REPLICA(1)                                             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 applicability.  For example,
          they could be used to synchronize one's home directory
          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 rela-
          tive to $home/lib/replica.  Configuration 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 sys-
          tem 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.

          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

     Page 1                       Plan 9             (printed 3/28/24)

     REPLICA(1)                                             REPLICA(1)

          Dir structure (see stat(5)). For deletion events, the meta-
          data 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, simultane-
          ous 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 speci-
          fies 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 require 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.  Typi-
               cally 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 run-
               ning servermount.

          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.

     Page 2                       Plan 9             (printed 3/28/24)

     REPLICA(1)                                             REPLICA(1)

          serverdb
               The path to the server's file database, after running
               servermount.  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
               clientmount.

          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.

          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 boot }
              clientroot=/n/boot
              c=/n/boot/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 serverupdate simply returns successfully.)

     Page 3                       Plan 9             (printed 3/28/24)

     REPLICA(1)                                             REPLICA(1)

          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 /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
          installation, 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)

     Page 4                       Plan 9             (printed 3/28/24)