Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SUP(1)			    General Commands Manual			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 ma-
       chines 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 de-
       fault 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  up-
	      grades.

       -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 op-
	      tion to allow backups for	a file	collection  on	your  machine.
	      The  backup  mechanism will create a copy	of the current version
	      of a file	immediately before a new copy  is  received  from  the
	      file  server;  the  copy	is given the same name as the original
	      file but is put into a directory called BACKUP within the	direc-
	      tory    containing    the	   original    file.	For   example,
	      /usr/sas/src/foo.c   would   have	  a   backup	copy	called
	      /usr/sas/src/BACKUP/foo.c.   There is no provision for automati-
	      cally maintaining	multiple old versions of files;	you would have
	      to do this yourself.

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

       -d     Files that are no	longer in the  collection  on  the  repository
	      will  be	deleted	 if  present on	the local machine and were put
	      there by a previous sup.	This may also be specified in  a  sup-
	      file with	the delete option.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       Each  file  collection  must also be described in one or	more supfiles.
       When sup	is executed, it	reads the specified supfile to determine  what
       file collections	 and releases to upgrade.  Each	collection-release set
       is described by a single	line of	text in	the supfile;  this  line  must
       contain	the  name  of the collection, and possibly one or more options
       separated by spaces.  The options are:

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

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

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

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

       login=accountid
       password=password
       crypt=key
	      Files on the file	server may be protected, and network transmis-
	      sions may	be encrypted.  This prevents  unauthorized  access  to
	      files via	sup.  When files are not accessible to the default ac-
	      count (e.g.  the anon anonymous account),	you can	specify	an al-
	      ternative	 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 de-
       scribed 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  de-
	      sired  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	parent
	      directory	for the	files in this release.	list=listname to spec-
	      ify  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=re-
	      lease  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 in-
	      formation.

       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 ac-
       cess, 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, di-
       rectory 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  al-
	      ways command.

       omit filename ...
	      The specified file(s) (or	directories) will be excluded from the
	      list of files to be upgraded.  For example,  by  specifying  up-
	      grade  /usr/vision  and omit /usr/vision/exp, the	generated list
	      of files would include all subdirectories	and files of  /usr/vi-
	      sion except /usr/vision/exp (and its subdirectories and files).

       omitany pattern ...
	      The specified patterns are compared against the files in the up-
	      grade 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 up-
	      graded 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  up-
	      graded.	A special token, %s, may be specified in the exec-com-
	      mand and will be replaced	by the name of the file	that  was  up-
	      graded.	For  example,  if  you say execute ranlib %s (libc.a),
	      then whenever libc.a is upgraded,	the client machine  will  exe-
	      cute  ranlib libc.a.  As described above,	the client must	invoke
	      sup with the -e flag to allow the	automatic execution of command
	      files.

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

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

FILES
       Files on	the client machine for sup:

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

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

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

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

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

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

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

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

       Files needed on each repository machine for the file server:

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

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

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

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

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

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

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

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

       /usr/collection
	      default base directory for a file	collection

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

EXAMPLE
       example

BUGS
       The encryption mechanism	should	be  strengthened,  although  it's  not
       trivial.

				   02/08/92				SUP(1)

NAME | SYNOPSIS | DESCRIPTION | SETTING UP UPGRADES | PREPARING A FILE COLLECTION REPOSITORY | FILES | SEE ALSO | EXAMPLE | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sup&sektion=1&manpath=FreeBSD+7.1-RELEASE+and+Ports>

home | help