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.

       -C     The -C flag or the canonicalize supfile option, canonicalize all
              pathnames  upon reception to make sure local changes from direc-
              tories to symlinks and vice versa have not happened behind sup's
              back, and attempt to repair them.  This option is expensive.

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

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

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 direc-
       tory  becomes  a  symlink  to a hierarchy that contains the same names.
       Then sup will cross the symlink and start deleting files  and  directo-
       ries  from  the destination.  This is avoided by using the canonicalize
       option, but it is expensive.  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