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 applicabil‐
ity. For example, they could be used to synchronize one's home direc‐
tory 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. Config‐
uration 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 sys‐
tem.
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
verb path serverpath mode uid gid mtime length 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 struc‐
ture (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 server‐
mount.
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 server‐
mount. 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 client‐
mount.
clientexclude
A (potentially empty) list of paths to exclude from synchroniza‐
tion. 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 kfs }
clientroot=/n/kfs
c=/n/kfs/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 serverup‐
date simply returns successfully.)
The fourth edition Plan 9 distribution uses these tools to synchronize
installations with the central server at Bell Labs. The replica con‐
figuration 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 installa‐
tion, 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 ALSOreplica(8)REPLICA(1)
