Expand PMF_FN_* macros.

[netbsd-mini2440.git] / usr.sbin / sup / source / sup.doc

                       THE SUP SOFTWARE UPGRADE PROTOCOL























                          Carnegie Mellon University
                          School of Computer Science

                                 Steven Shafer
                                 Mary Thompson

                               8 September 1989









  The  SUP  system  is  a  set  of  programs  for maintaining a set of files in
identical versions across a network of cooperating machines.  It runs under the
Mach operating system.
1. Introduction
  The  SUP System is a set of programs that provide for collections of files to
be maintained in identical  versions  across  a  number  of  machines.    These
programs are:

SUP             The "client" program, run by users or system maintainers, which
                initiates the upgrade activity  on  a  machine  requesting  the
                latest  version of a collection of files.  SUP will normally be
                run as a daemon, firing up once  each  night  (week,  etc.)  to
                upgrade the specified file collections.

SUPFILESRV      The  "file  server" program, a daemon that is run by the system
                maintainer to service requests for files  initiated  by  client
                SUP  programs.  The file server runs on every machine used as a
                "repository" of distributable  versions  of  files.    It  runs
                continuously  and  listens  for  network connection requests by
                individual  client  processes;  for  each   individual   client
                request, a process is forked to service that request.

SUPSCAN         The   "file  scanner"  program,  that  may  optionally  be  run
                periodically to speed up execution of  the  file  server.    It
                pre-compiles  a list of files on the file system that match the
                specifications for a given file collection  so  that  the  file
                server need not do this during each upgrade of that collection.
                The file scanner is normally used daily  for  very  large  file
                collections  that  are upgraded by many clients each day; it is
                not so useful for small file collections or for those that  are
                upgraded by only a few client machines per day.

  When SUP is run, the user designates the names of certain "file collections",
sets of files, that should be upgraded.   All  pre-defined  system  collections
have  entries in the coll.host file that gives the name of the host will act as
the repository for that software collection.  The file server on  that  machine
provides  a  list  of  the files included in the collection and which ones have
been changed since the last time this collection was upgraded from that  client
machine;  the  client decides which of these files it needs to receive; and the
files are sent from the file server.  In this way, files can  be  installed  on
the  repository machine once, and they will propagate to all machines upgrading
from that repository as soon as the respective users execute SUP to perform the
upgrade.    This  allows groups of cooperating users to establish sets of files
that can be relied upon to be the same across a set of host machines.

  SUP is intended to provide a broadcast  facility  for  maintaining  identical
versions  of  files  across  multiple  machines.  An alternative approach is to
provide a common file system; even when such a  system  is  available,  SUP  is
useful  for  maintaining  frequently  used files on local disk storage, and for
maintaining files across the file server machines themselves.

  The SUP system does not  address  the  issues  of  version  control,  nor  of
maintaining  compatibility  of  pieces of a system that are being independently
changed by different users or on different machines; what  SUP  provides  is  a
broadcast  mechanism  for issuing stable, reliable versions of software or data
files, produced by a small number of maintainers and needed by a larger  number
of users.  SUP is intended specifically to address these situations:

   - A large collection of system software prepared by a maintenance staff
     for use by a large user community.  For  example,  the  CMU-CSD  UNIX
     software  used  by hundreds of workstations.  In such situations, the
     users know absolutely nothing about how to obtain such software,  but
     they   need  to  keep  it  constantly  upgraded  on  their  machines.
     Similarly, the  maintainers  cannot  possibly  maintain  each  user's
     machine individually: they must rely on a broadcast mechanism such as
     SUP.

   - A moderate collection of  software  and  data  files  shared  by  the
     members  of  a  project.    For example, the vision libraries used by
     computer vision researchers  at  CMU.    Again,  a  small  number  of
     maintainers on a specific machine produce and maintain this software,
     which is used by many users on many machines in the CMU  environment.
     However,  SUP  will not support the practice of some groups that have
     large programs with different pieces  being  simultaneously  modified
     and tested in incompatible ways by various users.

   - A  user  with accounts on more than one machine.  Such a user can set
     up SUP to automatically copy a collection of files from  one  machine
     to  one  or  more  others whenever they are changed on the repository
     machine.

  If the system maintenance staff is  involved  on  the  repository  machine  a
