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.

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.

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.

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

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

login=accountid
password=password
Files on the file server may be protected. 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.

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.

FILES
Files on the client machine for sup:

/MachTen/misc/supTenon
supfile used for MachTen software upgrades from Tenon. This
supfile will query the file server at sup.tenon.com and
automatically install software upgrades on your MachTen
system. In the process, sup will manage the collection named
MachTen in the directory hierarchy /MachTen/misc/sup. The
suggested use of sup for MachTen upgrades is:

sup -mv /MachTen/misc/supTenon

/usr/lib/supfiles/coll.list
supfile used for -s flag

<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/<collection>
default base directory for file collection