home | help
UNTITLED()			      LOCAL			      UNTITLED()

NAME
     csup -- network distribution package for CVS repositories

SYNOPSIS
     csup [-146ksvzZ] [-A addr] [-b base] [-c collDir] [-d delLimit] [-h host]
	  [-i pattern] [-l lockfile] [-L verbosity] [-p port] [-r maxRetries]
	  supfile

DESCRIPTION
     csup  is a software package for updating collections of files across a net-
     work.  It is a rewrite of the CVSup software in C.  This  manual  page  de-
     scribes the usage of the csup client program.

     Unlike  more  traditional	network distribution packages, such as rdist and
     sup, csup has specific optimizations  for	distributing  CVS  repositories.
     csup  takes  advantage  of the properties of CVS repositories and the files
     they contain (in particular, RCS files), enabling	it  to	perform  updates
     much faster than traditional systems.

     csup  is  a general-purpose network file updating package.  It is extremely
     fast, even for collections of files which have nothing to do  with  CVS  or
     RCS.

OPTIONS
     The  client  program csup requires at least a single argument, supfile.  It
     names a file describing one or more collections of files to be  transferred
     and/or  updated  from  the server.  The supfile has a format similar to the
     corresponding file used by sup.  In most cases, csup can use  existing  sup
     supfiles.

     The following options are supported by csup:

     -1 	 Disables  automatic  retries  when  transient	failures  occur.
		 Without this option, a transient failure such as a dropped net-
		 work connection causes csup to retry repeatedly, using  random-
		 ized  exponential backoff to space the retries.  This option is
		 equivalent to -r 0.

     -4 	 Forces csup to use IPv4 addresses only.

     -6 	 Forces csup to use IPv6 addresses only.

     -A addr	 Specifies a local address to bind to  when  connecting  to  the
		 server.   The	local  address	might be a hostname or a numeric
		 host address string consisting of a dotted decimal IPv4 address
		 or an IPv6 address.  This may be useful  on  hosts  which  have
		 multiple IP addresses.

     -b base	 Specifies the base directory under which csup will maintain its
		 bookkeeping  files,  overriding  any base specifications in the
		 supfile.

     -c collDir  Specifies the subdirectory of base where the information  about
		 the collections is maintained.  The default is sup.

     -d delLimit
		 Specifies  the maximum number of files that may be deleted in a
		 single update run.  Any attempt to exceed the limit results  in
		 a fatal error.  This can provide some protection against tempo-
		 rary  configuration  mistakes on the server.  The default limit
		 is infinity.

     -h host	 Specifies the server host to contact, overriding any host spec-
		 ifications in the supfile.

     -i pattern  Causes csup to include  only  files  and  directories	matching
		 pattern  in  the  update.   If a directory matches the pattern,
		 then the entire subtree rooted at the	directory  is  included.
		 If  this  option  is specified multiple times, the patterns are
		 combined using the `or' operation.  If no -i options are given,
		 the default is to update all files in each collection.

		 The pattern is a standard file name pattern.  It is interpreted
		 relative to the collection's prefix directory.   Slash  charac-
		 ters  are  matched  only  by  explicit  slashes in the pattern.
		 Leading periods in file name are not treated specially.

     -k 	 Causes csup to keep the temporary  copies  of	any  incorrectly
		 edited files, in the event of checksum mismatches.  This option
		 is  for  debugging, to help determine why the files were edited
		 incorrectly.  Regardless of whether this option  is  specified,
		 the  permanent  versions of faulty files are replaced with cor-
		 rect versions obtained by transferring the files in  their  en-
		 tirety.  Such transfers are called fixups.

     -l lockfile
		 Creates and locks the lockfile while the update is in progress.
		 If  lockfile  is  already locked, csup fails without performing
		 automatic retries.  This option is useful when csup is executed
		 periodically from cron.  It prevents  a  job  from  interfering
		 with  an  earlier job that is perhaps taking extra long because
		 of network problems.

		 The process-ID is written to the lock file in	text  form  when
		 the lock is successfully acquired.  Upon termination of the up-
		 date, the lock file is removed.

     -L verbosity
		 Sets  the verbosity level for output.	A level of 0 causes csup
		 to be completely silent unless errors occur.  A level of 1 (the
		 default) causes each updated file to be listed.  A level  of  2
		 provides  more detailed information about the updates performed
		 on each file.	All messages are directed to the  standard  out-
		 put.

     -p port	 Sets  the  TCP  port  to  which csup attempts to connect on the
		 server host.  The default port is 5999.

     -r maxRetries
		 Limits the number of automatic retries that will  be  attempted
		 when  transient errors such as lost network connections are en-
		 countered.  By default, csup will retry indefinitely  until  an
		 update is successfully completed.  The retries are spaced using
		 randomized  exponential  backoff.  Note that -r 0 is equivalent
		 to the -1 option.

     -s 	 Suppresses the check of each client file's status against  what
		 is  recorded  in  the list file.  Instead, the list file is as-
		 sumed to be accurate.	This option greatly reduces  the  amount
		 of  disk  activity and results in faster updates with less load
		 on the client host.  However it should only be used if client's
		 files are never modified locally in any way.  Mirror sites  may
		 find  this  option  beneficial to reduce the disk load on their
		 systems.  For safety, even mirror sites should run  csup  occa-
		 sionally (perhaps once a day) without the -s option.

		 Without  the  -s  option,  csup performs a stat(2) call on each
		 file and verifies that its attributes match those  recorded  in
		 the list file.  This ensures that any file changes made outside
		 of csup are detected and corrected.

		 If the -s option is used when one or more files have been modi-
		 fied locally, the results are undefined.  Local file damage may
		 remain  uncorrected,  updates	may be missed, or csup may abort
		 prematurely.

     -v 	 Prints the version number and	exits,	without  contacting  the
		 server.

     -z 	 Enables  compression  for  all  collections, as if the compress
		 keyword were added to every collection in the supfile.

     -Z 	 Disables compression for all collections, as  if  the	compress
		 keyword were removed from every collection in the supfile.

     The  supfile  is a text file which specifies the file collections to be up-
     dated.  Comments begin with `#' and extend to the end of the  line.   Lines
     that  are	empty except for comments and white space are ignored.	Each re-
     maining line begins with the name of a server-defined collection of  files.
     Following the collection name on the line are zero or more keywords or key-
     word=value pairs.

     Default  settings	may  be  specified  in	lines  whose  collection name is
     *default.	Such defaults will apply to subsequent	lines  in  the	supfile.
     Multiple *default lines may be present.  New values augment or override any
     defaults specified earlier in the supfile.  Values specified explicitly for
     a collection override any default values.

     The most commonly used keywords are:

     release=releaseName
		 This  specifies  the  release of the files within a collection.
		 Like collection names, release names are defined by the  server
		 configuration files.  Usually there is only one release in each
		 collection,  but  there  may  be any number.  Collections which
		 come from a CVS repository often use release=cvs by convention.
		 Non-CVS collections conventionally use release=current.

     base=base	 This specifies a directory under which csup will  maintain  its
		 bookkeeping  files,  describing the state of each collection on
		 the client machine.  The base	directory  must  already  exist;
		 csup  will  not  create  it.	The  default  base  directory is
		 /usr/local/etc/csup.

     prefix=prefix
		 This is the directory under which updated files will be placed.
		 By default, it is the same as base.  If it is not  an	absolute
		 pathname,  it	is interpreted relative to base.  The prefix di-
		 rectory must already exist; csup will not create it.

		 As a special case, if prefix is a symbolic link pointing  to  a
		 nonexistent  file named `SKIP', then csup will skip the collec-
		 tion.	The parameters associated with the collection are  still
		 checked  for  validity,  but none of its files will be updated.
		 This feature allows a site to use a standard supfile on several
		 machines, yet control which collections get updated on  a  per-
		 machine basis.

     host=hostname
		 This  specifies the server machine from which all files will be
		 taken.  csup requires that all collections in a single run come
		 from the same host.  If you wish  to  update  collections  from
		 several different hosts, you must run csup several times.

     delete	 The  presence	of  this keyword gives csup permission to delete
		 files.  If it is missing, no files will be deleted.

		 The presence of the delete keyword  puts  csup  into  so-called
		 exact	mode.	In  exact  mode,  csup does its best to make the
		 client's files correspond to those on	the  server.   This  in-
		 cludes  deleting  individual  deltas and symbolic tags from RCS
		 files, as well as deleting entire files.  In exact  mode,  csup
		 verifies  every edited file with a checksum, to ensure that the
		 edits have produced a file identical to the master copy on  the
		 server.  If the checksum test fails for a file, then csup falls
		 back upon transferring the entire file.

		 In  general,  csup  deletes  only  files which are known to the
		 server.  Extra files present in  the  client's  tree  are  left
		 alone,  even in exact mode.  More precisely, csup is willing to
		 delete two classes of files:
		 *   Files that were previously created or updated by  csup  it-
		     self.
		 *   Checked-out  versions  of files which are marked as dead on
		     the server.

     use-rel-suffix
		 Causes csup to append a suffix constructed from the release and
		 tag to the name of each list file that it maintains.  See  "THE
		 LIST FILE" for details.

     compress	 This  enables	compression of all data sent across the network.
		 Compression is quite effective, normally eliminating 65% to 75%
		 of the bytes that would otherwise need to be transferred.  How-
		 ever, it is costly in terms of CPU time on both the client  and
		 the  server.	On local area networks, compression is generally
		 counter-productive; it actually slows down  file  updates.   On
		 links	with  speeds  of 56K bits/second or less, compression is
		 almost always beneficial.  For network links  with  speeds  be-
		 tween these two extremes, let experimentation be your guide.

		 The -z command line option enables the compress keyword for all
		 collections,  regardless  of  what is specified in the supfile.
		 Likewise, the -Z command line option disables the compress  op-
		 tion  for all collections.  csup uses a looser checksum for RCS
		 files, which ignores harmless differences in white space.  Dif-
		 ferent versions of CVS and RCS produce a variety of differences
		 in white space for the same RCS files.  Thus the strict  check-
		 sum  can  report  spurious mismatches for files which are logi-
		 cally identical.  This can lead to numerous unneeded  "fixups",
		 and thus to slow updates.

     umask=n	 Causes  csup  to  use a umask value of n (an octal number) when
		 updating the files in the collection.	This option  is  ignored
		 if preserve is specified.

     Some  additional,	more specialized keywords are described below.	Unrecog-
     nized keywords are silently ignored for backward compatibility with sup.

CVS MODE
     CVSup supports two primary modes of operation.  They are  called  CVS  mode
     and checkout mode.

     In  CVS  mode, the client receives copies of the actual RCS files making up
     the master CVS repository.  CVS mode is the default mode of operation.   It
     is  appropriate  when  the  user  wishes to maintain a full copy of the CVS
     repository on the client machine.

     CVS mode is also appropriate for file collections which are not based  upon
     a	CVS  repository.  The files are simply transferred verbatim, without in-
     terpretation.

CHECKOUT MODE
     In checkout mode, the client receives specific revisions of files,  checked
     out  directly  from  the server's CVS repository.	Checkout mode allows the
     client to receive any version from the repository,  without  requiring  any
     extra disk space on the server for storing multiple versions in checked-out
     form.   Checkout mode provides much flexibility beyond that basic function-
     ality, however.  The client can specify any CVS symbolic tag, or any  date,
     or  both,	and  csup will provide the corresponding checked-out versions of
     the files in the repository.

     Checkout mode is selected on a per-collection basis, by the presence of one
     or both of the following keywords in the supfile:

     tag=tagname
		 This specifies a symbolic tag that should be used to select the
		 revisions that are checked out from the  CVS  repository.   The
		 tag  may  refer  to either a branch or a specific revision.  It
		 must be symbolic; numeric revision numbers are not supported.

		 For the FreeBSD source repository, the most commonly used  tags
		 will be:

		 RELENG_6  The `stable' branch.

		 .	   The main branch (the `current' release).  This is the
			   default, if only the date keyword is given.

     date=[cc]yy.mm.dd.hh.mm.ss
		 This  specifies  a date that should be used to select the revi-
		 sions that are checked out from the CVS repository.  The client
		 will receive the revisions that were in effect at the specified
		 date and time.

		 At present, the date format is inflexible.  All 17 or 19  char-
		 acters must be specified, exactly as shown.  For the years 2000
		 and beyond, specify the century cc.  For earlier years, specify
		 only the last two digits yy.  Dates and times are considered to
		 be  GMT.   The  default  date	is  `.', which means "as late as
		 possible".

     To enable checkout mode, you must specify at least one of	these  keywords.
     If both are missing, csup defaults to CVS mode.

     If  both  a  branch tag and a date are specified, then the revisions on the
     given branch, as of the given date, will be checked out.  It is  permitted,
     but not particularly useful, to specify a date with a specific release tag.

     In  checkout mode, the tag and/or date may be changed between updates.  For
     example, suppose that a collection has been transferred using the	specifi-
     cation   `tag=.'.	 The  user  could  later  change  the  specification  to
     `tag=RELENG_3'.  This would cause csup to edit  the  checked-out  files  in
     such a way as to transform them from the `current' versions to the `stable'
     versions.	 In  general, csup is willing to transform any tag/date combina-
     tion into any other tag/date combination, by applying the	intervening  RCS
     deltas to the existing files.

     When  transforming  a  collection	of checked-out files from one tag to an-
     other, it is important to specify the list keyword in the supfile,  to  en-
     sure  that the same list file is used both before and after the transforma-
     tion.  The list file is described in "THE LIST FILE", below.

THE LIST FILE
     For efficiency, csup maintains a  bookkeeping  file  for  each  collection,
     called the list file.  The list file contains information about which files
     and revisions the client currently possesses.  It also contains information
     used  for	verifying that the list file is consistent with the actual files
     in the client's tree.

     The list file is not strictly necessary.  If it is deleted, or becomes  in-
     consistent  with the actual client files, csup falls back upon a less effi-
     cient method of identifying the client's files and performing its	updates.
     Depending	on  csup's  mode  of operation, the fallback method employs time
     stamps, checksums, or analysis of RCS files.

     Because the list file is not essential, csup is able to "adopt" an existing
     file tree acquired by FTP or from a CD-ROM.  csup identifies  the	client's
     versions  of  the files, updates them as necessary, and creates a list file
     for future use.  Adopting a foreign file tree is not as fast as  performing
     a normal update.  It also produces a heavier load on the server.

     The list file is stored in a collection-specific directory; see "FILES" for
     details.	Its  name  always  begins  with  `checkouts'.	If  the  keyword
     use-rel-suffix is specified in the supfile, a suffix, formed from	the  re-
     lease and tag, is appended to the name.  The default suffix can be overrid-
     den by specifying an explicit suffix in the supfile:

     list=suffix
		 This specifies a suffix for the name of the list file.  A lead-
		 ing  dot is provided automatically.  For example, `list=stable'
		 would produce a list file named checkouts.stable, regardless of
		 the release, tag, or use-rel-suffix keyword.

REFUSE FILES
     The user can specify sets of files that he does not wish to  receive.   The
     files  are  specified as file name patterns in so-called refuse files.  The
     patterns are separated by whitespace, and multiple patterns  are  permitted
     on  each line.  Files and directories matching the patterns are neither up-
     dated nor deleted; they are simply ignored.

     There is currently no provision for comments in refuse files.

     The patterns are similar to those of sh(1), except that there is no special
     treatment for slashes or for filenames that begin with a period.  For exam-
     ple, the pattern `*.c' will match any file name ending with `.c'  including
     those  in subdirectories, such as `foo/bar/lam.c'.  All patterns are inter-
     preted relative to the collection's prefix directory.

     If the files are coming from a CVS repository, as is usually the case, then
     they will be RCS files. These have a `,v' suffix which must be  taken  into
     account  in  the patterns. For example, the FreeBSD documentation files are
     in a sub-directory of base called `doc'.  If `Makefile' from that directory
     is not required then the line

	   doc/Makefile

     will not work because the file on the server is called `Makefile,v.' A bet-
     ter solution would be

	   doc/Makefile*

     which will match whether `Makefile' is an RCS file or not.

     As another example, to receive the FreeBSD documentation files without  the
     Japanese,	Russian, and Chinese translations, create a refuse file contain-
     ing the following lines:

	   doc/ja*
	   doc/ru*
	   doc/zh*

     As many as three refuse files are examined for each  supfile  line.   There
     can  be a global refuse file named base/collDir/refuse which applies to all
     collections and releases.	There can be a per-collection refuse file  named
     base/collDir/collection/refuse which applies to a specific collection.  Fi-
     nally, there can be a per-release and tag refuse file which applies only to
     a	given release/tag combination within a collection.  The name of the lat-
     ter is formed by suffixing the name of the per-collection	refuse	file  in
     the  same	manner as described above for the list file.  None of the refuse
     files are required to exist.

     csup has a built-in default value of /usr/local/etc/cvsup for base and  sup
     for collDir but it is possible to override both of these. The value of base
     can be changed using the -b option or a base=pathname entry in the supfile.
     (If  both	are  used  the	-b option will override the supfile entry.)  The
     value of collDir can only be changed  with  the  -c  option;  there  is  no
     supfile command to change it.

     As  an  example,  suppose that the base and collDir both have their default
     values, and that the collection and release are `src-all'	and  `cvs',  re-
     spectively.    Assume  further  that  checkout  mode  is  being  used  with
     `tag=RELENG_3'.  The three possible refuse files would then be named:

	   /usr/local/etc/cvsup/sup/refuse
	   /usr/local/etc/cvsup/sup/src-all/refuse
	   /usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3

     If the supfile includes the command base=/foo the refuse files would be:

	   /foo/sup/refuse
	   /foo/sup/src-all/refuse
	   /foo/sup/src-all/refuse.cvs:RELENG_3

     If -b /bar is used (even with base=/foo in the supfile):

	   /bar/sup/refuse
	   /bar/sup/src-all/refuse
	   /bar/sup/src-all/refuse.cvs:RELENG_3

     and with -c stool as well:

	   /bar/stool/refuse
	   /bar/stool/src-all/refuse
	   /bar/stool/src-all/refuse.cvs:RELENG_3

csup AND FIREWALLS
     In its default mode, csup will work through any firewall which permits out-
     bound connections to port 5999 of the server host.

USING csup WITH SOCKS
     csup can be used through a SOCKS proxy server with  the  standard	runsocks
     command.  Your csup executable needs to be dynamically-linked with the sys-
     tem libraries for runsocks to work properly.

USING ssh PORT FORWARDING
     As  an alternative to SOCKS, a user behind a firewall can penetrate it with
     the TCP port forwarding provided by the Secure Shell package ssh.	The user
     must have a login account on the CVSup server host in  order  to  do  this.
     The procedure is as follows:

     1.   Establish a connection to the server host with ssh, like this:

	  ssh -f -x -L 5999:localhost:5999 serverhost sleep 60

	  Replace  serverhost  with  the  hostname of the CVSup server, but type
	  `localhost' literally.  This sets up	the  required  port  forwarding.
	  You must start csup before the 60-second sleep finishes.  Once the up-
	  date	has  begun, ssh will keep the forwarded channels open as long as
	  they are needed.

     2.   Run csup on the local host, including the arguments `-h localhost'  on
	  the command line.

FILES
     /usr/local/etc/cvsup	       Default base directory.
     sup			       Default collDir subdirectory.
     base/collDir/collection/checkouts*
				       List files.

SEE ALSO
     cvs(1), rcsintro(1), ssh(1).

     http://mu.org/~mux/csup.html

AUTHORS
     Maxime  Henrion  <mux@FreeBSD.org>  is  the  author of csup, the rewrite of
     CVSup in C.  John Polstra <jdp@polstra.com> is the author of CVSup.

LEGALITIES
     CVSup is a registered trademark of John D. Polstra.

     csup is released under a 2-clauses BSD license.

BUGS
     An RCS file is not recognized as such unless its name ends with `,v'.

     Any directory named `Attic' is assumed to be a CVS Attic,	and  is  treated
     specially.

FreeBSD 			February 1, 2006			 CSUP(1)

home | help