From b41b9034225ab3e49980d9de55c141011b6383b0 Mon Sep 17 00:00:00 2001 From: Taru Karttunen Date: Wed, 30 Mar 2011 16:49:47 +0300 Subject: Import sources from 2011-03-30 iso image - sys/man --- sys/man/1/replica | 341 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100755 sys/man/1/replica (limited to 'sys/man/1/replica') diff --git a/sys/man/1/replica b/sys/man/1/replica new file mode 100755 index 000000000..2201c017a --- /dev/null +++ b/sys/man/1/replica @@ -0,0 +1,341 @@ +.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) -- cgit v1.2.3