sourCEntral - mobile manpages

pdf

TRA

NAME

minisync, tramkdb, trascan, trasrv, trafixdb − unidirectional replica synchronization

SYNOPSIS

minisync [ -Anftv ] [ -z n ] src dst [ paths ]

trascan replica [ paths ]

tramkdb dbfile replicaname

trasrv [ -i ifile ] [ -o option ] dbfile root

trafixdb -l

trafixdb [ -n ] dbfile [ outdbfile ]

DESCRIPTION

Tra is a file system synchronizer. It helps to manage the replication of a shared file system on many hosts, automatically propagating updates when possible. The file system is optimistically replicated: any replica is allowed to make any change at any time. Changes are propagated via pairwise synchronization between replicas. Incomptible changes, called conflicts, are reported to the user for manual resolution.

Minisync
Minisync
tracks the modification history of each file as it is changed and copied from replica to replica. The replica names on the command line are executable files, typically shell scripts, that run trasrv with appropriate arguments. Replica names are further described a few paragraphs later in this section.

The synchronization of a single file proceeds as follows (this is a description of the behavior, not the implementation):

1.

If the history of the file on src is a prefix of or equal to the history on dst, then dst is up-to-date; do nothing.

2.

If the history of the file on dst is a prefix of the history of the file on src, the file on src is propagated to dst.

3.

If neither history is a prefix of the other, the two files have diverged. Report a conflict.

Creation or deletion of a file is considered an event in the history of a file. Conflict names take the form action/action, indicating how the histories have diverged; the first action corresponds to the file on src and the second action corresponds to the file on dst. Action is one of update, create, or delete. For example, an update/delete conflict indicates that since the files on src and dst diverged, the file on src has been updated but the file on dst has been deleted. Of course, these changes might have occurred on other replicas and propagated to src and dst.

Minisync performs a undirectional synchronization, propagating updates from the replica src to the replica dst. If paths are specified, the synchronization is limited to files and directories in the trees rooted at those paths. If no path is specified, the entire replica is synchronized.

The options are:

-A

By default, when two identical files are in conflict, the conflict is automatically resolved. The -A flag turns this auto-resolution off.

-n

Do nothing. Print what would be done.

-f

Resolve all conflicts in favor of the src (from) replica.

-t

Resolve all conflicts in favor of the dst (to) replica.

-v

Verbose; print file system operations as they are carried out.

-z

Set deflate compression level, from 1 to 9.

The arguments src and dst are named by executables that establish connections to trasrv(8). If a replica name does not begin with ./, ../, or /, it is prefixed with the path $home/lib/tra (on Plan 9) or $HOME/.tra (on Unix).

If the file $home/lib/tra/minisync.log (on Plan 9) or $HOME/.tra/minisync.log (on Unix) exists, minisync appends a log of its actions to the file.

Tramkdb
File histories are kept in an on-disk database. Tramkdb initializes a new database. The bulk of the data is kept in dbfile, which typically has a .tradb suffix. Auxiliary files dbfile.redo and dbfile.redo2 hold block-level and database operation-level redo logs. Each replica has a name that is used in the internal metadata and in the explanations of conflicts. This is the second argument to tramkdb and stored in the database. So that replicas can’t accidentally be configured with identical names, the given replicaname is suffixed with a random 32-bit number.

Trascan
Trascan
performs a file system scan of the named paths on replica (an executable interpreted exactly as minisync’s src and dst arguments) and updates the database, but does not touch the file system.

In order to detect updates reliably, the database includes SHA1 hashes of every file in the file system. The first file system scan for a newly created replica can take a long time, since all the data in the file system must be hashed. Trascan is a useful way to initialize the database without performing any file system operations.

