


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.

       -u     When  this  flag  is  given,  sup  will  not try to
              restore the user access and modified times of files



                             02/08/92                           1





SUP(1)                                                     SUP(1)


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



                             02/08/92                           2





SUP(1)                                                     SUP(1)


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




                             02/08/92                           3





SUP(1)                                                     SUP(1)


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



                             02/08/92                           4





SUP(1)                                                     SUP(1)


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



                             02/08/92                           5





SUP(1)                                                     SUP(1)


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




                             02/08/92                           6





SUP(1)                                                     SUP(1)


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



                             02/08/92                           7





SUP(1)                                                     SUP(1)


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



                             02/08/92                           8





SUP(1)                                                     SUP(1)


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



                             02/08/92                           9





SUP(1)                                                     SUP(1)


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



                             02/08/92                          10





SUP(1)                                                     SUP(1)


       <base-directory>/sup/<collection>/host
              list  of  remote hosts allowed to upgrade a collec-
              tion

       <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


