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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
CVSUP(1)		FreeBSD	General	Commands Manual		      CVSUP(1)

NAME
     cvsup -- network distribution package for CVS repositories

SYNOPSIS
     cvsup [-1aDeEgksvzZ] [-A addr] [-b	base] [-c collDir] [-d delLimit]
	   [-h host] [-i pattern] [-l lockfile]	[-L verbosity] [-p port]
	   [-P m|a|port|lo-hi|-] [-r maxRetries] supfile [destDir]

DESCRIPTION
     CVSup is a	software package for distributing and updating collections of
     files across a network.  The name CVSup refers to the package as a	whole.
     It	consists of a client program, cvsup, and a server program, cvsupd.
     This manual page describes	the general aspects of the CVSup package, as
     well as the particulars of	the cvsup client program.  For detailed	infor-
     mation about cvsupd, see cvsupd(8).

     Unlike more traditional network distribution packages, such as rdist and
     sup, CVSup	has specific optimizations for distributing CVS	repositories.
     CVSup 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.

     CVSup 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	cvsup 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, cvsup can use
     existing sup supfiles.

     An	optional argument destDir may also be specified.  If given, it names a
     directory under which all updated files will be placed.  When destDir is
     specified,	the client's original files are	left untouched.	 This feature
     is	primarily intended for testing.

     The following options are supported by cvsup:

     -1		 Disables automatic retries when transient failures occur and
		 the GUI is not	being used.  Without this option, a transient
		 failure such as a dropped network connection causes cvsup to
		 retry repeatedly, using randomized exponential	backoff	to
		 space the retries.  This option is equivalent to -r 0,	and is
		 implied when the GUI is used.

     -a		 Requires the server to	authenticate itself (prove its iden-
		 tity) to the client.  If authentication of the	server fails,
		 the update is canceled.  See AUTHENTICATION, below.

     -A	addr	 Specifies a local address (dotted quad	or hostname) to	bind
		 to when connecting to the server.  This may be	useful on
		 hosts which have multiple IP addresses.

     -b	base	 Specifies the base directory under which cvsup	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.

     -D		 Causes	cvsup to perform file deletions	only, omitting all
		 other kinds of	updates.  This is useful in some situations
		 where disk space on the client	is very	limited.  One can
		 first run cvsup with the -D option, to	free up	as much	space
		 as possible.  Then a second run can be	made, this time	with-
		 out the -D option.  If	files or directories have been renamed
		 on the	server,	this technique ensures that all	of the old
		 files are deleted on the client before	any of the new ones
		 are created.  This option is not implemented yet for checkout
		 mode.

     -e		 Enables the execution of shell	commands received from the
		 server, as if the execute keyword were	added to every collec-
		 tion in the supfile.

     -E		 Disables the execution	of shell commands received from	the
		 server, as if the execute keyword were	removed	from every
		 collection in the supfile.

     -g		 Disables the use of the graphical user	interface.  This
		 option	is implied if the DISPLAY environment variable is not
		 set.

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

     -i	pattern	 Causes	cvsup 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-
		 cially.

		 The GUI has a `Filter'	type-in	field where the	patterns may
		 be edited.

     -k		 Causes	cvsup 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 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, cvsup fails without
		 performing automatic retries.	This option is useful when
		 cvsup 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.

		 POSIX-style file locking is used, as described	in fcntl(2).
		 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 non-GUI output.  A level of 0
		 causes	cvsup 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 output.  This	option is ignored when
		 the GUI is used.

     -p	port	 Sets the TCP port to which cvsup attempts to connect on the
		 server	host.  This feature is primarily for testing.  The
		 default port is 5999.	When not in passive mode (see the
		 description of	the -P option),	the server also	uses the next
		 lower port to establish a second connection back to the
		 client.

     -P	m|a|port|lo-hi|-
		 Controls the establishment of the auxiliary TCP connection(s)
		 used to carry information between the client and the server.
		 Altogether, the client	and server require four	unidirectional
		 channels to communicate: two from the client to the server,
		 and two from the server to the	client.	 These four unidirec-
		 tional	channels can be	set up in different ways, to support
		 various firewall setups.  The modes provided for this are
		 multiplexed mode, passive mode, and active mode.  All but
		 multiplexed mode are deprecated.  Multiplexed mode can	handle
		 any situation that the	other modes can	handle.

		 By default the	channels are established in multiplexed	mode,
		 if the	server is new enough to	support	it.  Multiplexed mode
		 uses a	single TCP connection to implement the four channels.
		 A built-in packet layer multiplexes the different logical
		 channels on top of the	TCP connection,	in a manner not	unlike
		 ssh's port forwarding feature.	 This adds a very small	amount
		 of communication overhead (<1%) and a little bit of CPU over-
		 head, but it should work behind almost	any kind of firewall
		 setup.	 The firewall must permit the client host to initiate
		 connections to	port 5999 of the server	host; beyond that, no
		 special permissions are required.  To explicitly force	multi-
		 plexed	mode, use the option -P	m.

		 Multiplexed mode can be used in conjunction with a SOCKS
		 proxy server.	Simply run cvsup under the runsocks command,
		 and add @M3novm to the	end of the cvsup command line.

		 Active	mode implements	the four unidirectional	channels using
		 two bidirectional TCP connections.  The original connection
		 from the client to the	server implements two channels,	and a
		 second	TCP connection implements the other two	channels.  To
		 establish the second TCP connection, the server connects back
		 to the	client.	 With -P a, the	client listens for the connec-
		 tion on a port	chosen by the operating	system.	 Many operat-
		 ing systems use ports in the range 1024-5000 for this pur-
		 pose.	The user can specify a particular port with -P port,
		 or a range of ports with -P lo-hi.  These port	specifications
		 cannot	be used	through	a SOCKS	proxy server.

		 Passive mode is similar in that it also uses two TCP connec-
		 tions to implement the	four unidirectional channels.  How-
		 ever, in passive mode the client connects to the server to
		 create	the second TCP connection.  Passive mode can be	useful
		 when the client is behind a firewall that allows outbound
		 connections, but denies most incoming connections.  To	select
		 passive mode, use the option -P -.  Passive mode cannot be
		 used through a	SOCKS proxy server.

     -r	maxRetries
		 Limits	the number of automatic	retries	that will be attempted
		 when transient	errors such as lost network connections	are
		 encountered.  By default, when	the GUI	is not used, cvsup
		 will retry indefinitely until an update is successfully com-
		 pleted.  The retries are spaced using randomized exponential
		 backoff.  Use of the GUI implies -r 0.	 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 cvsup occasionally (perhaps	once a day) without
		 the -s	option.

		 Without the -s	option,	cvsup 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 CVSup 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 cvsup
		 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
     updated.  Comments	begin with `#' and extend to the end of	the line.
     Lines that	are empty except for comments and white	space are ignored.
     Each remaining 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 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:

     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 convention-
		 ally use release=current.

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

     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	directory must already exist; cvsup will not create
		 it.

		 As a special case, if prefix is a symbolic link pointing to a
		 nonexistent file named	`SKIP',	then cvsup will	skip the col-
		 lection.  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.  cvsup requires that	all collections	in a single
		 run come from the same	host.  If you wish to update collec-
		 tions from several different hosts, you must run cvsup	sev-
		 eral times.

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

		 The presence of the delete keyword puts cvsup into so-called
		 exact mode.  In exact mode, CVSup does	its best to make the
		 client's files	correspond to those on the server.  This
		 includes deleting individual deltas and symbolic tags from
		 RCS files, as well as deleting	entire files.  In exact	mode,
		 CVSup 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 CVSup falls back upon transferring the entire file.

		 In general, CVSup 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, CVSup is willing
		 to delete two classes of files:
		 +o   Files that	were previously	created	or updated by CVSup
		     itself.
		 +o   Checked-out versions of files which are marked as dead on
		     the server.

     use-rel-suffix
		 Causes	cvsup 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
		 updates.  On links with speeds	of 56K bits/second or less,
		 compression 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.

     norcs	 Disables special processing for RCS files.  They will be
		 treated the same as other files.

     norsync	 Disables the use of Tridgell &	Mackerras' rsync algorithm for
		 updating regular (non-RCS) files.  The	algorithm works	cor-
		 rectly	for any	kind of	file, but it may be ineffective	and
		 computationally expensive for files such as compressed	tar
		 archives.

     strictrcs	 Causes	updated	RCS files to be	checked	using strict byte-by-
		 byte MD5 checksums.  Normally,	CVSup uses a looser checksum
		 for RCS files,	which ignores harmless differences in white
		 space.	 Different versions of CVS and RCS produce a variety
		 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 numerous
		 unneeded ``fixups'', and thus to slow updates.

     nocheckrcs	 Disables the comparison of MD5	checksums for updated RCS
		 files.	 This option is	turned on automatically	if the delete
		 keyword is not	specified.

     execute	 Enables the execution of shell	commands received from the
		 server.  This should be used with caution, since it may con-
		 stitute a security risk.

     preserve	 Causes	cvsup to attempt to transfer all possible file
		 attributes from the server to the client.  The	attributes
		 supported depend on both the host platform and	the client
		 platform.  On FreeBSD systems,	the following attributes are
		 supported:
		 +o   Owner.
		 +o   Group.
		 +o   Permissions.
		 +o   Flags.
		 +o   Modification time.

		 Of these, the first four are controlled by the	preserve key-
		 word, while the fifth is preserved in all cases.

		 The preserve keyword is not intended to be used for updating
		 user files or CVS repositories.  It is	intended only for spe-
		 cialized applications in which	a host's entire	file tree is
		 to be replicated exactly.  Any	differences between the	server
		 host and the client host can cause problems if	preserve is
		 specified.  For example, if the client	receives a file	whose
		 owner does not	exist on the client machine, it	will be	unable
		 to preserve the owner.	 This may in turn cause	the permis-
		 sions to have unintended meanings.  In	addition, each subse-
		 quent update run will cause further unsuccessful attempts to
		 correct the file's owner on the client, wasting time and
		 bandwidth.  Finally, preserve mode increases the network
		 traffic and slows down	updates.

		 For preserve mode to function properly, the client must be
		 executed with root access permissions.	 If the	client is not
		 root, then attempts to	preserve the owner, group, and flags
		 are suppressed.

		 The preserve keyword is ignored in checkout mode.

     umask=n	 Causes	cvsup 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.

OPERATION
     cvsup includes a graphical	user interface (GUI) which allows one to moni-
     tor its progress and performance during an	update.	 The GUI is disabled
     if	the -g command line option is given, or	if the DISPLAY environment
     variable is not set.  The GUI includes a ``Filter'' type-in field,	where
     patterns may be entered to	restrict the files to be updated.  The pat-
     terns are as described for	the -i option.	If multiple patterns are
     entered, they should be separated by white	space.

     At	present, the GUI does not support changing the parameters specified in
     the supfile.  That	is planned for a future	release.  Despite its relative
     uselessness, the GUI is fun to watch.

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

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 ver-
     sions 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 CVSup will	provide	the corre-
     sponding 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 sup-
		 ported.

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

		 RELENG_3  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
		 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, CVSup	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
     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
     specification `tag=.'.  The user could later change the specification to
     `tag=RELENG_3'.  This would cause CVSup to	edit the checked-out files in
     such a way	as to transform	them from the `current'	versions to the
     `stable' versions.	 In general, CVSup is willing to transform any
     tag/date combination 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
     another, it is important to specify the list keyword in the supfile, to
     ensure that the same list file is used both before	and after the trans-
     formation.	 The list file is described in THE LIST	FILE, below.

THE LIST FILE
     For efficiency, cvsup 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
     inconsistent with the actual client files,	cvsup falls back upon a	less
     efficient method of identifying the client's files	and performing its
     updates.  Depending on CVSup's mode of operation, the fallback method
     employs time stamps, checksums, or	analysis of RCS	files.

     Because the list file is not essential, cvsup is able to ``adopt''	an
     existing file tree	acquired by FTP	or from	a CD-ROM.  cvsup identifies
     the client's versions of the files, updates them as necessary, and	cre-
     ates 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
     release and tag, is appended to the name.	The default suffix can be
     overridden	by specifying an explicit suffix in the	supfile:

     list=suffix
		 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.

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

	   doc/Makefile

     will not work because the file on the server is called `Makefile,v.' A
     better 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
     containing	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 collec-
     tion.  Finally, 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 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.

     cvsup 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',
     respectively.  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

