I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.


SUP(1)                      General Commands Manual                     SUP(1)



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.

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

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.

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 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*!



                                  2013/03/13                            SUP(1)