3 changes, pull, push, scan \- client-server replica management
47 These shell scripts provide a simple log-based client-server replica management.
48 The server keeps a log of changes made to its file system,
49 and clients synchronize by reading the log and applying these changes locally.
51 These scripts are a polished interface to the low-level tools described in
55 for details on the inner workings of replica management.
56 These tools were written primarily as the fourth
57 edition Plan 9 distribution mechanism, but they
58 have wider applicability.
59 For example, they could be used to synchronize one's
60 home directory between a laptop and a central file server.
62 Replicas are described by configuration files.
65 in all the replica commands is a configuration
66 file. Paths that do not begin with
71 are assumed to be relative to
72 .BR $home/lib/replica .
73 Configuration files are described below.
76 is the only one of these programs that does not
77 need to be run on the client.
78 It scans the server file system for changes
79 and appends entries for those changes into the server log.
80 Typically it is run on a machine with a fast network
81 connection to the server file system.
84 copies changes from the server to the client,
87 copies changes from the client to the server.
88 (Both run on the client.)
91 is given, only changes to those paths or their children are copied.
98 to print a summary of what it is doing.
99 Each status line is of the form
119 a change to a file's contents
121 or a change to a file's metadata
124 is the file path on the client;
126 is the file path on the server.
132 are the file's metadata as in the
136 For deletion events, the metadata is that of the deleted file.
137 For other events, the metadata is that after the event.
144 to print the summary but not actually carry out the actions.
149 are careful to notice simultaneous changes to a file or
150 its metadata on both client and server.
151 Such simultaneous changes are called
153 Here, simultaneous does not mean at the same instant
154 but merely that both changes were carried out without knowledge
156 For example, if a client and server both make changes to a file
157 without an intervening
165 will report an update/update conflict.
166 If a conflict is detected, both files are left the same.
171 specifies that conflicts for paths beginning with
173 should be resolved using the client's copy,
176 specifies the server's copy.
181 options may be repeated.
184 prints a list of local changes made on the client
185 that have not yet been pushed to the server.
190 flag, except that it does not check for conflicts
191 and thus does not require the server to be available.
193 The replica configuration file is an
195 script that must define the following functions and variables:
198 A function that mounts the server; run on both client and server.
201 A function that rescans the server for changes.
202 Typically this command dials a CPU server known
203 to be close to the file server and runs
205 on that well-connected machine.
208 The path to the root of the replicated file
209 system on the server, as it will be in the name space
214 The path to the server's change log, after running
218 The path to the proto file describing the server's files,
225 The path to the server's file database, after running
231 A function to mount the client file system; run only on the client.
234 The path to the root of the replicated file system on the client,
239 The path to the client's copy of the server log file.
240 The client log is maintained by
244 The path to the proto file describing the client's files.
251 The path to the client's file database, after running
255 A (potentially empty) list of paths to exclude from
256 synchronization. A typical use of this is to exclude
257 the client database and log files.
258 These paths are relative to the root of the replicated file system.
261 As an example, the Plan 9 distribution replica configuration looks like:
263 fn servermount { 9fs sources; bind /n/sources/plan9 /n/dist }
264 fn serverupdate { status='' }
266 s=/n/dist/dist/replica
267 serverlog=$s/plan9.log
268 serverproto=$s/plan9.proto
270 fn clientmount { 9fs kfs }
272 c=/n/kfs/dist/replica
273 clientlog=$c/client/plan9.log
274 clientproto=$c/plan9.proto
275 clientdb=$c/client/plan9.db
276 clientexclude=(dist/replica/client)
279 (Since the Plan 9 developers run
281 manually to update the log, the clients need not do anything
282 to rescan the file system.
285 simply returns successfully.)
287 The fourth edition Plan 9 distribution uses these
288 tools to synchronize installations with the central
290 The replica configuration files and metadata are kept
293 To update your system, make sure you are connected
294 to the internet and run
296 replica/pull /dist/replica/network
298 If conflicts are reported (say you have made local changes to
302 but only want to keep the
307 replica/pull -c rc/bin/cpurc -s rc/bin/termrc /dist/replica/network
311 to ignore the server's change to
315 .B /usr/glenda/bin/rc/pull
321 .B /dist/replica/network
322 inserted at the right point on the command line.
323 Logged in as glenda, one can repeat the above example with:
325 pull -c rc/bin/cpurc -s rc/bin/termrc
328 To see a list of changes made to the local file system
329 since installation, run
331 replica/changes /dist/replica/network
333 (Although the script is called
337 is a local-only operation, the network need not be configured.)