Provided by: sup_20100519-1build1_amd64 bug

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

                                             10/01/08                                      SUP(1)