source: trunk/athena/etc/track/subscriptionlist.5 @ 16559

.ll 6.5i
.TH SUBSCRIPTIONLIST 5 "19 September 1988"
.UC 4
.SH NAME
subscriptionlist \- describe files to be updated by track
.SH DESCRIPTION
.PP
A
.B subscriptionlist
defines a set of files to be considered for updating by the
.B track
system.
A
.B subscriptionlist
contains a set of
.I entries.
Typically, each
.I entry
represents a directory, but an
.I entry
may represent a file, link, or device.
.P
The librarian uses the command
.sp 1
.ti +4
track -w [ options...]
.I subscriptionlist
.sp 1
to prepare a
.I statfile,
which comprises an efficient representation of the
library filesystem's currentness.
.P
The subscriber uses
.B track
& a subscriptionlist, together with the librarian's statfile,
to update his own files from the library's copies.
Note that the librarian & subscriber may use different subscriptionlists.
.SH SYNTAX
A subscriptionlist is a list of
.I entries.
.P
A
.I global exception-list
may appear before the first
.I entry.
This takes the form:
.sp 1
.br
GLOBAL :
.I pattern ...
:
.sp 1
.br
where each
.I pattern
is a shell-wildcard, using '*', '?', and '[]'.
Braces '{}' are not interpreted in subscriptionlist patterns.
.PP
Each
.I entry
has 5 fields, separated by colons:
.sp 1
.I fromfile
:
.I tofile
:
.I cmpfile
:
.I except-list
: [ command...]
.sp 1
The fields are (in order) :
.RS
.ti -2
1)
.I fromfile:
name of the source file on the librarian machine.
This field must not be blank.
.ti -2
2)
.I tofile:
name of the destination file on the subscriber machine.
Default is
.I fromfile.
.ti -2
3)
.I cmpfile:
name of the comparison file on the subscriber machine,
to be used for determining if an update is necessary.
Default is
.I tofile.
.ti -2
4)
.I exception-list:
a list of special cases and files to be excluded from updating.
.ti -2
5) A shell
.I command-line
to be executed whenever an update is made.
(NOTE: this feature is currently disabled, because it needs to be rewritten.)
.RE
.P
Fields are separated by a colon.
The last field (and thus the entry) is terminated with a newline.
.sp 1
Each of the fields
.I fromfile, tofile, cmpfile,
is stripped of leading slashes '/',
and leading/trailing white space is ignored in these fields.
.sp 1
In the
.I exception-list,
whitespace is used to separate entries.
.sp 1
In the
.I command-line,
all white space is preserved and passed to /bin/sh, and
newlines can be escaped with a backslash.
The backslash will be removed before the script is sent to the shell.
.sp 1
Any characters after a hashmark, "#", up to the end of line
will be treated as comments and ignored.
.SH SEMANTICS
.P
In the following, we assume that
.B track
has been invoked with the command-line options "-F/from_mnt -T/to_mnt",
and that the librarian file-system has been
mounted on the mount-point /from_mnt.
For each entry "A ::: a b c :",
.B track
compares the trees /from_mnt/A & /to_mnt/A,
and then updates /to_mnt/A and its subordinates if necessary,
excepting the subtrees a, b, & c.
Note that the librarian's exception-list for A is also in effect, because
.B track
's knowledge of /from_mnt's file-system state comes from the librarian's
.I statfile
(q.v.).
.P
.B Track
does not require the pathnames indicated by
.I fromfile, tofile, & cmpfile
to have the same file-type.
If, however, non-default directories
.I tofile
or
.I cmpfile
appear in the entry, track will expect these trees to parallel
.I fromfile's
structure quite perfectly.
If an entry specifies
.I cmpfile
explicitly, cmpfile will be path-qualified with either /from_mnt or /to_mnt,
according to whether or not the -w option is used.
.P
If the name of a directory is used in any field,
.B track
treats the directory as being the root of a subtree.
If the name of a symbolic link is used in any field,
.B track
will handle the symbolic link itself and will NOT follow the link.
.PP
If, in an
.I exception-list,
an item A is preceded by an arrow "->",
.B track
will export/import a symbolic-link
to the librarian's copy of the named item.  If an item is preceded by an
explanation point "!",
.B track
will export/import the file normally, as if it did not appear in the
exception list.  Wild-card patterns may appear in the exception-lists.
Literal filenames always supercede wild-card patterns in the
exception-list; for example, an entry "! filename" would take
precedence over an entry "-> *".  Wild-card patterns with more literal
characters supercede wild-card patterns with fewer literal characters;
for example, an entry "-> a*b" would take precedence over an entry
"*".
.RE
.P
Because this is a data-description-language, and not a procedural language,
the order of the
.I entries'
appearance in the subscriptionlist is not important.
.B Track
traverses the subscriptionlist more-or-less alphabetically,
but it is unwise to assume that
.B track
will update one entry before another.
If one
.I entry
is a subdirectory of another,
.B track
ensures that the parent directory
is updated first, but that the child-entry's exception-list will be applied
to the the child-directory's contents.
.SH EXAMPLES
.in 8

