Unix/Linux Go Back    


NetBSD 6.1.5 - man page for sup (netbsd section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 collection need to be upgraded on your machine.

       Sup collections can have multiple releases.  One use for such releases is to provide  dif-
       ferent  versions of the same files.  At CMU, for example, system binaries have alpha, beta
       and default release corresponding to different staging levels of the  software.	 We  also
       use release names default and minimal to provide complete releases or subset releases.  In
       both of these cases, it only makes sense to sup one release of the collections.	 Releases
       have also been used in private or external sups to provide subsets of collections where it
       makes sense to pick up several of the releases.	For example the Mach 3.0  kernel  sources
       has  a  default	release  of  machine independent sources and separate releases of machine
       dependent sources for each supported platform.

       In performing an upgrade, the file server constructs a list of files included in the spec-
       ified 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 speci-
       fied.   The  list of collections is optional and if specified will be the only collections
       upgraded.  The following flags affect all collections specified:

       -s     As described above.

       -t     When this flag is given, sup will print the time	that  each  collection	was  last
	      upgraded, rather than performing actual upgrades.

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

       -S     Operate silently printing messages only on errors.

       -N     Sup will trace network messages sent and received that implement	the  sup  network
	      protocol.

       -P     Sup will use a set of non-privileged network ports reserved for debugging purposes.

       The  remaining  flags  affect  all  collections unless an explicit list of collections are
       given with the flags.  Multiple flags may be specified together that affect the same  col-
       lections.   For	the sake of convenience, any flags that always affect all collections can
       be  specified  with  flags  that  affect  only  some  collections.    For   example,   sup
       -sde=coll1,coll2 would perform a system upgrade, and the first two collections would allow
       both file deletions and command executions.  Note that this is not the same command as sup
       -sde=coll1  coll2,  which  would perform a system upgrade of just the coll2 collection and
       would ignore the flags given for the coll1 collection.

       -a     All files in the collection will be copied from the repository, regardless of their
	      status  on  the current machine.	Because of this, it is a very expensive operation
	      and should only be done for small collections if data corruption is  suspected  and
	      been confirmed.  In most cases, the -o flag should be sufficient.

       -b     If the -b flag if given, or the backup supfile option is specified, the contents of
	      regular files on the local system will be saved before they  are	overwritten  with
	      new data.  The file collection maintainer can designate specific files to be worthy
	      of backing up whenever they are upgraded.  However,  such  backup  will  only  take
	      place  if  you  specify  this flag or the backup option to allow backups for a file
	      collection on your machine.  The backup mechanism will create a copy of the current
	      version  of  a file immediately before a new copy is received from the file server;
	      the copy is given the same name as the original file but is put  into  a	directory
	      called  BACKUP  within  the  directory  containing the original file.  For example,
	      /usr/sas/src/foo.c would	have  a  backup  copy  called  /usr/sas/src/BACKUP/foo.c.
	      There is no provision for automatically maintaining multiple old versions of files;
	      you would have to do this yourself.

       -B     The -B flag overrides and disables the -b flag and the backup supfile option.

       -C     The -C flag or the canonicalize supfile option,  canonicalize  all  pathnames  upon
	      reception  to  make  sure local changes from directories 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 supfile with the delete option.

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

       -e     Sup  will  execute commands sent from the repository that should be run when a file
	      is upgraded.  If the -e flag is omitted, Sup will print a  message  that	specifies
	      the  command  to execute.  This may also be specified in a supfile with the execute
	      option.

       -E     The -E flag overrides and disables the -e flag and the execute supfile option.

       -f     A list-only upgrade will be performed.  Messages will be printed that indicate what
	      would happen if an actual upgrade were done.

       -k     Sup  will  check	the modification times of files on the local disk before updating
	      them.  Only files which are newer on the repository than on the local disk will  be
	      updated; files that are newer on the local disk will be kept as they are.  This may
	      also be specified in a supfile with the keep option.

       -K     The -K flag overrides and disables the -k flag and the keep supfile option.

       -l     Normally, sup will not upgrade a collection  if  the  repository	is  on	the  same
	      machine.	 This allows users to run upgrades on all machines without having to make
	      special checks for the repository machine.  If the -l flag  is  specified,  collec-
	      tions will be upgraded even if the repository is local.

       -m     Normally, sup used standard output for messages.	If the -m flag if given, sup will
	      send mail to the user running sup, or a user  specified  with  the  notify  supfile
	      option, that contains messages printed by sup.

       -M <user>
	      like -m but send mail to the specified user.

       -o     Sup  will normally only upgrade files that have changed on the repository since the
	      last time an upgrade was performed.  That is, if the  file  in  the  repository  is
	      newer than the date stored in the when file on the client.  The -o flag, or the old
	      supfile option, will cause sup to check all files in  the  collection  for  changes
	      instead of just the new ones.

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

       -z     Normally sup transfers files directly without any other processing, but with the -z
	      flag, or the compress supfile option, sup will compress the file before sending  it
	      across the network and uncompress it and restore all the correct file attributes at
	      the receiving end.

       -Z     The -Z flag overrides and disables the -z flag and the compress supfile option.

       -v     Normally, sup will only print messages if there are problems.  This flag causes sup
	      to also print messages during normal progress showing what sup is doing.

SETTING UP UPGRADES
       Each  file collection to be upgraded must have a base directory which contains a subdirec-
       tory called sup that will be used by the sup program; it will be created automatically  if
       you  do	not  create  it.   Sup	will  put subdirectories and files into this directory as
       needed.

       Sup will look for a subdirectory with the same name as the collection within the sup  sub-
       directory of the base directory.  If it exists it may contain any of the following files:

       when.rel-suffix
	      This  file  is  automatically  updated  by  sup  when  a collection is successfully
	      upgraded and contains the time that the file server, or possibly	supscan,  created
	      the  list of files in the upgrade list.  Sup will send this time to the file server
	      for generating the list of files that have been changed on the repository machine.

       refuse This file contains a list of files and directories, one per line, that  the  client
	      is not interested in that should not be upgraded.

       lock   This file is used by sup to lock a collection while it is being upgraded.  Sup will
	      get exclusive access to the lock file using flock(2), preventing more than one  sup
	      from upgrading the same collection at the same time.

       last.rel-suffix
	      This  file  contains  a list of files and directories, one per line, that have been
	      upgraded by sup in the past.  This information is used when the delete  option,  or
	      the  -d  flag is used to locate files previously upgraded that are no longer in the
	      collection that should be deleted.

       Each file collection must also be described in one or more supfiles.   When  sup  is  exe-
       cuted,  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  sup-
       file;  this line must contain the name of the collection, and possibly one or more options
       separated by spaces.  The options are:

       release=releasename
	      If a collection contains multiple releases, you need to specify which  release  you
	      want.   You can only specify one release per line, so if you want multiple releases
	      from the same collections, you will need to specify the collection more than  once.
	      In  this	case, you should use the use-rel-suffix option in the supfile to keep the
	      last and when files for the two releases separate.

       base=directory
	      The usual default name of the base directory for a collection  is  described  below
	      (see  FILES); if you want to specify another directory name, use this option speci-
	      fying the desired directory.

       prefix=directory
	      Each collection may also have an associated prefix directory which is used  instead
	      of the base directory to specify in what directory files within the collection will
	      be placed.

       host=hostname
       hostbase=directory
	      System collections are supported by the system maintainers, and sup will	automati-
	      cally  find  out	the  name of the host machine and base directory on that machine.
	      However, you can also upgrade private collections; you simply  specify  with  these
	      options  the hostname of the machine containing the files and the directory used as
	      a base directory for the file server on that machine.  Details of setting up a file
	      collection are given in the section below.

       login=accountid
       password=password
       crypt=key
	      Files  on  the  file  server  may  be  protected,  and network transmissions may be
	      encrypted.  This prevents unauthorized access to files via sup.  When files are not
	      accessible to the default account (e.g.  the anon anonymous account), you can spec-
	      ify an alternative accountid and password for the file server to use on the reposi-
	      tory  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  collec-
	      tion  on	the  repository must specify the same key or else sup will not be able to
	      upgrade files from that collection.  In this case, the default account used by  the
	      file  server on the repository machine will be the owner of the encryption key file
	      (see FILES) rather than the anon anonymous account.

       notify=address
	      If you use the -m option to receive log messages by mail, you  can  have	the  mail
	      sent  to	different  user,  possibly on another host, than the user running the sup
	      program.	Messages will be sent to the specified address, which can  be  any  legal
	      netmail  address.  In particular, a project maintainer can be designated to receive
	      mail for that project's file collection from all users running sup to upgrade  that
	      collection.

       backup As described above under the -b flag.

       delete As described above under the -d flag.

       execute
	      As described above under the -e flag.

       keep   As described above under the -k flag.

       old    As described above under the -o flag.

       use-rel-suffix
	      Causes the release name to be used as a suffix to the last and when files.  This is
	      necessary whenever you are supping more than one release in the same collection.

PREPARING A FILE COLLECTION REPOSITORY
       A set of files residing on a repository must be prepared before sup client  processes  can
       upgrade	those files.  The collection must be given a name and a base directory.  If it is
       a private collection, client users must be told the name  of  the  collection,  repository
       host, and base directory; these will be specified in the supfile via the host and hostbase
       options.  For a system-maintained file collection, entries must be placed  into	the  host
       list file and directory list file as described in supservers(8).

       Within the base directory, a subdirectory must be created called sup .  Within this direc-
       tory there must be a subdirectory for each collection using  that  base	directory,  whose
       name  is  the name of the collection; within each of these directories will be a list file
       and possibly a prefix file, a host file, an encryption key file, a log  file  and  a  scan
       file.  The filenames are listed under FILES below.

       prefix Normally,  all  files  in  the collection are relative to the base directory.  This
	      file contains a single line which is the name of a directory to be used in place of
	      the base directory for file references.

       host   Normally, all remote host machines are allowed access to a file collection.  If you
	      wish to restrict access to specific remote hosts	for  this  collection,	put  each
	      allowed  hostname on a separate line of text in this file.  If a host has more than
	      one name, only one of its names needs to be listed.  The name LOCAL can be used  to
	      grant  access  to  all hosts on the local network.  The host name may be a  numeric
	      network address or a network name.  If a crypt appears on the same line as the host
	      name, that crypt will be used for that host.  Otherwise, the crypt appearing in the
	      crypt file, if any will be used.

       crypt  If you wish to use the sup data encryption mechanism,  create  an  encryption  file
	      containing, on a single line of text, the desired encryption key.  Client processes
	      must then specify the same key with the crypt option in the supfile or they will be
	      denied  access to the files.  In addition, actual network transmission of file con-
	      tents and filenames will be encrypted.

       list   This file describes the actual list of files to be included in  this  file  collec-
	      tion, 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:  pre-
	      fix=dirname  to  use  a  different  parent directory for the files in this release.
	      list=listname to specify the list of files in the release.  scan=scanfile  must  be
	      used  in	multi-release collections that are scanned to keep the scan files for the
	      different releases separate.  host=hostfile to allow  different  host  restrictions
	      for  this  release.   next=release  used	to chain releases together.  This has the
	      effect of making one release be a combination of several other  releases.   If  the
	      same  file  appears  in  more than one chained release, the first one found will be
	      used.  If these files are not specified for  a  release  the  default  names:  pre-
	      fix,list,scan and host will be used.

       scan   This  file,  created  by	supscan,  is the list of filenames that correspond to the
	      instructions in the list file.  The scan file is only used for  frequently  updated
	      file  collections; it makes the file server run much faster.  See supservers(8) for
	      more information.

       lock   As previously mentioned, this file is used to indicate that the  collection  should
	      be  locked while upgrades are in progress.  All file servers will try to get shared
	      access to the lock file with flock(2).

       logfile
	      If a log file exists in the collection directory, the file server will  append  the
	      last  time an upgrade was successfully completed, the time the last upgrade started
	      and finished, and the name of the host requesting the upgrade.

       It should be noted that sup allows several different named collections  to  use	the  same
       base directory.	Separate encryption, remote host access, and file lists are used for each
       collection, since these files reside in subdirectories basedir/sup/coll.name.

       The list file is a text file with one command on each line.  Each command contains a  key-
       word  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 com-
       mands 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 speci-
	      fied, and no recursive filename construction is performed;  you  must  specify  the
	      names of the specific files to be backed up before upgrading.

       noaccount filename ...
	      The  accounting  information of the specified file(s) will not be preserved by sup.
	      Accounting information consists of the owner, group, mode and modified  time  of	a
	      file.

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

       rsymlink dirname ...
	      All symbolic links in the specified directory and  its  subdirectories  are  to  be
	      treated as symbolic links.  That is the links will be transferred and not the files
	      to which they point.

       execute exec-command (filename ...)
	      The exec-command you specified will be executed on the client process whenever  any
	      of the files listed in parentheses are upgraded.	A special token, %s, may be spec-
	      ified in the exec-command and will be replaced by the name of  the  file	that  was
	      upgraded.  For example, if you say execute ranlib %s (libc.a), then whenever libc.a
	      is upgraded, the client machine will execute ranlib libc.a.   As	described  above,
	      the  client  must  invoke  sup with the -e flag to allow the automatic execution of
	      command files.

       include listfile ...
	      The specified listfiles will be read at this point.  This is useful when	one  col-
	      lection  subsumes  other	collections; the larger collection can simply specify the
	      listfiles for the smaller collections contained within it.

       The order in which the command lines appear in the list file does not matter.  Blank lines
       may appear freely in the list file.

FILES
       Files on the client machine for sup:

       /etc/supfiles/coll.list
	      supfile used for -s flag

       /etc/supfiles/coll.what
	      supfile used for -s flag when -t flag is also specified

       /etc/supfiles/coll.host
	      host name list for system collections

       base-directory/sup/collection/last.release
	      recorded list of files in collection as of last upgrade

       base-directory/sup/collection/lock
	      file used to lock collection

       base-directory/sup/collection/refuse
	      list of files to refuse in collection

       base-directory/sup/collection/when.release
	      recorded time of last upgrade

       /usr/sup/collection
	      default base directory for file collection

       Files needed on each repository machine for the file server:

       /etc/supfiles/coll.dir
	      base directory list for system collections

       base-directory/sup/collection/crypt
	      data  encryption	key  for  a  collection.   the	owner of this file is the default
	      account used when data encryption is specified

       base-directory/sup/collection/host
	      list of remote hosts allowed to upgrade a collection

       base-directory/sup/collection/list
	      list file for a collection

       base-directory/sup/collection/lock
	      lock file for a collection

       base-directory/sup/collection/logfile
	      log file for a collection

       base-directory/sup/collection/prefix
	      file containing the name of the prefix directory for a collection

       base-directory/sup/collection/scan
	      scan file for a collection

       /usr/collection
	      default base directory for a file collection

SEE ALSO
       supservers(8)
       The SUP Software Upgrade Protocol, S. A. Shafer, CMU Computer Science Department, 1985.

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 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 care-
       ful*!

					     10/01/08					   SUP(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 02:22 AM.