"system"  file collection can be set up for which client SUP programs need know
nothing but the name of the collection.  Otherwise, the file collection will be
"private",  and  client  SUP programs must be specifically told the name of the
repository host and the base directory name for the collection on that host.

  SUP provides facilities for upgrading read-protected files (i.e.  files  that
are  not  readable by the general public), data encryption of transmitted files
and filenames, allowing access only to selected host machines not on the  local
network,  automatically  creating  backup  copies  of critical files, executing
command-files or programs after upgrading files that require special  handling,
and  mailing  progress  and error messages to designated users.  SUP is also as
clever as can be about ensuring that upgraded files have  the  same  accounting
information  (mode,  owner,  links,  etc.)  on  the  client  machine  as on the
repository machine, and ensuring that upgrade problems don't wipe out  existing
files when this is avoidable.
2. How to Use SUP to Upgrade a File Collection
  You  will normally want to run SUP periodically, say every day or every week,
using the at program, to upgrade important file collections such as UNIX system
software.    You  can  also  execute SUP directly at any time.  The SUP command
looks like this:

    $ sup [flags] [supfile]

These are the flags and arguments:

-a (all files)  Normally, SUP only upgrades files if they  are  out-of-date  or
                missing  on your machine.  If you specify the -a flag, then all
                files in the collection will be upgraded regardless of  whether
                they meet these conditions.  This is useful for recovering from
                catastrophic file deletions or disk crashes.

-b (backup)      If this flag  is  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              overrides  and  disables  the  -b  flag  and the backup supfile
                option.

-d (delete)      Files that are no longer in the collection on  the  repository
                will be deleted if present on the local machine.  This may also
                be specified in a supfile with the deleteoption.

-D              This flag overrides and disables the -d  flag  and  the  delete
                supfile option.

-e (execute)    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              overrides  and  disables  the  -e  flag and the execute supfile
                option.

-f (file list)  If you specify -f, then SUP will print a list of all the  files
                in  the specified collections, indicating which ones need to be
                upgraded, which  are  directories,  and  which  require  backup
                copies  to  be  created.    The  upgrade  itself  will  not  be
                performed.

-l (local)       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 (mail)       Normally, SUP prints log messages on its  standard  output  and
                diagnostic  output.   With the -m flag, messages will be mailed
                to you instead.  This also  allows  the  notify  option  to  be
                effective  (see  the discussion of supfiles below) to send mail
                to someone else.

-N (network debugging)
                The  -N  flag  causes  SUP  to  produce  tons  of  output lines
                describing   the   progress   and   status   of   the   network
                communications with the name server and file server.

-P (debugging ports)
                The -P flag tells SUP to use an alternate set of TCP ports from
                the  normal  ports.    This  is  a  debugging  aid  for  system
                maintenance.

-o (old files)  This flag overrides the noold  option  if  it  appears  in  the
                supfile.    The  -a  flag also overrides the noold option.  See
                "Supfiles" below for details.

-O              overrides and disables the -o flag and the old supfile option.

-s (system collections)
                Normally,  you  will specify a specific supfile to describe the
                file collections you want.  If you use  the  -s  flag,  then  a
                specific  supfile  will  be  used  that  describes  the  system
                software file collections.  The supfile for system software  is
                /usr/cmu/lib/supfiles/coll.list.

-t (time)       If you specify -t, then SUP will simply print out the last time
                and  date  at  which  each  specified   file   collection   was
                successfully  upgraded; it will not perform any actual upgrade.
                This is a diagnostic aid  in  case  you  suspect  the  upgrades
                aren't working.

-v (verbose)    Normally,  SUP only produces messages to tell what's gone wrong
                (if anything does go wrong).  With the -v flag,  messages  will
                be  produced  to  tell  what is happening when things are going
                normally as well.

