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

FreeBSD Manual Pages


home | help
CSUP(1)			  BSD General Commands Manual		       CSUP(1)

     csup -- network distribution package for CVS repositories

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

     csup is a software	package	for updating collections of files across a
     network.  It is a rewrite of the CVSup software in	C.  This manual	page
     describes 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

     The client	program	csup requires at least a single	argument, supfile.  It
     names a file describing one or more collections of	files to be trans-
     ferred 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 ex-
     isting 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
		 network connection causes csup	to retry repeatedly, using
		 randomized 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 ad-
		 dress 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
		 temporary configuration mistakes on the server.  The default
		 limit is infinity.

     -h	host	 Specifies the server host to contact, overriding any host
		 specifications	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 inter-
		 preted	relative to the	collection's prefix directory.	Slash
		 characters are	matched	only by	explicit slashes in the	pat-
		 tern.	Leading	periods	in file	name are not treated spe-

     -k		 Causes	csup to	keep the temporary copies of any incorrectly
		 edited	files, in the event of checksum	mismatches.  This op-
		 tion 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 re-
		 placed	with correct versions obtained by transferring the
		 files in their	entirety.  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
		 update, 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 up-
		 dates performed on each file.	All messages are directed to
		 the standard output.

     -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
		 encountered.  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
		 assumed 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 occasionally (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 out-
		 side of csup are detected and corrected.

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

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

     -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	key-
     words or keyword=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 explic-
     itly for a	collection override any	default	values.

     The most commonly used keywords are:

		 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	re-
		 lease in each collection, but there may be any	number.	 Col-
		 lections which	come from a CVS	repository often use
		 release=cvs by	convention.  Non-CVS collections convention-
		 ally 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

		 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	directory 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	col-
		 lection.  The parameters associated with the collection are
		 still checked for validity, but none of its files will	be up-
		 dated.	 This feature allows a site to use a standard supfile
		 on several machines, yet control which	collections get	up-
		 dated on a per-machine	basis.

		 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

     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:
		 o   Files that	were previously	created	or updated by csup it-
		 o   Checked-out versions of files which are marked as dead on
		     the server.

		 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.
		 However, it is	costly in terms	of CPU time on both the	client
		 and the server.  On local area	networks, compression is gen-
		 erally	counter-productive; it actually	slows down file	up-
		 dates.	 On links with speeds of 56K bits/second or less, com-
		 pression is almost always beneficial.	For network links with
		 speeds	between	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 sup-
		 file.	Likewise, the -Z command line option disables the
		 compress option for all collections.  csup uses a looser
		 checksum for RCS files, which ignores harmless	differences in
		 white space.  Different versions of CVS and RCS produce a va-
		 riety of differences in white space for the same RCS files.
		 Thus the strict checksum can report spurious mismatches for
		 files which are logically identical.  This can	lead to	numer-
		 ous 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.

     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,	with-
     out interpretation.

     In	checkout mode, the client receives specific revisions of files,
     checked out directly from the server's CVS	repository.  Checkout mode al-
     lows the client to	receive	any version from the repository, without re-
     quiring any extra disk space on the server	for storing multiple versions
     in	checked-out form.  Checkout mode provides much flexibility beyond that
     basic functionality, 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:

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

		 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.

		 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
		 characters 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 permit-
     ted, but not particularly useful, to specify a date with a	specific re-
     lease 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
     specification `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
     combination into any other	tag/date combination, by applying the inter-
     vening 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 transfor-
     mation.  The list file is described in THE	LIST FILE, below.

     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 in-
     formation 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
     inconsistent with the actual client files,	csup falls back	upon a less
     efficient method of identifying the client's files	and performing its up-
     dates.  Depending on csup's mode of operation, the	fallback method	em-
     ploys time	stamps,	checksums, or analysis of RCS files.

     Because the list file is not essential, csup is able to "adopt" an	exist-
     ing 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

     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	over-
     ridden by specifying an explicit suffix in	the supfile:

		 This specifies	a suffix for the name of the list file.	 A
		 leading 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.

     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
     updated 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 spe-
     cial treatment for	slashes	or for filenames that begin with a period.
     For example, the pattern `*.c' will match any file	name ending with `.c'
     including those in	subdirectories,	such as	`foo/bar/lam.c'.  All patterns
     are interpreted 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


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


     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
     containing	the following lines:


     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 collec-
     tion.  Finally, there can be a per-release	and tag	refuse file which ap-
     plies only	to a given release/tag combination within a collection.	 The
     name of the latter	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:


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


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


     and with -c stool as well:


     In	its default mode, csup will work through any firewall which permits
     outbound connections to port 5999 of the server host.

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

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

     /usr/local/etc/cvsup	       Default base directory.
     sup			       Default collDir subdirectory.
				       List files.

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

     Maxime Henrion <> is the author of csup, the rewrite of
     CVSup in C.  John Polstra <> is the	author of CVSup.

     CVSup is a	registered trademark of	John D.	Polstra.

     csup is released under a 2-clauses	BSD license.

     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

FreeBSD			       February	1, 2006			       FreeBSD


Want to link to this manual page? Use this URL:

home | help