glenda.party
term% ls -F
term% cat index.txt
REPLICA(1)                  General Commands Manual                 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 ap‐
       pends 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 re‐
       quire 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 ALSO
       replica(8)



                                                                    REPLICA(1)