AUTHENTICATION
     CVSup implements an optional authentication mechanism which can be	used
     by	the client and server to verify	each other's identities.  Public CVSup
     servers normally do not enable authentication.  CVSup users may ignore
     this section unless they have been	informed that authentication is
     required by the administrator of their server.

     The authentication	subsystem uses a challenge-response protocol which is
     immune to packet sniffing and replay attacks.  No passwords are sent over
     the network in either direction.  Both the	client and the server can
     independently verify the identities of each other.

     The file $HOME/.cvsup/auth	holds the information used for authentication.
     This file contains	a record for each server that the client is allowed to
     access.  Each record occupies one line in the file.  Lines	beginning with
     `#' are ignored, as are lines containing only white space.	 White space
     is	significant everywhere else in the file.  Fields are separated by `:'
     characters.

     Each record of the	file has the following form:

	   serverName:clientName:password:comment

     All fields	must be	present	even if	some of	them are empty.	 ServerName is
     the name of the server to which the record	applies.  By convention, it is
     the canonical fully-qualified domain name of the server, e.g.,
     `CVSup177.FreeBSD.ORG'.  This must	agree with the server's	own idea of
     its name.	The name is case-insensitive.

     ClientName	is the name the	client uses to gain access to the server.  By
     convention, e-mail	addresses are used for all client names, e.g.,
     `BillyJoe@FreeBSD.ORG'.  Client names are case-insensitive.

     Password is a secret string of characters that the	client uses to prove
     its identity.  It may not contain any `:' or newline characters.

     Comment may contain any additional	information to identify	the record.
     It	is not interpreted by the program.

     To	set up authentication for a given server, one must perform the follow-
     ing steps:

     1.	  Obtain the official serverName from the administrator	of the server
	  or from some other source.

     2.	  Choose an appropriate	clientName.  It	should be in the form of a
	  valid	e-mail address,	to make	it easy	for the	server administrator
	  to contact the user if necessary.

     3.	  Choose an arbitrary secret password.

     4.	  Run the cvpasswd utility, and	type in	the password when prompted for
	  it.  The utility will	print out a line to send to the	server admin-
	  istrator, and	instruct you how to modify your	$HOME/.cvsup/auth
	  file.	 You should use	a secure channel to send the line to the
	  server administrator.

     Since $HOME/.cvsup/auth contains passwords, you should ensure that	it is
     not readable by anyone except yourself.

     Authentication works independently	in both	directions.  The server	admin-
     istrator controls whether you must	prove your identity.  You control
     whether to	check the server's identity, by	means of the -a	command	line
     option.

USING CVSup FOR	MIRRORING
     Although CVSup is optimized for CVS repositories, it works	quite well as
     a general purpose mirroring tool.	It is able to update all types of
     files.
     +o	 RCS files are updated by transferring individual tags and deltas, and
	 merging them into the client file.
     +o	 Regular files are updated using the rsync algorithm, if it is
	 enabled.  If the rsync	algorithm is disabled, files which have	had
	 data appended to them on the server (e.g., log	files) receive only
	 the new tail portion.	Other regular files are	replaced in whole.
     +o	 Empty directories are preserved.
     +o	 Symbolic links	are updated as dictated	by symlink and rsymlink	com-
	 mands in the server's configuration files.  See cvsupd(8).
     +o	 Hard links are	preserved within each collection, but not between col-
	 lections.
     +o	 Device	nodes are updated by major and minor device number.  This may
	 not produce the desired results if the	client host and	the server
	 host run different operating systems.

CVSup AND FIREWALLS
     In	its default mode, cvsup	will work through any firewall which permits
     outbound connections to port 5999 of the server host.  With slightly more
     permissive	firewall rules it may be possible to use passive mode or one
     of	the other modes, for a very slight gain	in efficiency.	See the
     description of the	-P option for details.

     For more information on using CVSup with specific kinds of	firewalls, see
     the CVSup FAQ at <http://www.cvsup.org/>.

USING CVSup WITH SOCKS
     CVSup can be used through a SOCKS proxy server with the standard runsocks
     command.  Your cvsup executable needs to be dynamically-linked with the
     system libraries for runsocks to work properly.  Also, when using
     runsocks you must add the magic parameter @M3novm to the end of the cvsup
     command line.

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 cvsup 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 cvsup 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.
     base/collDir/refuse	       Global refuse file.
     base/collDir/collection/refuse*   Per-collection and per-release and tag
				       refuse files.
     $HOME/.cvsup/auth		       Authentication password file.

SEE ALSO
     cvpasswd(1), cvs(1), cvsupd(8), rcsintro(1), ssh(1).

     http://www.cvsup.org/

AUTHORS
     John Polstra <jdp@polstra.com>.

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

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.

     The GUI interacts poorly with some	window managers, notably older ver-
     sions of FVWM.  Adding the	line

	   Style "cvsup" ClickToFocus

     to	FVWM2's	.fvwmrc	file helps quite a bit.	 The problem appears to	be
     caused by window manager bugs, triggered by the GUI's use of the
     `WM_TAKE_FOCUS' protocol.	As a work-around, you can always use the -g
     option to disable the GUI entirely.

FreeBSD				January	1, 2002			       FreeBSD

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERATION | CVS MODE | CHECKOUT MODE | THE LIST FILE | REFUSE FILES | AUTHENTICATION | USING CVSup FOR MIRRORING | CVSup AND FIREWALLS | USING CVSup WITH SOCKS | USING ssh PORT FORWARDING | FILES | SEE ALSO | AUTHORS | LEGALITIES | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=cvsup&manpath=FreeBSD+Ports>

home | help