.ti -8
etc/hosts : : : :
.br
This entry specifies the file named "/mnt/etc/hosts".
.sp  1
.ti -8
/etc/hosts : : : :
.ti -8
/etc/services : : : :
.br
These entries specify the files "/mnt/etc/hosts" and "/mnt/etc/services".
.sp  1
.ti -8
usr/lib : : : :
.br
This entry specifies the entire subtree rooted at /mnt/usr/lib
.sp 1
.ti -8
/usr/lib : : : sendmail.cf uucp :
.br
This entry specifies files in the subtree rooted
at "/mnt/usr/lib" except for "/mnt/usr/lib/sendmail.cf" and all files
in the subtree rooted at "/mnt/usr/lib/uucp".
.ti -8
/usr/lib/aliases : : : : newaliases
.br
This entry specifies the file "/mnt/usr/lib/aliases" and
will execute the command "newaliases" if and only if
a new version is successfully copied.
.sp 1
.ti -8
/usr/lib/aliases : : : : newaliases \e
.ti -4
echo aliases file has been updated \(bv mail root
.br
This entry works exactly like the previous example and
in addition sends mail to the administrator.
.sp 1
.ti -8
/usr/lib/aliases : : : : newaliases \e
.ti -4
echo `date` /usr/lib/aliases >> /usr/adm/tracklog
.br
This entry works exactly like the previous example except that rather than
sending mail, a log entry containing the date and filename is appended to the
file named "/usr/adm/tracklog".
.sp 1
.ti -8
/usr/lib/aliases : /tmp/aliases : : : \e
.ti -4
echo new aliases file has arrived \(bv mail root
.br
This entry copies any new versions of the file named "/usr/lib/aliases" on the
.I librarian
to a locally named file "/tmp/aliases" and sends mail to the administrator.
.sp 1
.ti -8
/etc/zoneinfo::: ->* Australia GMT*:
.ti -8
/etc/zoneinfo/EST::::
.ti -8
/etc/zoneinfo/EST5EDT::::
.ti -8
/etc/zoneinfo/localtime::::
.br
These entries cause a "link-farm" to be maintained under /etc/zoneinfo,
except that EST, EST5EDT, and localtime will be updated normally,
and Australia, GMT, GMT+1, GMT+2, etc., will be ignored.
.sp 1
.ti -8
/bin/sh : /bin/nsh : : : \e
.ti -4
mv /bin/sh /bin/osh \e
.ti -4
mv /bin/nsh /bin/sh \e
.ti -4
echo new shell installed \(bv  mail root
.br
This entry copies any new versions of the file named "/bin/sh" on the
.I librarian
to a locally named file "/bin/nsh", then saves "/bin/sh" in "/bin/osh",
then moves the the new version into "/bin/sh".
.sp 1
.ti -8
/usr/sys/GORP/vmunix : /nvmunix : /vmunix : : \e
.ti -4
mv /vmunix /ovmunix \e
.ti -4
mv /nvmunix /vmunix \e
.ti -4
shutdown -r now
.br
This entry causes
.B track
to compare the locally named file "/vmunix" with the
.I librarian's
file named
"/usr/sys/GORP/vmunix".
If the versions differ, the new version will be copied into
the locally named file "/nvmunix" and the shell script will
be executed to install and reboot with the new kernel.
.in -8
.SH FILES
 .../track/slists/
.I subscriptionlist_name
.SH BUGS
.SH "SEE ALSO"
track(1)
.br
statfile(5)
.br
When Network File Systems Aren't Enough: Automatic File Distribution Revisited
.br
.ti 5
by Daniel Nachbar