A set of files residing on a repository must be prepared before
sup client processes can upgrade those files. The collection must be given a
name and a
base directory. If it is a private collection, client users must be told the name of the collection, repository host, and base directory; these will be specified in the supfile via the
host and
hostbase options. For a system-maintained file collection, entries must be placed into the host list file and directory list file as described in
supservers(8). Within the base directory, a subdirectory must be created called
sup. Within this directory there must be a subdirectory for each collection using that base directory, whose name is the name of the collection; within each of these directories will be a list file and possibly a prefix file, a host file, an encryption key file, a log file and a scan file. The filenames are listed under FILES below.
prefix
Normally, all files in the collection are relative to the base directory. This file contains a single line which is the name of a directory to be used in place of the base directory for file references.
host
Normally, all remote host machines are allowed access to a file collection. If you wish to restrict access to specific remote hosts for this collection, put each allowed hostname on a separate line of text in this file. If a host has more than one name, only one of its names needs to be listed. The name LOCAL can be used to grant access to all hosts on the local network. The host name may be a numeric network address or a network name. If a crypt appears on the same line as the host name, that crypt will be used for that host. Otherwise, the crypt appearing in the crypt file, if any will be used.
crypt
If you wish to use the sup data encryption mechanism, create an encryption file containing, on a single line of text, the desired encryption key. Client processes must then specify the same key with the crypt option in the supfile or they will be denied access to the files. In addition, actual network transmission of file contents and filenames will be encrypted.
list
This file describes the actual list of files to be included in this file collection, in a format described below.
releases
This file describes any releases that the collection may have. Each line starts with the release name and then may specify any of the following files: prefix=<dirname> to use a different parent directory for the files in this release. list=<listname> to specify the list of files in the release. scan=<scanfile> must be used in multi-release collections that are scanned to keep the scan files for the different releases separate. host=<hostfile> to allow different host restrictions for this release. next=<release> used to chain releases together. This has the effect of making one release be a combination of several other releases. If the same file appears in more than one chained release, the first one found will be used. If these files are not specified for a release the default names: prefix,list,scan and host will be used.
scan
This file, created by supscan, is the list of filenames that correspond to the instructions in the list file. The scan file is only used for frequently updated file collections; it makes the file server run much faster. See supservers(8) for more information.
lock
As previously mentioned, this file is used to indicate that the collection should be locked while upgrades are in progress. All file servers will try to get shared access to the lock file with flock(2).
logfile
If a log file exists in the collection directory, the file server will append the last time an upgrade was successfully completed, the time the last upgrade started and finished, and the name of the host requesting the upgrade.
It should be noted that sup allows several different named collections to use the same base directory. Separate encryption, remote host access, and file lists are used for each collection, since these files reside in subdirectories <basedir>/sup/<coll.name>. The list file is a text file with one command on each line. Each command contains a keyword and a number of operands separated by spaces. All filenames in the list file are evaluated on the repository machine relative to the host's base directory, or prefix directory if one is specified, and on your machine with respect to the base, or prefix, directory for the client. The filenames below (except exec-command) may all include wild-cards and meta-characters as used by csh(1) including *, ?, [...], and {...}. The commands are:
upgrade filename ...
The specified file(s) (or directories) will be included in the list of files to be upgraded. If a directory name is given, it recursively includes all subdirectories and files within that directory.
always filename ...
The always command is identical to upgrade, except that omit and omitany commands do not affect filenames specified with the always command.
omit filename ...
The specified file(s) (or directories) will be excluded from the list of files to be upgraded. For example, by specifying upgrade /usr/vision and omit /usr/vision/exp, the generated list of files would include all subdirectories and files of /usr/vision except /usr/vision/exp (and its subdirectories and files).
omitany pattern ...
The specified patterns are compared against the files in the upgrade list. If a pattern matches, the file is omitted. The omitany command currently supports all wild-card patterns except {...}. Also, the pattern must match the entire filename, so a leading */, or a trailing /*, may be necessary in the pattern.
backup filename ...
The specified file(s) are marked for backup; if they are upgraded and the client has specified the backup option in the corresponding line of the supfile, then backup copies will be created as described above. Directories may not be specified, and no recursive filename construction is performed; you must specify the names of the specific files to be backed up before upgrading.
noaccount filename ...
The accounting information of the specified file(s) will not be preserved by sup. Accounting information consists of the owner, group, mode and modified time of a file.
symlink filename ...
The specified file(s) are to be treated as symbolic links and will be transferred as such and not followed. By default, sup will follow symbolic links.
rsymlink dirname ...
All symbolic links in the specified directory and its subdirectories are to be treated as symbolic links. That is the links will be transferred and not the files to which they point.
execute exec-command (filename ...)
The exec-command you specified will be executed on the client process whenever any of the files listed in parentheses are upgraded. A special token, %s, may be specified in the exec-command and will be replaced by the name of the file that was upgraded. For example, if you say execute ranlib %s (libc.a), then whenever libc.a is upgraded, the client machine will execute ranlib libc.a. As described above, the client must invoke sup with the -e flag to allow the automatic execution of command files.
include listfile ...
The specified listfiles will be read at this point. This is useful when one collection subsumes other collections; the larger collection can simply specify the listfiles for the smaller collections contained within it.
The order in which the command lines appear in the list file does not matter. Blank lines may appear freely in the list file.