tra(1)

NAME

minisync, tramkdb, trascan, trasrv, trafixdb - unidirec

tional 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 synchro

nization between replicas. Incomptible changes, called con

flicts, 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 sec

tion.

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 pre

fix 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 pre

fix of the history of the file on src, the file on src is propa

gated 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, propa

gating updates from the replica src to the replica dst. If paths

are specified, the synchronization is limited to files and direc

tories in the trees rooted at those paths. If no path is speci

fied, the entire replica is synchronized.

The options are:

-A By default, when two identical files are in con

flict, 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 opera

tion-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.

TrasrvTrasrv is the per-replica server to which minisync con

nects. 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 ear

liest pattern that matches determines whether the path is includ

ed. If no pattern matches, the path is included. If no -i op

tion 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.

setmtimeInclude file modification time information in syn

chronizations.

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.

TrafixdbTrafixdb is the Tra database equivalent of the Unix utili

ty fsck: it scans for inconsistencies and fixes them, reporting

the changes it makes. Unlike in some Unix file systems, incon

sistencies 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 ex

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

This is actually oversimplified: when using remote connec

tions, 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 al

locate a pty for the connection, which merges standard output and

standard error. Since trasrv occasionally writes important in

formation on standard error, it is a good idea to use the pro

grams stdmerge and stdsplit (see tra-aux(1)) to keep them sepa

rate. 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@cvs.pdos.lcs.mit.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 both

er 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 tra

log@pdos.lcs.mit.edu
g%
# unix
$ gzip < .tra/minisync.log
uuencode minisync.log.gz
mail tralog@pdos.lcs.mit.edu

$

The log contains the dates and times of your synchroniza

tions, 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.

TRA(1)