sup - software upgrade protocol
sup [ flags ] [ supfile ] [ collection ...]
Sup is a program used for upgrading collections of files
from other machines to your machine. You execute sup, the
client program, which talks over the network using IP/TCP
to a file server process. The file server process cooperates
with sup to determine which files of the collection
need to be upgraded on your machine.
Sup collections can have multiple releases. One use for
such releases is to provide different versions of the same
files. At CMU, for example, system binaries have alpha,
beta and default release corresponding to different staging
levels of the software. We also use release names
default and minimal to provide complete releases or subset
releases. In both of these cases, it only makes sense to
sup one release of the collections. Releases have also
been used in private or external sups to provide subsets
of collections where it makes sense to pick up several of
the releases. For example the Mach 3.0 kernel sources has
a default release of machine independent sources and separate
releases of machine dependent sources for each supported
platform.
In performing an upgrade, the file server constructs a
list of files included in the specified release of the
collection. The list is sent to your machine, which
determines which files are needed. Those files are then
sent from the file server. It will be most useful to run
sup as a daemon each night so you will continually have
the latest version of the files in the needed collections.
The only required argument to sup is the name of a supfile.
It must either be given explicitly on the command
line, or the -s flag must be specified. If the -s flag is
given, the system supfile will be used and a supfile command
argument should not be specified. The list of collections
is optional and if specified will be the only
collections upgraded. The following flags affect all collections
specified:
-s As described above.
-t When this flag is given, sup will print the time
that each collection was last upgraded, rather than
performing actual upgrades.
-u When this flag is given, sup will not try to
restore the user access and modified times of files
in the collections from the server.
-S Operate silently printing messages only on errors.
-N Sup will trace network messages sent and received
that implement the sup network protocol.
-P Sup will use a set of non-privileged network ports
reserved for debugging purposes.
The remaining flags affect all collections unless an
explicit list of collections are given with the flags.
Multiple flags may be specified together that affect the
same collections. For the sake of convenience, any flags
that always affect all collections can be specified with
flags that affect only some collections. For example, sup
-sde=coll1,coll2 would perform a system upgrade, and the
first two collections would allow both file deletions and
command executions. Note that this is not the same command
as sup -sde=coll1 coll2, which would perform a system
upgrade of just the coll2 collection and would ignore the
flags given for the coll1 collection.
-a All files in the collection will be copied from the
repository, regardless of their status on the current
machine. Because of this, it is a very expensive
operation and should only be done for small
collections if data corruption is suspected and
been confirmed. In most cases, the -o flag should
be sufficient.
-b If the -b flag if given, or the backup supfile
option is specified, the contents of regular files
on the local system will be saved before they are
overwritten with new data. The file collection
maintainer can designate specific files to be worthy
of backing up whenever they are upgraded. However,
such backup will only take place if you specify
this flag or the backup option to allow backups
for a file collection on your machine. The backup
mechanism will create a copy of the current version
of a file immediately before a new copy is received
from the file server; the copy is given the same
name as the original file but is put into a directory
called BACKUP within the directory containing
the original file. For example, /usr/sas/src/foo.c
would have a backup copy called
/usr/sas/src/BACKUP/foo.c. There is no provision
for automatically maintaining multiple old versions
of files; you would have to do this yourself.
-B The -B flag overrides and disables the -b flag and
the backup supfile option.
-d Files that are no longer in the collection on the
repository will be deleted if present on the local
machine and were put there by a previous sup. This
may also be specified in a supfile with the delete
option.
-D The -D flag overrides and disables the -d flag and
the delete supfile option.
-e Sup will execute commands sent from the repository
that should be run when a file is upgraded. If the
-e flag is omitted, Sup will print a message that
specifies the command to execute. This may also be
specified in a supfile with the execute option.
-E The -E flag overrides and disables the -e flag and
the execute supfile option.
-f A list-only upgrade will be performed. Messages
will be printed that indicate what would happen if
an actual upgrade were done.
-k Sup will check the modification times of files on
the local disk before updating them. Only files
which are newer on the repository than on the local
disk will be updated; files that are newer on the
local disk will be kept as they are. This may also
be specified in a supfile with the keep option.
-K The -K flag overrides and disables the -k flag and
the keep supfile option.
-l Normally, sup will not upgrade a collection if the
repository is on the same machine. This allows
users to run upgrades on all machines without having
to make special checks for the repository
machine. If the -l flag is specified, collections
will be upgraded even if the repository is local.
-m Normally, sup used standard output for messages.
If the -m flag if given, sup will send mail to the
user running sup, or a user specified with the
notify supfile option, that contains messages
printed by sup.
-o Sup will normally only upgrade files that have
changed on the repository since the last time an
upgrade was performed. That is, if the file in the
repository is newer than the date stored in the
when file on the client. The -o flag, or the old
supfile option, will cause sup to check all files
in the collection for changes instead of just the
new ones.
-O The -O flag overrides and disables the -o flag and
the old supfile option.
-z Normally sup transfers files directly without any
other processing, but with the -z flag, or the com-
press supfile option, sup will compress the file
before sending it across the network and uncompress
it and restore all the correct file attributes at
the receiving end.
-Z The -Z flag overrides and disables the -z flag and
the compress supfile option.
-v Normally, sup will only print messages if there are
problems. This flag causes sup to also print messages
during normal progress showing what sup is
doing.
Each file collection to be upgraded must have a base
directory which contains a subdirectory called sup that
will be used by the sup program; it will be created automatically
if you do not create it. Sup will put subdirectories
and files into this directory as needed.
Sup will look for a subdirectory with the same name as the
collection within the sup subdirectory of the base direc-
tory. If it exists it may contain any of the following
files:
when.<rel-suffix>
This file is automatically updated by sup when a
collection is successfully upgraded and contains
the time that the file server, or possibly supscan,
created the list of files in the upgrade list. Sup
will send this time to the file server for generating
the list of files that have been changed on the
repository machine.
refuse This file contains a list of files and directories,
one per line, that the client is not interested in
that should not be upgraded.
lock This file is used by sup to lock a collection while
it is being upgraded. Sup will get exclusive
access to the lock file using flock(2), preventing
more than one sup from upgrading the same collection
at the same time.
last.<rel-suffix>
This file contains a list of files and directories,
one per line, that have been upgraded by sup in the
past. This information is used when the delete
option, or the -d flag is used to locate files previously
upgraded that are no longer in the collection
that should be deleted.
Each file collection must also be described in one or more
supfiles. When sup is executed, it reads the specified
supfile to determine what file collections and releases
to upgrade. Each collection-release set is described by a
single line of text in the supfile; this line must contain
the name of the collection, and possibly one or more
options separated by spaces. The options are:
release=releasename
If a collection contains multiple releases, you
need to specify which release you want. You can
only specify one release per line, so if you want
multiple releases from the same collections, you
will need to specify the collection more than once.
In this case, you should use the use-rel-suffix
option in the supfile to keep the last and when
files for the two releases separate.
base=directory
The usual default name of the base directory for a
collection is described below (see FILES); if you
want to specify another directory name, use this
option specifying the desired directory.
prefix=directory
Each collection may also have an associated prefix
directory which is used instead of the base directory
to specify in what directory files within the
collection will be placed.
host=hostname
hostbase=directory
System collections are supported by the system
maintainers, and sup will automatically find out
the name of the host machine and base directory on
that machine. However, you can also upgrade pri-
vate collections; you simply specify with these
options the hostname of the machine containing the
files and the directory used as a base directory
for the file server on that machine. Details of
setting up a file collection are given in the section
below.
login=accountid
password=password
crypt=key
Files on the file server may be protected, and network
transmissions may be encrypted. This prevents
unauthorized access to files via sup. When files
are not accessible to the default account (e.g.,
the anon anonymous account), you can specify an
alternative accountid and password for the file
server to use on the repository host. Network
transmission of the password will be always
encrypted. You can also have the actual file data
encrypted by specifying a key; the file collection
on the repository must specify the same key or else
sup will not be able to upgrade files from that
collection. In this case, the default account used
by the file server on the repository machine will
be the owner of the encryption key file (see FILES)
rather than the anon anonymous account.
notify=address
If you use the -m option to receive log messages by
mail, you can have the mail sent to different user,
possibly on another host, than the user running the
sup program. Messages will be sent to the specified
address, which can be any legal netmail
address. In particular, a project maintainer can
be designated to receive mail for that project's
file collection from all users running sup to
upgrade that collection.
backup As described above under the -b flag.
delete As described above under the -d flag.
execute
As described above under the -e flag.
keep As described above under the -k flag.
old As described above under the -o flag.
use-rel-suffix
Causes the release name to be used as a suffix to
the last and when files. This is necessary whenever
you are supping more than one release in the same
collection.
PREPARING A FILE COLLECTION REPOSITORY [Toc] [Back] 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 multirelease
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 metacharacters
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.
Files on the client machine for sup:
/usr/lib/supfiles/coll.list
supfile used for -s flag
/usr/lib/supfiles/coll.what
supfile used for -s flag when -t flag is also specified
/usr/lib/supfiles/coll.host
host name list for system collections
<base-directory>/sup/<collection>/last<.release>
recorded list of files in collection as of last
upgrade
<base-directory>/sup/<collection>/lock
file used to lock collection
<base-directory>/sup/<collection>/refuse
list of files to refuse in collection
<base-directory>/sup/<collection>/when<.release>
recorded time of last upgrade
/usr/sup/<collection>
default base directory for file collection
Files needed on each repository machine for the file
server:
/usr/lib/supfiles/coll.dir
base directory list for system collections
<base-directory>/sup/<collection>/crypt
data encryption key for a collection. the owner of
this file is the default account used when data
encryption is specified
<base-directory>/sup/<collection>/host
list of remote hosts allowed to upgrade a collection
<base-directory>/sup/<collection>/list
list file for a collection
<base-directory>/sup/<collection>/lock
lock file for a collection
<base-directory>/sup/<collection>/logfile
log file for a collection
<base-directory>/sup/<collection>/prefix
file containing the name of the prefix directory
for a collection
<base-directory>/sup/<collection>/scan
scan file for a collection
/usr/<collection>
default base directory for a file collection
supservers(8)
The SUP Software Upgrade Protocol, S. A. Shafer, CMU Computer
Science Department, 1985.
<example>
The encryption mechanism should be strengthened, although
it's not trivial.
[ Back ] |
