


SUP(1)                                                     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 cooper-
       ates  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 stag-
       ing 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 sepa-
       rate releases of machine dependent sources for  each  sup-
       ported 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  sup-
       file.   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 com-
       mand argument should not be specified.  The list  of  col-
       lections  is  optional  and  if specified will be the only
       collections upgraded.  The following flags affect all col-
       lections 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.



                             02/08/92                           1





SUP(1)                                                     SUP(1)


       -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 com-
       mand 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 cur-
              rent machine.  Because of this, it is a very expen-
              sive  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  wor-
              thy of backing up whenever they are upgraded.  How-
              ever, such backup will only take place if you spec-
              ify 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  direc-
              tory  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.




                             02/08/92                           2





SUP(1)                                                     SUP(1)


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

       -z     Normally sup transfers files directly  without  any
              other processing, but with the -z flag, or the com-
              press supfile option, sup will  compress  the  file



                             02/08/92                           3





SUP(1)                                                     SUP(1)


              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 mes-
              sages 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 auto-
       matically if you do not create it.  Sup will put subdirec-
       tories 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  direc-
       tory.   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 generat-
              ing 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 collec-
              tion 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 pre-
              viously upgraded that are no longer in the  collec-
              tion that should be deleted.


       Each file collection must also be described in one or more



                             02/08/92                           4





SUP(1)                                                     SUP(1)


       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
              ption  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  direc-
              tory  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 pri-
              vate 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  sec-
              tion below.

       login=accountid
       password=password
       crypt=key
              Files on the file server may be protected, and net-
              work 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



                             02/08/92                           5





SUP(1)                                                     SUP(1)


              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 speci-
              fied  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 direc-
       tory; these will be specified in the supfile via the  host
       and  hostbase  options.  For a system-maintained file col-
       lection, 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 subdi-
       rectory  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 pre-
       fix file, a host file, an encryption key file, a log  file



                             02/08/92                           6





SUP(1)                                                     SUP(1)


       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 mecha-
              nism, 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  collec-
              tion  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 restric-
              tions for this  release.   next=<release>  used  to
              chain  releases  together.  This  has the effect of
              making one release be  a  combination  of  serveral
              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.



                             02/08/92                           7





SUP(1)                                                     SUP(1)


       scan   This file, created by supscan, is the list of file-
              names that correspond to the  instructions  in  the
              list  file.   The  scan  file is only used for fre-
              quently 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 indi-
              cate  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 subdirec-
       tories <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  file-
              names 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



                             02/08/92                           8





SUP(1)                                                     SUP(1)


              /usr/vision except /usr/vision/exp (and its  subdi-
              rectories 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 sup-
              file,  then  backup  copies  will  be  created   as
              described above.  Directories may not be specified,
              and no  recursive  filename  construction  is  per-
              formed;  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 informa-
              tion consists of the owner, group, mode  and  modi-
              fied 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  fol-
              lowed.  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



                             02/08/92                           9





SUP(1)                                                     SUP(1)


              collections; the larger collection can simply spec-
              ify the listfiles for the smaller collections  con-
              tained 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:

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

       /usr/lib/supfiles/coll.what
              supfile used for -s flag when -t flag is also spec-
              ified

       /usr/lib/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:

       /usr/lib/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  collec-
              tion





                             02/08/92                          10





SUP(1)                                                     SUP(1)


       <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  Com-
       puter Science Department, 1985.

EXAMPLE
       <example>

BUGS
       The  encryption mechanism should be strengthened, although
       it's not trivial.


























                             02/08/92                          11


