Man Linux: Main Page and Category List

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