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.

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

       -i     Normally,	 sup  will fail	to upgrade any files that are ETXTBSY.
	      The -i flag, or the unlinkbusy supfile option, will cause	sup to
	      try  to  upgrade a busy file by unlinking	it before the replace-
	      ment file	is installed.  The option is intended for environments
	      where  upgrades  to  possibly running binaries or	libraries will
	      take place.  Some	operating systems (HPUX) do not	allow the  un-
	      link  system  call  to  succeed on ETXTBSY files.	 If the	unlink
	      does not succeed,	an attempt is made to rename the file to file-
	      name.sup#sup-pid.moved.	The  new  name is logged in either the
	      system default rename log	file, /usr/local/etc/sup.moved,	or  in
	      a	 logfile  as set by the	renamelog supfile option.  The logfile
	      allows for easy deletion of  ETXTBSY  files  once	 they  are  no
	      longer  in  use.	 A typical time	to perform the deletions is at
	      system boot time with something similar to:

		     cat /usr/local/etc/sup.moved | xargs rm -rf

       -I     The -I flag overrides and	disables  the  -i  flag	 and  the  un-
	      linkbusy supfile option.

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

       -u     The -u flag, or the noupdate supfile option prevent updates from
	      occurring	for regular files where	the modification time and mode
	      hasn't changed.

       -U     The  -U flag overrides and disables the -u flag and the noupdate
	      supfile 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
	      recieving	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 ption	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.

       renamelog=filename
	      When the unlinkbusy or -i	option is enabled, but the system can-
	      not  unlink  a  busy file, it will rename	it instead and log the
	      new filename.  Logging will occur	to the system  default	rename
	      log  file	or to the specified filename in	the renamelog entry of
	      a	supfile.

       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.

       unlinkbusy
	      As described above under the -i flag.

       noupdate
	      As described above under the -u flag.

       compress
	      As described above under the -z 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 adddress 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 par-
	      ent directory for	the files in this release.  list=_listname_ to
	      specify the list of files	in the release.	 scan=_scanfile_ tells
	      supscan  to  generate  scanfile  for this	release.  Supscan will
	      only generate scan files for releases that specify a scanfile or
	      for  collections	that do	not have a releases file.  host=_host-
	      file_ to allow different host  restrictions  for	this  release.
	      next=_release_ used to chain releases together. This has the ef-
	      fect of making one release be a combination  of  serveral	 other
	      releases.	 If the	same file appears in more than one chained re-
	      lease, the first one found will be used.	If these files are not
	      specified	for a release the default names: prefix, list 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 subdirectorie _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.

       rename filename dest-filename...
	      The  rename command allows for a file on the server to be	placed
	      on the client under a different name.  To	prevent	confusion  and
	      ease  its	 use,  the rename option implicitly omits any files on
	      the server that have the same name as dest-filename.

       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	transfered  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.  The timestamp of the upgraded file is maintained even if
	      the executed command might change	it so as to prevent an upgrade
	      with every sup.

       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:

       /usr/cs/lib/supfiles/coll.list
	      supfile used for -s flag

       /usr/cs/lib/supservers/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:

       /usr/cs/lib/supservers/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

       /usr/local/etc/sup.moved
	      log file for files renamed by the	unlinkbusy option

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

       <base-directory>/sup/<collection>/scan
	      default scan file	for a collection if no release file exists

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

				   03/15/95				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+5.2-RELEASE+and+Ports>

home | help