supfile         You must specify the name of a supfile, unless you use  the  -s
                flag  to  indicate  the  system software supfile.  The supfile,
                described below, specifies which file collections you  want  to
                upgrade.

  For example, to upgrade system software on your machine, type:

    $ sup -s

or, to have detailed log messages mailed to you:

    $ sup -v -m -s

Because  SUP runs with your user-id, you will not be able to upgrade the system
software unless you are logged onto that account when you execute SUP.

  Each file collection being upgraded  must  have  a  base  directory  on  your
machine,  which  will normally contain all the files in the collection.  Within
this directory there should be 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 files into this directory as needed.

  If you want to find out what files need to be upgraded, type:

    $ sup -f supfile

This will list all the files in the collection, indicating  which  need  to  be
upgraded  (and  why), which are directories, and which would have backup copies
created if the upgrade were performed.  If you simply want to find out the date
and time of the last successful upgrades, type:

    $ sup -t supfile

This  will  print  the  collection  name  and time of the last upgrade for each
collection described in the indicated supfile.  For the system collections, you
can use:

    $ sup -s -t

2.1 Supfiles
  When you execute SUP, you specify a supfile either by name or by using the -s
flag.  This file is a list of the file collections you wish to upgrade.

  The supfile is a text file, with each file collection described on  a  single
line.    The  line  begins with the name of the collection, and may then have a
number of options separated by spaces.  The options are:

base=directory  The name of the base directory on this machine  for  this  file
                collection,   when   you   don't   want   to  use  the  default
                (/usr/collection).

host=hostname   The name of the host machine acting as the repository for  this
                file  collection,  used  for  "private"  file collections.  For
                "system" file collections, this is unnecessary because the this
                information is kept in /usr/cs/lib/supfiles/coll.host.

hostbase=directory
                The name of the base directory on the  repository  machine  for
                the  file  collection  (see  "How  to Set Up a File Collection"
                below).  This is also used only for "private" file collections;
                for  "system"  file  collections,  the  information is obtained
                automatically by the file server.  The default name of the host
                base directory is /usr/collection.

login=accountid The name of the account to be used by the file server, when the
                default is not acceptable (i.e. it doesn't have  the  necessary
                file  access  privileges  to  read  the  file collection).  The
                default at CMU is  the  "Anonymous  FTP"  account  if  no  data
                encryption   is   used,   or   the   owner   of  the  directory
                sup/collection within the repository machine's  base  directory
                if encryption is used.

password=password
                The password used  for  the  login  account  specified  by  the
                "login" option.  This password will be transmitted in encrypted
                form over the network.

crypt=key       An optional encryption key for filenames and file data for this
                file  collection.    If used, the same key must be specified on
                the repository machine or the  upgrade  will  not  take  place.
                This  key  is  used  for  filenames  and  data  only -- not for
                transmission of the passsword in the "password"  option.    The
                use  of  data  encryption  also  implies  an  alternate default
                account for the file server (see the "login" option above).

notify=mailaddress
                The  account  name  to  which  mail  is to be addressed for log
                messages for this file collection, when the -m flag is given to
                SUP.  The account name can be a complete mail address, possibly
                including a network host name such as sas@cmu-cs-ius.

