342 lines
7 KiB
Text
342 lines
7 KiB
Text
|
.TH REPLICA 1
|
||
|
|
.SH NAME
|
||
|
|
changes, pull, push, scan \- client-server replica management
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.B replica/pull
|
||
|
|
[
|
||
|
|
.B -nv
|
||
|
|
]
|
||
|
|
[
|
||
|
|
.B -c
|
||
|
|
.I name
|
||
|
|
]...
|
||
|
|
[
|
||
|
|
.B -s
|
||
|
|
.I name
|
||
|
|
]...
|
||
|
|
.I name
|
||
|
|
[
|
||
|
|
.I path
|
||
|
|
...
|
||
|
|
]
|
||
|
|
.br
|
||
|
|
.B replica/push
|
||
|
|
[
|
||
|
|
.B -nv
|
||
|
|
]
|
||
|
|
.I name
|
||
|
|
[
|
||
|
|
.I path
|
||
|
|
...
|
||
|
|
]
|
||
|
|
.br
|
||
|
|
.B replica/changes
|
||
|
|
.I name
|
||
|
|
[
|
||
|
|
.I path
|
||
|
|
...
|
||
|
|
]
|
||
|
|
.br
|
||
|
|
.B replica/scan
|
||
|
|
.I name
|
||
|
|
[
|
||
|
|
.I path
|
||
|
|
...
|
||
|
|
]
|
||
|
|
.SH 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.
|
||
|
|
.PP
|
||
|
|
These scripts are a polished interface to the low-level tools described in
|
||
|
|
.IR replica (8).
|
||
|
|
See
|
||
|
|
.IR 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.
|
||
|
|
.PP
|
||
|
|
Replicas are described by configuration files.
|
||
|
|
The
|
||
|
|
.I name
|
||
|
|
in all the replica commands is a configuration
|
||
|
|
file. Paths that do not begin with
|
||
|
|
.BR / ,
|
||
|
|
.BR ./ ,
|
||
|
|
or
|
||
|
|
.B ../
|
||
|
|
are assumed to be relative to
|
||
|
|
.BR $home/lib/replica .
|
||
|
|
Configuration files are described below.
|
||
|
|
.PP
|
||
|
|
.I 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.
|
||
|
|
.PP
|
||
|
|
.I Replica/pull
|
||
|
|
copies changes from the server to the client,
|
||
|
|
while
|
||
|
|
.I replica/push
|
||
|
|
copies changes from the client to the server.
|
||
|
|
(Both run on the client.)
|
||
|
|
If a list of
|
||
|
|
.I paths
|
||
|
|
is given, only changes to those paths or their children are copied.
|
||
|
|
The
|
||
|
|
.B -v
|
||
|
|
flag causes
|
||
|
|
.I pull
|
||
|
|
or
|
||
|
|
.I push
|
||
|
|
to print a summary of what it is doing.
|
||
|
|
Each status line is of the form
|
||
|
|
.ift .sp 0.5
|
||
|
|
.ifn .sp
|
||
|
|
\h'0.25i'
|
||
|
|
.I verb
|
||
|
|
.I path
|
||
|
|
.I serverpath
|
||
|
|
.I mode
|
||
|
|
.I uid
|
||
|
|
.I gid
|
||
|
|
.I mtime
|
||
|
|
.I length
|
||
|
|
.ift .sp 0.5
|
||
|
|
.ifn .sp
|
||
|
|
.I Verb
|
||
|
|
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
|
||
|
|
is the file path on the server.
|
||
|
|
.IR Mode ,
|
||
|
|
.IR uid ,
|
||
|
|
.IR gid ,
|
||
|
|
and
|
||
|
|
.I mtime
|
||
|
|
are the file's 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.
|
||
|
|
The
|
||
|
|
.B -n
|
||
|
|
flag causes
|
||
|
|
.I pull
|
||
|
|
or
|
||
|
|
.I push
|
||
|
|
to print the summary but not actually carry out the actions.
|
||
|
|
.PP
|
||
|
|
.I Push
|
||
|
|
and
|
||
|
|
.I pull
|
||
|
|
are careful to notice simultaneous changes to a file or
|
||
|
|
its metadata on both client and server.
|
||
|
|
Such simultaneous changes are called
|
||
|
|
.IR 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
|
||
|
|
.I push
|
||
|
|
or
|
||
|
|
.IR pull ,
|
||
|
|
the next
|
||
|
|
.I push
|
||
|
|
or
|
||
|
|
.I pull
|
||
|
|
will report an update/update conflict.
|
||
|
|
If a conflict is detected, both files are left the same.
|
||
|
|
The
|
||
|
|
.B -c
|
||
|
|
flag to
|
||
|
|
.I pull
|
||
|
|
specifies that conflicts for paths beginning with
|
||
|
|
.I name
|
||
|
|
should be resolved using the client's copy,
|
||
|
|
while
|
||
|
|
.B -s
|
||
|
|
specifies the server's copy.
|
||
|
|
The
|
||
|
|
.B -c
|
||
|
|
and
|
||
|
|
.B -s
|
||
|
|
options may be repeated.
|
||
|
|
.PP
|
||
|
|
.I Replica/changes
|
||
|
|
prints a list of local changes made on the client
|
||
|
|
that have not yet been pushed to the server.
|
||
|
|
It is like
|
||
|
|
.I push
|
||
|
|
with the
|
||
|
|
.B -n
|
||
|
|
flag, except that it does not check for conflicts
|
||
|
|
and thus does not require the server to be available.
|
||
|
|
.PP
|
||
|
|
The replica configuration file is an
|
||
|
|
.IR rc (1)
|
||
|
|
script that must define the following functions and variables:
|
||
|
|
.TP
|
||
|
|
.B servermount
|
||
|
|
A function that mounts the server; run on both client and server.
|
||
|
|
.TP
|
||
|
|
.B 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
|
||
|
|
.I replica/scan
|
||
|
|
on that well-connected machine.
|
||
|
|
.TP
|
||
|
|
.B serverroot
|
||
|
|
The path to the root of the replicated file
|
||
|
|
system on the server, as it will be in the name space
|
||
|
|
after running
|
||
|
|
.BR servermount .
|
||
|
|
.TP
|
||
|
|
.B serverlog
|
||
|
|
The path to the server's change log, after running
|
||
|
|
.BR servermount .
|
||
|
|
.TP
|
||
|
|
.B serverproto
|
||
|
|
The path to the proto file describing the server's files,
|
||
|
|
after running
|
||
|
|
.BR servermount .
|
||
|
|
Only used by
|
||
|
|
.IR scan .
|
||
|
|
.TP
|
||
|
|
.B serverdb
|
||
|
|
The path to the server's file database, after running
|
||
|
|
.BR servermount .
|
||
|
|
Only used by
|
||
|
|
.IR scan .
|
||
|
|
.TP
|
||
|
|
.B clientmount
|
||
|
|
A function to mount the client file system; run only on the client.
|
||
|
|
.TP
|
||
|
|
.B clientroot
|
||
|
|
The path to the root of the replicated file system on the client,
|
||
|
|
after running
|
||
|
|
.BR clientmount .
|
||
|
|
.TP
|
||
|
|
.B clientlog
|
||
|
|
The path to the client's copy of the server log file.
|
||
|
|
The client log is maintained by
|
||
|
|
.IR pull .
|
||
|
|
.TP
|
||
|
|
.B clientproto
|
||
|
|
The path to the proto file describing the client's files.
|
||
|
|
Only used by
|
||
|
|
.IR changes .
|
||
|
|
Often just a copy of
|
||
|
|
.BR $serverproto .
|
||
|
|
.TP
|
||
|
|
.B clientdb
|
||
|
|
The path to the client's file database, after running
|
||
|
|
.BR clientmount .
|
||
|
|
.TP
|
||
|
|
.B 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.
|
||
|
|
.PD
|
||
|
|
.PP
|
||
|
|
As an example, the Plan 9 distribution replica configuration looks like:
|
||
|
|
.EX
|
||
|
|
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)
|
||
|
|
.EE
|
||
|
|
.PP
|
||
|
|
(Since the Plan 9 developers run
|
||
|
|
.I scan
|
||
|
|
manually to update the log, the clients need not do anything
|
||
|
|
to rescan the file system.
|
||
|
|
Thus
|
||
|
|
.B serverupdate
|
||
|
|
simply returns successfully.)
|
||
|
|
.PP
|
||
|
|
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
|
||
|
|
.BR /dist/replica .
|
||
|
|
To update your system, make sure you are connected
|
||
|
|
to the internet and run
|
||
|
|
.EX
|
||
|
|
replica/pull /dist/replica/network
|
||
|
|
.EE
|
||
|
|
If conflicts are reported (say you have made local changes to
|
||
|
|
.B /rc/bin/cpurc
|
||
|
|
and
|
||
|
|
.BR /rc/bin/termrc ,
|
||
|
|
but only want to keep the
|
||
|
|
.B cpurc
|
||
|
|
changes),
|
||
|
|
use
|
||
|
|
.EX
|
||
|
|
replica/pull -c rc/bin/cpurc -s rc/bin/termrc /dist/replica/network
|
||
|
|
.EE
|
||
|
|
to instruct
|
||
|
|
.I pull
|
||
|
|
to ignore the server's change to
|
||
|
|
.BR cpurc .
|
||
|
|
.PP
|
||
|
|
The script
|
||
|
|
.B /usr/glenda/bin/rc/pull
|
||
|
|
runs
|
||
|
|
.I pull
|
||
|
|
with the
|
||
|
|
.B -v
|
||
|
|
flag and with
|
||
|
|
.B /dist/replica/network
|
||
|
|
inserted at the right point on the command line.
|
||
|
|
Logged in as glenda, one can repeat the above example with:
|
||
|
|
.EX
|
||
|
|
pull -c rc/bin/cpurc -s rc/bin/termrc
|
||
|
|
.EE
|
||
|
|
.PP
|
||
|
|
To see a list of changes made to the local file system
|
||
|
|
since installation, run
|
||
|
|
.EX
|
||
|
|
replica/changes /dist/replica/network
|
||
|
|
.EE
|
||
|
|
(Although the script is called
|
||
|
|
.IR network ,
|
||
|
|
since
|
||
|
|
.I changes
|
||
|
|
is a local-only operation, the network need not be configured.)
|
||
|
|
.SH SOURCE
|
||
|
|
.B /rc/bin/replica
|
||
|
|
.SH SEE ALSO
|
||
|
|
.IR replica (8)
|