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 cooperates with sup to determine which files of the col-
       lection 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  exam-
       ple, 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  sev-
       eral  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 col-
              lection  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 conve-
       nience, 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 col-
       lections  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  speci-
              fied,  the contents of regular files on the local system will be
              saved before they are overwritten with new data.  The file  col-
              lection  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 direc-
              tory    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 automati-
              cally 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  sup-
              file 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 reposi-
              tory  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 sup-
              file 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  reposi-
              tory  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  sup-
              file option.

       -z     Normally sup transfers files directly without any other process-
              ing, 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 pro-
       gram; 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 informa-
              tion  is  used when the delete option, or the -d flag is used to
              locate files previously upgraded that are no longer in the  col-
              lection 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  collec-
              tions,  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  direc-
              tory.

       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 transmis-
              sions  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 repos-
              itory 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 sepa-
              rate 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  trans-
              mission 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 par-
              ent 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=<host-
              file>  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  com-
       mand  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 subdirec-
              tories 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  exe-
              cute  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  collec-
              tion

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

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen