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.
- -C
- The -C flag or the canonicalize supfile option, canonicalize
      all pathnames upon reception to make sure local changes from directories
      to symlinks and vice versa have not happened behind sup's back, and
      attempt to repair them. This option is expensive.
- -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.
- i
- Ignore errors from chown(2) or chgrp(2).
- -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.
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.
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 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
supservers(8)
The SUP Software Upgrade Protocol, S. A. Shafer, CMU Computer Science
  Department, 1985.
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 avoided by using the canonicalize option, but it
    is expensive. Don't use sup with symlink/rsymlink and the delete option at
    the same time or *be careful*!