REPLICA(1)REPLICA(1)
NAME
changes, pull, push, scan – client-server replica management
SYNOPSIS
replica/pull
[
-nv
]
[
-c
name
]...
[
-s
name
]...
name
[
path
...
]
replica/push
[
-nv
]
name
[
path
...
]
replica/changes
name
[
path
...
]
replica/scan
name
[
path
...
]
DESCRIPTION
These shell scripts provide a simple log-based client-server replica management.
The server keeps a log of changes made to its file system,
and clients synchronize by reading the log and applying these changes locally.
These scripts are a polished interface to the low-level tools described in
replica(8).
See
replica(8)
for details on the inner workings of replica management.
These tools were written primarily as the fourth
edition Plan 9 distribution mechanism, but they
have wider applicability.
For example, they could be used to synchronize one’s
home directory between a laptop and a central file server.
Replicas are described by configuration files.
The
name
in all the replica commands is a configuration
file. Paths that do not begin with
/,
./,
or
../
are assumed to be relative to
$home/lib/replica.
Configuration files are described below.
Replica/scan
is the only one of these programs that does not
need to be run on the client.
It scans the server file system for changes
and appends entries for those changes into the server log.
Typically it is run on a machine with a fast network
connection to the server file system.
Replica/pull
copies changes from the server to the client,
while
replica/push
copies changes from the client to the server.
(Both run on the client.)
If a list of
paths
is given, only changes to those paths or their children are copied.
The
-v
flag causes
pull
or
push
to print a summary of what it is doing.
Each status line is of the form
unhandled troff command .ift
unhandled troff command .ifn
\h’0.25i’
verb
path
serverpath
mode
uid
gid
mtime
length
unhandled troff command .ift
unhandled troff command .ifn
Verb
describes the event:
addition of a file
(a),
deletion of a file
(d),
a change to a file’s contents
(c),
or a change to a file’s metadata
(m).
Path
is the file path on the client;
serverpath
is the file path on the server.
Mode,
uid,
gid,
and
mtime
are the file’s metadata as in the
Dir
structure (see
stat(5)).
For deletion events, the metadata is that of the deleted file.
For other events, the metadata is that after the event.
The
-n
flag causes
pull
or
push
to print the summary but not actually carry out the actions.
Push
and
pull
are careful to notice simultaneous changes to a file or
its metadata on both client and server.
Such simultaneous changes are called
conflicts.
Here, simultaneous does not mean at the same instant
but merely that both changes were carried out without knowledge
of the other.
For example, if a client and server both make changes to a file
without an intervening
push
or
pull,
the next
push
or
pull
will report an update/update conflict.
If a conflict is detected, both files are left the same.
The
-c
flag to
pull
specifies that conflicts for paths beginning with
name
should be resolved using the client’s copy,
while
-s
specifies the server’s copy.
The
-c
and
-s
options may be repeated.
Replica/changes
prints a list of local changes made on the client
that have not yet been pushed to the server.
It is like
push
with the
-n
flag, except that it does not check for conflicts
and thus does not require the server to be available.
The replica configuration file is an
rc(1)
script that must define the following functions and variables:
servermount
A function that mounts the server; run on both client and server.
serverupdate
A function that rescans the server for changes.
Typically this command dials a CPU server known
to be close to the file server and runs
replica/scan
on that well-connected machine.
serverroot
The path to the root of the replicated file
system on the server, as it will be in the name space
after running
servermount.
serverlog
The path to the server’s change log, after running
servermount.
serverproto
The path to the proto file describing the server’s files,
after running
servermount.
Only used by
scan.
serverdb
The path to the server’s file database, after running
servermount.
Only used by
scan.
clientmount
A function to mount the client file system; run only on the client.
clientroot
The path to the root of the replicated file system on the client,
after running
clientmount.
clientlog
The path to the client’s copy of the server log file.
The client log is maintained by
pull.
clientproto
The path to the proto file describing the client’s files.
Only used by
changes.
Often just a copy of
$serverproto.
clientdb
The path to the client’s file database, after running
clientmount.
clientexclude
A (potentially empty) list of paths to exclude from
synchronization. A typical use of this is to exclude
the client database and log files.
These paths are relative to the root of the replicated file system.
As an example, the Plan 9 distribution replica configuration looks like:
fn servermount { 9fs sources; bind /n/sources/plan9 /n/dist }
fn serverupdate { status='' }
serverroot=/n/dist
s=/n/dist/dist/replica
serverlog=$s/plan9.log
serverproto=$s/plan9.proto
fn clientmount { 9fs boot }
clientroot=/n/boot
c=/n/boot/dist/replica
clientlog=$c/client/plan9.log
clientproto=$c/plan9.proto
clientdb=$c/client/plan9.db
clientexclude=(dist/replica/client)
(Since the Plan 9 developers run
scan
manually to update the log, the clients need not do anything
to rescan the file system.
Thus
serverupdate
simply returns successfully.)
The fourth edition Plan 9 distribution uses these
tools to synchronize installations with the central
server at Bell Labs.
The replica configuration files and metadata are kept
in
/dist/replica.
To update your system, make sure you are connected
to the internet and run
replica/pull /dist/replica/network
If conflicts are reported (say you have made local changes to
/rc/bin/cpurc
and
/rc/bin/termrc,
but only want to keep the
cpurc
changes),
use
replica/pull -c rc/bin/cpurc -s rc/bin/termrc /dist/replica/network
to instruct
pull
to ignore the server’s change to
cpurc.
The script
/usr/glenda/bin/rc/pull
runs
pull
with the
-v
flag and with
/dist/replica/network
inserted at the right point on the command line.
Logged in as glenda, one can repeat the above example with:
pull -c rc/bin/cpurc -s rc/bin/termrc
To see a list of changes made to the local file system
since installation, run
replica/changes /dist/replica/network
(Although the script is called
network,
since
changes
is a local-only operation, the network need not be configured.)
SOURCE
/rc/bin/replica
SEE
replica(8)