NAME¶
sup - software upgrade protocol
SYNOPSIS¶
sup [
flags ] [
supfile ] [
collection ...]
DESCRIPTION¶
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.
- -M <user>
- like -m but send mail to the specified user.
- -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 compress 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.
SETTING UP UPGRADES¶
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 directory. 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
private 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 be 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¶
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.
FILES¶
Files on the client machine for
sup:
- /etc/supfiles/coll.list
- supfile used for -s flag
- /etc/supfiles/coll.what
- supfile used for -s flag when -t flag is also
specified
- /etc/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:
- /etc/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
SEE ALSO¶
supservers(8)
The SUP Software Upgrade Protocol, S. A. Shafer, CMU Computer Science
Department, 1985.
EXAMPLE¶
<example>
BUGS¶
The encryption mechanism should be strengthened, although it's not trivial.
sup can delete files it should not with the delete option. This is
because in the delete pass, it tries to delete all files in the old list that
don't exist in the new list. This is a problem when a directory becomes a
symlink to a hierarchy that contains the same names. Then sup will cross the
symlink and start deleting files and directories from the destination. This is
not easily fixed. Don't use sup with symlink/rsymlink and the delete option at
the same time or *be careful*!