REPL(8)                                                   REPL(8)

     NAME
          prune, scandb, syncdb - peer to peer replica management

     SYNOPSIS
          repl/prune repl...
          repl/scandb [ -tv ] [ -p nb ] [ -n id ] [ -r replid ] [ -i
          excldir ] dir db
          repl/syncdb [ -12lnrv ] dir1 dir2 db1 db2 [ dir... ]

     DESCRIPTION
          These programs implement a peer-to-peer replica management
          system for file trees. Each peer is called a replica and
          holds both the replicated file tree and a data base. The
          data base contains a textual representation of the file tree
          together with the history of updates for each file as
          described below.  Any number of replicas can be defined and
          any pair can be synchronized at any time. There is no cen-
          tralized server nor there is a synchronization order
          required to detect conflicts.

          Replication is done using causal histories as defined by
          Lamport.  Each file entry in the data base holds a history
          of change events.  When a replica creates, changes, or
          deletes a file, a change event is added to the file's his-
          tory. A change event is a single character that identifies
          the replica that did the change. The character is lower case
          for creation, data changes, and metadata changes. The char-
          acter is upper case for deletion events.

          To synchronize a file between two replicas, their histories
          for the file are compared. The file is considered up to date
          if the histories are equal. If one of them is a prefix of
          the other, it is considered out of date with respect to the
          other. In this case the file and its history are updated in
          the other replica. If the histories differ, but no one is a
          prefix of the other, there was a concurrent update and a
          conflict is reported.

          Scandb is used to scan the file tree at dir for changes. It
          builds a new data base that corresponds to the tree in disk
          and compares it with db. The program prunes from the scan
          process any directory not modified since the last scan per-
          formed. Flag -t disables such prunning and is intended for
          use in file systems that do not propagate modification times
          from the changed file up to the root directory of the file
          system.

          The history for a file in the new data base is that found in
          db perhaps followed by a change event (when the file has
          changed).

     REPL(8)                                                   REPL(8)

          Option -n can be used when there is no db file. This happens
          when defining a new replica.  The option argument is the
          name for the replica and must be a lower case letter. The
          change histories in the new data base will contain a single
          event (a change in the replica being defined).

          Option -r can be used to define a new replica with name
          replid while creating an initial data base for name id. This
          is useful to build a data base for an already updated
          replica that has been copied by other means. See the example
          below.

          Flag -v makes the program verbose. It will report any change
          event noticed.

          To ignore a directory give its name to option -i using an
          relative path name starting at the replica directory.  The
          directory contents will be ignored. The option can be used
          multiple times to ignore multiple directories. Be careful to
          give the same ignore arguments to all the replicas.

          To prune the history, you can use -p and pass the identifier
          (a number) for the prune event. Such identifier must be used
          at all the replicas. See the discussion below.

          Syncdb is used to synchronize replicas. Its arguments are
          the two directories and data bases for the replicas being
          synchronized.  Syncdb operates as said above to detect
          updates and conflicts. It copies, creates, and deletes files
          to bring both replicas to a synchronized state. If any dir
          is supplied, relative to the top-dir of a replica, synchro-
          nization applies only to it.

          Flag -v makes the program report any change made. Flag -n
          performs a dry run to report changes between both replicas
          without synchronizing them.  The flag -l can be used to syn-
          crhonize just the left replica (in command line order) with
          respect to the other. Flag -r does the same for the right
          replica.

          Flags -1 and -2 can be used to resolve conflicts in favor of
          the first replica (the left one) and in favor of the second
          one (the right one).  When there are different conflicts to
          be gained by different replicas, one replica can be updated
          by hand, and then used as the prefered to settle down all
          the conflicts.

          To prune file histories follow this procedure.

          1    Be sure that all the peers are synchronized.

          2    Use prune to prune all the peers. You can pass the

     REPL(8)                                                   REPL(8)

               names for all the repl configuration files.

          This program calls scandb for each replica using the -p
          flag. The effect is to remove all but the last event in the
          histories for files within the database.  Any other proce-
          dure would be very costly or complex, because it would
          require finding the maximum common prefix for each history
          and removing it from all the replicas.

          Database files are exclusive-open text files that contain
          the replica identifier in the first line, followed by one
          line per file entry.  Each entry contains the file name, the
          update history, the user and group identifers, file permis-
          sions (8 hex digits), modification time (8 hex digits), file
          length (decimal), and Qid version. The file name starts with
          '/' and is relative to the top directory of the replicated
          file tree. All fields are separated by space. Entries for
          deleted files have their history terminated on uppercase.

     EXAMPLE
          This defines for the system file tree, excluding /usr and
          /dist, a replica called a.  The same is done for /usr/nemo
          excluding the directory /usr/nemo/dist and /usr/nemo/tmp.
               ; repl/scandb -n a -i usr -i dist /root /dist/sys.db
               ; repl/scandb -n a -i tmp -i dist $home $home/dist/home.db

          Now we can replicate both the system and /usr/nemo into a
          new laptop by defining two replicas, named b, and synchro-
          nizing them.
               # at the laptop, booted from the network.
               ; mount -c /dev/sdC0/fossil /n/fossil
               ; repl/scandb -n b /n/fossil /dist/nautilus.db
               ; replica/syncdb /root /fossil /dist/sys.db /dist/nautilus.db
               ; mkdir /fossil/$home /fossil/$home/dist
               ; repl/scandb -n b -i tmp -i dist /fossil/$home $home/dist/laptop.db
               ; replica/syncdb (/ /fossil)^$home $home/dist/^(home.db laptop.db)

     SOURCE
          /sys/src/cmd/repl

     SEE ALSO
          repl(1), replica(1).

     BUGS
          Append only files are not synchronized to prevent duplica-
          tion of file contents.