Trasrv
Trasrv
is the per-replica server to which minisync connects. It needs to be told the database to use and the root of the replicated file system. The -i option instructs trasrv to consult ifile for a list of paths to include or exclude from replication. In the ifile, blank lines and lines beginning with a sharp (#) are ignored. The other lines must be of the form verb pattern, where verb is include or exclude and pattern is a shell-style file name pattern. To decide whether to include a given path, each line in the file is consulted in order; the earliest pattern that matches determines whether the path is included. If no pattern matches, the path is included. If no -i option is given, a default rule set is used:

     # default rule set for trasrv
     exclude *.tradb*
     exclude minisync.log

If the pattern is rooted, as in /a/b, then the pattern must match the entire path. If the pattern is not rooted, as in *.tradb* or a/b, then the pattern need only match the end of the path.

The -o flag enables option , which is an arbitrary string. The collection of options includes:
setmode

Include file mode information in synchronizations. This causes changes to file modes to be propagated to other replicas that have enabled the setmode option.

setuid

Include file owner information in synchronizations.

setgid

Include file group information in synchronizations.

setmtime

Include file modification time information in synchronizations.

mkwriteable

Make read-only files temporarily writeable for the purposes of update propagation. This is useful primarily for propagating RCS files.

testdblog

Do not flush the database to disk when trasrv has finished. This is used to exercise the redo2 database operation log.

Trafixdb
Trafixdb
is the Tra database equivalent of the Unix utility fsck: it scans for inconsistencies and fixes them, reporting the changes it makes. Unlike in some Unix file systems, inconsistencies can not arise from surprise interruptions (e.g., killing a running trasrv). Updates to the database are performed atomically, so the only source of inconsistencies is programmer error. Trafixdb is updated when such errors are found and fixed in the actual database code. The command

     trafixdb -l

displays a list of errors that trafixdb can repair, along with the date the bug was fixed in the database code.

EXAMPLES

This example demonstrates setting up replicas and running a simple synchronization.

     $ cd /tmp
     $ mkdir r1 r2
     $ cat >t1 <<!
     #!/bin/sh
     trasrv t1.tradb /tmp/r1
     !
     $ cat >t2 <<!
     #!/bin/sh
     trasrv -r t2.tradb /tmp/r2
     !
     $ chmod +x t1 t2
     $ tramkdb t1.tradb repl1
     $ tramkdb t2.tradb repl2
     $ echo hello world >r1/a
     $ minisync -v ./t1 ./t2
     copy /a
     $ cat r2/a
     hello world
     $

A more full featured replica might be

     g% cat lib/tra/emelie
     #!/bin/rc
     trasrv -o setmode -o setgid /usr/rsc/lib/tra/emelie.tradb /usr/rsc
     g%

Notice that files on remote machines may be replicated by running trasrv on a remote machine in the shell script. For example,

     g% cat .tra/wally
     #!/bin/sh
     ssh wally trasrv $HOME/.tra/xxx.tradb $HOME
     g%

This is actually oversimplified: when using remote connections, in order to convince ssh to turn off Nagle’s algorithm (which slows down our RPCs considerably), use

     ssh -2 -q -e none -t -t

on Unix or

     ssh -Rmp

on Plan 9. This has the side effect of causing ssh to allocate a pty for the connection, which merges standard output and standard error. Since trasrv occasionally writes important information on standard error, it is a good idea to use the programs stdmerge and stdsplit (see tra-aux(1)) to keep them separate. A full example would then be:

     g% cat .tra/wally
     #!/bin/sh
     ssh -2 -q -e none -t -t wally stdmerge trasrv \
          $HOME $HOME/.tra/xxx.tradb | stdsplit
     g%

SOURCE

cvs -d :pserver:anoncvs AT cvs DOT pdos DOT lcs DOT mit DOT edu:/cvs co tra

TRACES

We are interested in collecting traces of synchronization activity for research purposes. We would greatly appreciate it if you turn on logging (by creating or $home/lib/tra/minisync.log on Plan 9 or $HOME/.tra/minisync.log on Unix) and mail us your log file occasionally (for example, when the size starts to bother you, you might mail it and then zero it. Please compress the logs before sending. For example:

     # plan 9
     g% gzip < lib/tra/minisync.log >/tmp/a
     g% echo minisync logs | mail -a /tmp/a tralog AT pdos DOT lcs DOT mit DOT edu
     g%
     # unix
     $ gzip < .tra/minisync.log |
       uuencode minisync.log.gz |
       mail tralog AT pdos DOT lcs DOT mit DOT edu
     $

The log contains the dates and times of your synchronizations, the names of the files being synchronized, the names of the machines involved, and the minisync command lines. We promise not to make the logs available to others without first appropriately anonymizing them.

pdf