noexec          This option prevents the automatic execution of  command  files
                on  your  machine  with  the upgrade is finished (see "What SUP
                Does" below).

backup          This option enables backup  copies  of  critical  files  to  be
                created by SUP as specified in "What SUP Does" below.

nodelete        This option prevents SUP from deleting files on your machine if
                they are deleted from the file  collection  on  the  repository
                machine.

noold           This  option  tells SUP not to check on files in the collection
                that have not been modified or created since the last  upgrade.
                This  allows  SUP to run much faster on large file collections,
                but prevents it from deleting files on the  client  machine  if
                they  are  deleted from the repository, or from restoring files
                that have been accidentally deleted from  the  client  machine.
                This  option  is  normally  useful  only  for  very  large file
                collections.   Its  function  subsumes  that  of  the  nodelete
                option.    The noold flag will be ignored when either the -a or
                -o flag is specified to SUP; this allows a complete file  check
                to  be  performed with the -o flag when needed to recover from,
                say, accidental deletion of critical files.

  Here is an example of a supfile:

    cmu  backup
    vision  crypt=pupil backup notify=vision@cmu-cs-ius
    sas  host=ius hostbase=/usr/sas/sun login=sas password=foo crypt=bletch

This supfile specifies the following file collection upgrades:

cmu             The "cmu" file collection, which is a "system" file collection,
                with  local  base  directory  /usr/cmu  (the  default).  Backup
                copies of critical files will be created during upgrading.

vision          The "vision" file collection, also a "system" file  collection,
                with  local  base  directory  /usr/vision.    Backups  will  be
                created.  The data will be encrypted with key  pupil,  and  log
                messages will be sent to the vision account on cmu-cs-ius.

sas             A   "private"   file  collection  will  be  upgraded  from  the
                cmu-cs-ius machine.  The remote base directory is /usr/sas/sun,
                but the local base directory is /usr/sas.  The file server will
                login on account sas  with  password  foo;  the  data  will  be
                encrypted with key bletch.
3. What SUP Does
  An upgrade involves several steps:

   1. SUP  first  reads  the specified supfile, checking it for errors and
      recording all the specifications and options.

   2. If any collections do not specify a host  name,  SUP  will  look  in
      /usr/cs/supfiles/coll.host  to  find  out the names of the hosts for
      these collections.  In the preceding example, the name server  would
      be  asked  to  supply  the  host  names  for the cmu and vision file
      collections.

   3. For each collection on the list, SUP will connect to the file server
      on  the  appropriate host and carry on the upgrade process.  (If the
      file server is on the same host machine as the client, and the  base
      directories are the same, then no upgrade is performed.)

         a. The  file server and SUP exchange setup information, including
            the host base directory, login  account  name,  password,  and
            encryption  key.    SUP  also  reports  the  time  of the last
            upgrade, by looking  in  the  file  sup/collection/when  (e.g.
            /usr/vision/sup/vision/when)  on the client machine.  The file
            server gets the base directory name, if needed, by looking  in
            the   file   /usr/cs/lib/supservers/coll.dir,   and  gets  the
            encryption key from  sup/collection/crypt  on  the  repository
            machine.  The connection may be refused by the file server for
            such reasons as:

               - incorrect login name or password
               - base  directory  is  protected  against  access  by   the
                 specified account
               - incorrect data encryption key
               - host not allowed access

         b. Once  the  connection is established and access permission has
            been granted as above, the file server builds a  list  of  all
            files  and  directories in the file collection.  The list file
            sup/collection/list (see "How to Set  Up  a  File  Collection"
            below)  is used to generate this list.  The files indicated in
            the list file are marked with  a  special  flag  if  they  are
            indicated  to  have  backup copies created in case of upgrade.
            The last modification date of each file is checked against the
            time  of  the last upgrade (reported by the client above), and
            if it has been modified since the last upgrade, a flag is  set
            to  indicate  that  the  client's  copy of this file is out of
            date.  The file list, along with the  backup  and  out-of-date
            flag  for  each  file,  is sent to the client.  If a scan file
            exists as created by SUPSCAN (sup/collection/scan),  then  the
            file  list  is  taken  from  the  scan  file  instead of being
            constructed from the list file by the file server.    In  this
            case,  the  time of record for the upgrade will be the time at
            which the scan file was created rather than the time at  which
            the  upgrade  actually  occurs.    If  the  noold  option  was
            specified in the supfile (and not overridden by the -a  or  -o
            flag to SUP), the list of filenames sent to the client process
            will exclude those files that were  not  created  or  modified
            since the last upgrade.

         c. The  client  SUP  process  receives  the  list  of  files  and
            constructs a list of the files it needs.  This  will  normally
            be those files that are either (1) out-of-date as indicated by
            the flag sent from the file server, or (2)  missing  from  the
            local  machine.  However, if the -a flag was specified to SUP,
            then every file in the list will be  selected  by  the  client
            process.  The list of needed files is sent to the file server.
            For each selected file, if the backup flag was marked and  the
            user specified the backup option in the supfile, then a backup
            copy of the file will be created.  This will be a copy of  the
            file  with  "backup/"  inserted in the filename just after the
            directory name, i.e.  /usr/vision/lib/libvision.a would have a
            backup  copy  named  /usr/vision/lib/backup/libvision.a.  (The
            indicated  directory,  e.g.  /usr/vision/lib/backup,  will  be
            created if needed.)  Also at this time, if the nodelete option
            was not specified, the client reads its list of files  in  the
            collection     during    the    last    successful    upgrade,
            sup/collection/last, and deletes any files appearing  in  that
            list that are not in the current file list.

         d. The  file  server  receives the list of files requested by the
            client.  It checks to see that each file is  on  its  list  of
            files  for  this collection, and that each file is accessible;
            if a file fails either condition its name will be reported  to
            the  client as being denied to that client.  Each file will be
            sent to the client machine,  along  with  the  owning  account
            name,  the  owning group name, the 12 low-order mode bits, and
            the last modification time for that file.  If a file has  more
            than  one  link (filename), both of which are requested by the
            client, then the file will be sent once and the second  (etc.)
            filename will be accompanied only by a flag saying it's a link
            and the name of the file actually sent.  The  client  receives
            each   file   and   processes  it  as  described  under  "File
            Installation" below.  Directories  are  treated  similarly  to
            files;  the  mode,  owning account and group, and modification
            time  are  transmitted  to  the  client  machine  whenever   a
            directory is upgraded.

         e. When all files have been transmitted, the file server looks at
            the list of command-files to be executed after  upgrading  for
            this collection (see "How to Set Up a File Collection" below).
            If any of the command-files or their trigger files  have  been
            upgraded,  then  the  client  is  sent  the  filename  of  the
            command-file.  The client SUP process  will  normally  execute
            these  files; however, if the user has specified noexec in the
            supfile, then the files will not be executed.  In this case, a
            log message will be created and printed or mailed, telling the
            user to please execute these files.    When  creating  command
            files  to be executed by SUP, you should bear in mind that the
            command file might be  executed  several  times  on  the  same
            version of the trigger files.

         f. Finally,  if  the  upgrade is successfully completed, the file
            server reports the time  (on  its  own  clock)  at  which  the
            upgrade  began;  the  client will record this time in the file
            sup/collection/when to be reported as above at  the  start  of
            the  next  upgrade.  If the nodelete option was not specified,
            then the list of all files in the collection is  written  into
            sup/collection/last.

  SUP  and  the  server  processes begin each connection by determining whether
byte-swapping is necessary for passing integers across the network.  If so, the
server  process  performs  byte-swapping  on input or output of integers to the
network, while the client uses its natural representation for network I/O.

3.1 File Installation
  When SUP receives an ordinary file  (i.e.  one  that  is  not  a  link  to  a
previously sent file), it follows this procedure:

   1. If  the  file doesn't already exist on the local machine, it's a new
      file.  It will be created and the data will be  read  directly  into
      this file.

   2. Otherwise, the file already exists.  An attempt will be made to read
      the file contents from the network into a temporary file, which will
      later  be  renamed to replace the destination file.  SUP will try to
      create a temporary file in  the  following  directories,  proceeding
      down the list until one of the attempts succeeds:

         a. destination-directory   (the  directory  containing  the  file
            itself)
         b. sup (the sup subdirectory of the local base directory)
         c. . (the local base directory)
         d. /usr/tmp
         e. /tmp

      If all these attempts fail, SUP will try to create  the  destination
      file  itself  instead of using a temporary file.  If that fails, SUP
      will complain with a log message and go on to the next file.

   3. The file data itself is read into the temporary or destination file.
      Interrupts are disabled during this process.

   4. If  the  file  read  was  a  temporary  file,  it  is renamed to the
      destination file.  This is done via link/unlink, if possible, unless
      the destination file has more than one link already on this machine.
      If the link/unlink fails or if the  destination  file  has  multiple
      links, then the temporary file is actually copied to the destination
      and the temporary file is unlinked.

   5. The owner, group, modification time, and low-order 12 mode  bits  of
      the  destination  file  are set to the values received from the file
      server.  The last-access time of the file  is  set  to  the  current
      local clock.

   6. If  the  -v  flag  was  specified  to  SUP, a log message is printed
      indicating the successful receipt of the file.

  When SUP receives a new link to a file previously received, it  simply  tries
to  unlink  and  link unless the two names are on different file systems on the
local machine.  If this is the case, or if the link fails, then the  previously
received  file  is  actually  copied  to  the  new name (using exactly the same
process as described above for creating a temporary file if needed, etc.)   The
file-system  comparison  checks  the file system of the old file itself and the
directory containing the new name.

  In all cases, if the directory containing a received file or  link  does  not
exist  on  the local machine, SUP creates it with mkdir (recursively if needed)
before creating that file or link.  The mode, owner,  group,  and  modification
time of the newly created directory will then be set to be the same as the mode
of the corresponding directory on the  repository  machine.    This  accounting
information  will  be  updated  whenever  the  directory  is  modified  on  the
repository machine.

  As can be seen from this description, SUP will work the most  smoothly  (i.e.
always  using link/unlink for file name changing) if it has write permission in
the local base directory and in all subdirectories of that directory.
4. How to Set Up a File Collection
  It takes only a little bit of effort  to  set  up  a  file  collection  on  a
repository machine to be upgraded by authorized clients.

  First,  the file collection must be given a name and a base directory.  There
can  be  several  collections  with  different  names  sharing  the  same  base
directory;  for example, there might be a file collection called cmulib for the
CMU C library, and one called cmumathlib for just the math routines in the  CMU
C library, both using /usr/cmu as the base directory.

  If  it  is a "private" file collection, client users must be told the name of
the repository host and the name of the host base directory for use in the host
and  hostbase  options  in  the  supfile, described above.  If it is a "system"
collection instead, the system maintainers must alert the name servers  of  the
host  name  (in  /usr/cmu/lib/supservers/coll.host)  and  the  appropriate file
server of the base directory name (if not  the  default,  by  putting  it  into
/usr/cmu/lib/supservers/coll.dir).

  Within the base directory, a subdirectory must be created called sup.  Within
this subdirectory will be a further subdirectory whose name is the name of  the
collection (there may be several of these if several collections share the same
base directory).  Each collection's subdirectory will contain  any  or  all  of
four files:

collection/list The  list  file,  describing  the files in the collection.  The
                format of this file is explained below.

collection/host Normally, the file server allows access to a collection by  all
                machines.   If you wish to allow access only to specific remote
                hosts, you can list their names, one per  line,  in  this  text
                file.    If a remote host has several alias names, it need only
                be listed once in this file.  The name LOCAL  can  be  used  to
                allow access to all machines on the local network.  This access
                control is in addition to the  other  forms  of  authentication
                provided  by  SUP  (data  encryption  and  UNIX file protection
                modes).

collection/crypt
                If  you wish to apply data encryption to the filenames and file
                contents in this collection during upgrading, create this  file
                and place in it the encryption key.  This should be on a single
                line of text containing nothing else except an optional newline
                character.    The client must supply the same key via the crypt
                option in the supfile for this file collection; the file server
                checks  that  explicitly before authorizing the upgrade to take
                place.

collection/scan To speed up execution of the  file  server,  you  may  wish  to
                create a scan file periodically.  This is done by executing the
                SUPSCAN program:

                    $ supscan [-v] collection [basedir]

                This  will  construct  a  list  of  all  files   matching   the
                specifications  in  the  list  file,  and record it in the scan
                file.  When an upgrade is performed on the collection, the file
                server  will  notice that the scan file is present and use this
                list  instead  of  actually  building  the  filename  list   by
                analyzing  the  list  file.  The time of record for the upgrade
                will then be the time at which the scan file was created rather
                than the time at which the upgrade occurs.  A scan file is only
                useful for very large file collections that are  upgraded  many
                times  each  day.    The options for the SUPSCAN program are -v
                ("verbose") to produce messages as it scans the file list,  and
                basedir  if  the  collection is a private collection whose base
                directory name is not the default name.

  This is all the preparation required for a file collection to be upgraded.

  Note that the default user-id for the file server is "Anonymous  FTP"  if  no
data  encryption  is used; if encryption is used, the default will be the owner
of the subdirectory sup/collection within the base directory.

4.1 The List File
  The list file contains a description  of  the  files  to  be  upgraded.    It
contains  any  number  of commands, each on a separate line of text.  Each line
contains a keyword and a number of operands separated by spaces.  All filenames
in  the  list  are evaluated relative to the collection's base directory on the
repository machine for the file server, and relative to the base  directory  on
the  client  machine  for the client SUP process.  All (except execfile) may be
file specifications containing the shell's meta-characters  *,  ?,  [...],  and
{...}.

  The commands are:

upgrade filename ...
                These files will be  included  in  the  list  of  files  to  be
                upgraded.   If a directory name is given, all the files in that
                directory will be  included  and  any  subdirectories  will  be
                recursively included as well.

omit filename ...
                These files will not be included in the list; if a directory is
                specified,  it  will  not  be included nor will its contents be
                included.  For example, the specifications upgrade lib and omit
                lib/test  will  include  all  files  and  subdirectories of lib
                except  lib/test  (and  any  subdirectories  or  files   within
                lib/test).

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 files will be marked for creating  backup  copies  whenever
                they  are  upgraded  (as  described  above).  Only files can be
                included in this list -- not  directories.    As  noted  above,
                actual  backup  copies  will  only be created by SUP when these
                files are being  upgraded,  and  then  only  if  the  user  has
                specified the backup option in the supfile.

execute execfile (triggerfile ...) ...
                The listed execfiles  are  command  files  or  programs  to  be
                executed  after  an  upgrade to perform routine installation of
                the upgraded files.  Each execfile will be executed  only  when
                it  is  upgraded itself, or when any of its listed triggerfiles
                have been upgraded.  The installation tasks performed  by  such
                files  might  be, for example, creating a table of contents for
                manual entries or for a subroutine library, or modifying a host
                name field within a data file.

include listfile ...
                The named listfiles will be read at this point.  This allows  a
                collection  to  contain  another collection in its entirety, by
                simply specifying the name  of  the  listfile  for  that  other
                collection.

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.

symlink filename...
                The  specified  file(s) are to be treated as symbolic links and
                will be transfered as such and not followed.  By  default,  SUP
                will follow symbolic links.

rsymlink dirname...
                All the symbolic links in the specified subdirectories  are  to
                be transferred as such and not followed.

  Blank  lines  may  appear  freely  in  the  list file, and the order in which
command lines appear within the file does not matter.  Filenames must generally
match  as  strings, e.g.  with base directory /usr/vision, "lib" in the upgrade
command would not match "/usr/vision/lib" in the omit command;  it  would  only
match  "lib"  in  the omit command.  However, one special exception exists:  if
the base directory is specified via "dot"  (.)  in  the  upgrade  command,  the
filenames  within  that  directory  need not begin with "./" in other commands.
For example, with base directory /usr/vision,  the  commands  "upgrade  ."  and
"omit  exp"  specify  a  file  list  including all files and directories within
/usr/vision except the subdirectory /usr/vision/exp and its subdirectories  and
files.
5. Setup for SUP
  You need to add the following entries to /etc/services:

    supfilesrv      871/tcp
    supfiledbg      1127/tcp

  A  supfilsrv  daemon  should be kept running on any machine that may act as a
repository for a collection. Since this includes  private  collections,  it  is
advisable  to  have  supfilesrv  running on all machines if SUP is to be widely
used. nanny can be used to start the supfilesrv.

  The program modcoll.8 is used to set up the control files  for  the  "system"
collections. See /usr/cs/man/man8/modcoll.8
                               Table of Contents

1. Introduction                                                               1

2. How to Use SUP to Upgrade a File Collection                                2

   2.1 Supfiles                                                               2

3. What SUP Does                                                              4

   3.1 File Installation                                                      4

4. How to Set Up a File Collection                                            5

   4.1 The List File                                                          5

5. Setup for SUP                                                              6