317 lines
6.2 KiB
Plaintext
317 lines
6.2 KiB
Plaintext
.TH REPLICA 8
|
|
.SH NAME
|
|
applychanges, applylog, compactdb, updatedb \- simple client-server replica management
|
|
.SH SYNOPSIS
|
|
.B replica/compactdb
|
|
.I db
|
|
.br
|
|
.B replica/updatedb
|
|
[
|
|
.B -cl
|
|
]
|
|
[
|
|
.B -p
|
|
.I proto
|
|
]
|
|
[
|
|
.B -r
|
|
.I root
|
|
]
|
|
[
|
|
.B -t
|
|
.I now
|
|
.I n
|
|
]
|
|
[
|
|
.B -u
|
|
.I uid
|
|
]
|
|
[
|
|
.B -x
|
|
.I path
|
|
] ...
|
|
.I db
|
|
.br
|
|
.B replica/applylog
|
|
[
|
|
.B -nuv
|
|
]
|
|
[
|
|
.B -c
|
|
.I name
|
|
]...
|
|
[
|
|
.B -s
|
|
.I name
|
|
]...
|
|
.I clientdb
|
|
.I clientroot
|
|
.I serverroot
|
|
[
|
|
.I path ...
|
|
]
|
|
.br
|
|
.B replica/applychanges
|
|
[
|
|
.B -nuv
|
|
]
|
|
[
|
|
.B -p
|
|
.I proto
|
|
]
|
|
[
|
|
.B -x
|
|
.I path
|
|
] ...
|
|
.I clientdb
|
|
.I clientroot
|
|
.I serverroot
|
|
[
|
|
.I path ...
|
|
]
|
|
.SH DESCRIPTION
|
|
These four tools collectively provide simple log-based
|
|
client-server replica management.
|
|
The shell scripts described in
|
|
.IR replica (1)
|
|
provide a more polished interface.
|
|
.PP
|
|
Both client and server maintain textual databases of file system
|
|
metadata. Each line is of the form
|
|
.ift .sp 0.5
|
|
.ifn .sp
|
|
\h'0.25i'
|
|
.I path
|
|
.I mode
|
|
.I uid
|
|
.I gid
|
|
.I mtime
|
|
.I length
|
|
.ift .sp 0.5
|
|
.ifn .sp
|
|
Later entries for a
|
|
.I path
|
|
supersede previous ones.
|
|
A line with the string
|
|
.B REMOVED
|
|
in the
|
|
.I mode
|
|
field annuls all previous entries for that
|
|
.IR path .
|
|
The entries in a file are typically kept sorted by
|
|
.I path
|
|
but need not be.
|
|
These properties facilitate updating the database atomically
|
|
by appending to it.
|
|
.I Compactdb
|
|
reads in a database and writes out an equivalent one,
|
|
sorted by path and without outdated or annulled records.
|
|
.PP
|
|
A replica is further described on the server by a textual
|
|
log listing creation and deletion of files and changes
|
|
to file contents and metadata.
|
|
Each line is of the form:
|
|
.ift .sp 0.5
|
|
.ifn .sp
|
|
\h'0.25i'
|
|
.I time
|
|
.I gen
|
|
.I verb
|
|
.I path
|
|
.I serverpath
|
|
.I mode
|
|
.I uid
|
|
.I gid
|
|
.I mtime
|
|
.I length
|
|
.ift .sp 0.5
|
|
.ifn .sp
|
|
The
|
|
.I time
|
|
and
|
|
.I gen
|
|
fields are both decimal numbers, providing an ordering
|
|
for log entries so that incremental tools need not process
|
|
the whole log each time they are run.
|
|
The
|
|
.IR verb ,
|
|
a single character,
|
|
describes the event:
|
|
addition of a file
|
|
.RB ( a ),
|
|
deletion of a file
|
|
.RB ( d ),
|
|
a change to a file's contents
|
|
.RB ( c ),
|
|
or a change to a file's metadata
|
|
.RB ( m ).
|
|
.I Path
|
|
is the file path on the client;
|
|
.I serverpath
|
|
the path on the server (these are different when the
|
|
optional fifth field in a proto file line is given;
|
|
see
|
|
.IR proto (2)).
|
|
.IR Mode ,
|
|
.IR uid ,
|
|
.IR gid ,
|
|
and
|
|
.I mtime
|
|
are the files metadata as in the
|
|
.B Dir
|
|
structure (see
|
|
.IR stat (5)).
|
|
For deletion events, the metadata is that of the deleted file.
|
|
For other events, the metadata is that after the event.
|
|
.PP
|
|
.I Updatedb
|
|
scans the file system rooted at
|
|
.I root
|
|
for changes not present in
|
|
.IR db ,
|
|
noting them by appending new entries to the database
|
|
and by writing log events to standard output.
|
|
The
|
|
.B -c
|
|
option causes
|
|
.I updatedb
|
|
to consider only file and metadata changes, ignoring file additions and deletions.
|
|
By default, the log events have
|
|
.I time
|
|
set to the current system time
|
|
and use incrementing
|
|
.I gen
|
|
numbers starting at 0.
|
|
The
|
|
.B -t
|
|
option can be used to specify a different time and starting number.
|
|
If the
|
|
.B -u
|
|
option is given, all database entries and log events will use
|
|
.I uid
|
|
rather than the actual uids.
|
|
The
|
|
.B -x
|
|
option (which may be specified multiple times) excludes the named path
|
|
and all its children from the scan.
|
|
If the
|
|
.B -l
|
|
option is given, the database is not changed and the
|
|
.I time
|
|
and
|
|
.I gen
|
|
fields are omitted from the log events;
|
|
the resulting output is intended to be a human-readable
|
|
summary of file system activity since the last scan.
|
|
.PP
|
|
.I Applylog
|
|
is used to propagate changes from server to client.
|
|
It applies the changes listed in a log
|
|
(read from standard input)
|
|
to the file system rooted at
|
|
.IR clientroot ,
|
|
copying files when necessary from the file system rooted at
|
|
.IR serverroot .
|
|
By default,
|
|
.I applylog
|
|
does not attempt to set the uid on files; the
|
|
.B -u
|
|
flag enables this.
|
|
.I Applylog
|
|
will not overwrite local changes made to replicated files.
|
|
When it detects such conflicts, by default it prints an error describing
|
|
the conflict and takes no action.
|
|
If the
|
|
.B -c
|
|
flag is given,
|
|
.I applylog
|
|
still takes no action for files beginning with the given names,
|
|
but does so silently and will not
|
|
report the conflicts in the future.
|
|
(The conflict is resolved in favor of the client.)
|
|
The
|
|
.B -s
|
|
is similar but causes
|
|
.I applylog
|
|
to overwrite the local changes.
|
|
(The conflict is resolved in favor of the server.)
|
|
.PP
|
|
.I Applychanges
|
|
is, in some sense, the opposite of
|
|
.IR applylog ;
|
|
it scans the client file system for changes, and applies
|
|
those changes to the server file system.
|
|
.I Applychanges
|
|
will not overwrite remote changes made to replicated files.
|
|
For example, if a file is copied from server to client and subsequently
|
|
changed on both server and client,
|
|
.I applychanges
|
|
will not copy the client's new version to the server, because
|
|
the server also has a new version.
|
|
.I Applychanges
|
|
and
|
|
.I applylog
|
|
detect the same conflicts; to resolve conflicts reported by
|
|
.IR applychanges ,
|
|
invoke
|
|
.I applylog
|
|
with the
|
|
.B -c
|
|
or
|
|
.B -s
|
|
flags.
|
|
.SH EXAMPLE
|
|
One might
|
|
keep a client kfs file system up-to-date
|
|
against a server file system using these tools.
|
|
First, connect to a CPU server with a high-speed
|
|
network connection to the file server and scan
|
|
the server file system, updating the server database and log:
|
|
.EX
|
|
repl=$home/lib/replica
|
|
proto=/sys/lib/sysconfig/proto/portproto
|
|
db=$repl/srv.portproto.db
|
|
log=$repl/srv.portproto.log
|
|
|
|
9fs $fs
|
|
replica/updatedb -p $proto -r /n/$fs -x $repl $db >>$log
|
|
replica/compactdb $db >/tmp/a && mv /tmp/a $db
|
|
.EE
|
|
.PP
|
|
Then, update the client file system:
|
|
.EX
|
|
repl=$home/lib/replica
|
|
db=$repl/cli.portproto.db
|
|
log=$repl/srv.portproto.log
|
|
|
|
9fs $fs
|
|
9fs kfs
|
|
replica/applylog $db /n/kfs /n/$fs <$log
|
|
replica/compactdb $db >/tmp/a && mv /tmp/a $db
|
|
.EE
|
|
.PP
|
|
The
|
|
.B $repl
|
|
directory is excluded from the sync so that multiple
|
|
clients can each have their own local database.
|
|
The shell scripts in
|
|
.B /rc/bin/replica
|
|
are essentially a further development of this example.
|
|
.PP
|
|
The Plan 9 distribution update program
|
|
operates similarly, but omits the first scan;
|
|
it is assumed that the Plan 9 developers run
|
|
scans manually when the distribution
|
|
file system changes.
|
|
The manual page
|
|
.IR replica (1)
|
|
describes this in full.
|
|
.SH SEE ALSO
|
|
.IR replica (1)
|
|
.SH BUGS
|
|
These tools assume that
|
|
.I mtime
|
|
combined with
|
|
.I length
|
|
is a good indicator of changes to a file's contents.
|