sys/man/1/replica

   1 .TH REPLICA 1
   2 .SH NAME
   3 changes, pull, push, scan \- client-server replica management
   4 .SH SYNOPSIS
   5 .B replica/pull
   6 [
   7 .B -nv
   8 ]
   9 [
  10 .B -c
  11 .I name
  12 ]...
  13 [
  14 .B -s
  15 .I name
  16 ]...
  17 .I name
  18 [
  19 .I path
  20 ...
  21 ]
  22 .br
  23 .B replica/push
  24 [
  25 .B -nv
  26 ]
  27 .I name
  28 [
  29 .I path
  30 ...
  31 ]
  32 .br
  33 .B replica/changes
  34 .I name
  35 [
  36 .I path
  37 ...
  38 ]
  39 .br
  40 .B replica/scan
  41 .I name
  42 [
  43 .I path
  44 ...
  45 ]
  46 .SH DESCRIPTION
  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.
  50 .PP
  51 These scripts are a polished interface to the low-level tools described in
  52 .IR replica (8).
  53 See
  54 .IR replica (8)
  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.
  61 .PP
  62 Replicas are described by configuration files.
  63 The
  64 .I name
  65 in all the replica commands is a configuration
  66 file.  Paths that do not begin with
  67 .BR / ,
  68 .BR ./ ,
  69 or
  70 .B ../
  71 are assumed to be relative to
  72 .BR $home/lib/replica .
  73 Configuration files are described below.
  74 .PP
  75 .I Replica/scan
  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.
  82 .PP
  83 .I Replica/pull
  84 copies changes from the server to the client,
  85 while
  86 .I replica/push
  87 copies changes from the client to the server.
  88 (Both run on the client.)
  89 If a list of
  90 .I paths
  91 is given, only changes to those paths or their children are copied.
  92 The
  93 .B -v
  94 flag causes
  95 .I pull
  96 or
  97 .I push
  98 to print a summary of what it is doing.
  99 Each status line is of the form
 100 .ift .sp 0.5
 101 .ifn .sp
 102 \h'0.25i'
 103 .I verb
 104 .I path
 105 .I serverpath
 106 .I mode
 107 .I uid
 108 .I gid
 109 .I mtime
 110 .I length
 111 .ift .sp 0.5
 112 .ifn .sp
 113 .I Verb
 114 describes the event:
 115 addition of a file
 116 .RB ( a ),
 117 deletion of a file
 118 .RB ( d ),
 119 a change to a file's contents
 120 .RB ( c ),
 121 or a change to a file's metadata
 122 .RB ( m ).
 123 .I Path
 124 is the file path on the client;
 125 .I serverpath
 126 is the file path on the server.
 127 .IR Mode ,
 128 .IR uid ,
 129 .IR gid ,
 130 and
 131 .I mtime
 132 are the file's metadata as in the
 133 .B Dir
 134 structure (see
 135 .IR stat (5)).
 136 For deletion events, the metadata is that of the deleted file.
 137 For other events, the metadata is that after the event.
 138 The
 139 .B -n
 140 flag causes
 141 .I pull
 142 or
 143 .I push
 144 to print the summary but not actually carry out the actions.
 145 .PP
 146 .I Push
 147 and
 148 .I pull
 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
 152 .IR conflicts .
 153 Here, simultaneous does not mean at the same instant
 154 but merely that both changes were carried out without knowledge
 155 of the other.
 156 For example, if a client and server both make changes to a file
 157 without an intervening
 158 .I push
 159 or
 160 .IR pull ,
 161 the next
 162 .I push
 163 or
 164 .I pull
 165 will report an update/update conflict.
 166 If a conflict is detected, both files are left the same.
 167 The
 168 .B -c
 169 flag to
 170 .I pull
 171 specifies that conflicts for paths beginning with
 172 .I name
 173 should be resolved using the client's copy,
 174 while
 175 .B -s
 176 specifies the server's copy.
 177 The
 178 .B -c
 179 and
 180 .B -s
 181 options may be repeated.
 182 .PP
 183 .I Replica/changes
 184 prints a list of local changes made on the client
 185 that have not yet been pushed to the server.
 186 It is like
 187 .I push
 188 with the
 189 .B -n
 190 flag, except that it does not check for conflicts
 191 and thus does not require the server to be available.
 192 .PP
 193 The replica configuration file is an
 194 .IR rc (1)
 195 script that must define the following functions and variables:
 196 .TP
 197 .B servermount
 198 A function that mounts the server; run on both client and server.
 199 .TP
 200 .B serverupdate
 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
 204 .I replica/scan
 205 on that well-connected machine.
 206 .TP
 207 .B serverroot
 208 The path to the root of the replicated file
 209 system on the server, as it will be in the name space
 210 after running
 211 .BR servermount .
 212 .TP
 213 .B serverlog
 214 The path to the server's change log, after running
 215 .BR servermount .
 216 .TP
 217 .B serverproto
 218 The path to the proto file describing the server's files,
 219 after running
 220 .BR servermount .
 221 Only used by
 222 .IR scan .
 223 .TP
 224 .B serverdb
 225 The path to the server's file database, after running
 226 .BR servermount .
 227 Only used by
 228 .IR scan .
 229 .TP
 230 .B clientmount
 231 A function to mount the client file system; run only on the client.
 232 .TP
 233 .B clientroot
 234 The path to the root of the replicated file system on the client,
 235 after running
 236 .BR clientmount .
 237 .TP
 238 .B clientlog
 239 The path to the client's copy of the server log file.
 240 The client log is maintained by
 241 .IR pull .
 242 .TP
 243 .B clientproto
 244 The path to the proto file describing the client's files.
 245 Only used by
 246 .IR changes .
 247 Often just a copy of
 248 .BR $serverproto .
 249 .TP
 250 .B clientdb
 251 The path to the client's file database, after running
 252 .BR clientmount .
 253 .TP
 254 .B clientexclude
 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.
 259 .PD
 260 .PP
 261 As an example, the Plan 9 distribution replica configuration looks like:
 262 .EX
 263     fn servermount { 9fs sources; bind /n/sources/plan9 /n/dist }
 264     fn serverupdate { status='' }
 265     serverroot=/n/dist
 266     s=/n/dist/dist/replica
 267     serverlog=$s/plan9.log
 268     serverproto=$s/plan9.proto
 269
 270     fn clientmount { 9fs boot }
 271     clientroot=/n/boot
 272     c=/n/boot/dist/replica
 273     clientlog=$c/client/plan9.log
 274     clientproto=$c/plan9.proto
 275     clientdb=$c/client/plan9.db
 276     clientexclude=(dist/replica/client)
 277 .EE
 278 .PP
 279 (Since the Plan 9 developers run
 280 .I scan
 281 manually to update the log, the clients need not do anything
 282 to rescan the file system.
 283 Thus
 284 .B serverupdate
 285 simply returns successfully.)
 286 .PP
 287 The fourth edition Plan 9 distribution uses these
 288 tools to synchronize installations with the central
 289 server at Bell Labs.
 290 The replica configuration files and metadata are kept
 291 in
 292 .BR /dist/replica .
 293 To update your system, make sure you are connected
 294 to the internet and run
 295 .EX
 296     replica/pull /dist/replica/network
 297 .EE
 298 If conflicts are reported (say you have made local changes to
 299 .B /rc/bin/cpurc
 300 and
 301 .BR /rc/bin/termrc ,
 302 but only want to keep the
 303 .B cpurc
 304 changes),
 305 use
 306 .EX
 307     replica/pull -c rc/bin/cpurc -s rc/bin/termrc /dist/replica/network
 308 .EE
 309 to instruct
 310 .I pull
 311 to ignore the server's change to
 312 .BR cpurc .
 313 .PP
 314 The script
 315 .B /usr/glenda/bin/rc/pull
 316 runs
 317 .I pull
 318 with the
 319 .B -v
 320 flag and with
 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:
 324 .EX
 325     pull -c rc/bin/cpurc -s rc/bin/termrc
 326 .EE
 327 .PP
 328 To see a list of changes made to the local file system
 329 since installation, run
 330 .EX
 331     replica/changes /dist/replica/network
 332 .EE
 333 (Although the script is called
 334 .IR network ,
 335 since
 336 .I changes
 337 is a local-only operation, the network need not be configured.)
 338 .SH SOURCE
 339 .B /rc/bin/replica
 340 .SH SEE ALSO
 341 .IR replica (8)