||FreeBSD General Commands Manual
network distribution package for CVS repositories
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
CVSup package, as well as the particulars of
cvsup client program. For detailed information
Unlike more traditional network distribution packages, such as
CVSup has specific optimizations for distributing
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
The client program
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.
cvsup 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,
cvsup can use existing
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
The following options are supported by
- 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
0, and is implied when the GUI is used.
- Requires the server to authenticate itself (prove its identity) to the
client. If authentication of the server fails, the update is canceled. See
- 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
- Specifies the base directory under which
will maintain its bookkeeping files, overriding any
base specifications in the
- Specifies the subdirectory of base where the
information about the collections is maintained. The default is
- 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.
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
to free up as much space as possible. Then a second run can be made, this
time without 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.
- Enables the execution of shell commands received from the server, as if
execute keyword were added to every collection
in the supfile.
- Disables the execution of shell commands received from the server, as if
execute keyword were removed from every
collection in the supfile.
- Disables the use of the graphical user interface. This option is implied
DISPLAY environment variable is not
- Specifies the server host to contact, overriding any
host specifications in the
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 ‘
-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 characters are matched only by explicit slashes in the
pattern. Leading periods in file name are not treated specially.
The GUI has a ‘
type-in field where the patterns may be edited.
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.
- 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
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
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
- 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.
- 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.
- 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 unidirectional 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 overhead, 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
multiplexed mode, use the option
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 connection on a port chosen by the operating system. Many
operating systems use ports in the range 1024-5000 for this purpose. The
user can specify a particular port with
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
connections to implement the four unidirectional channels. However, 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
-. Passive mode
cannot be used through a SOCKS proxy server.
- 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,
retry indefinitely until an update is successfully completed. The retries
are spaced using randomized exponential backoff. Use of the GUI implies
0. Note that
0 is equivalent to the
- 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
occasionally (perhaps once a day) without the
cvsup performs a
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
CVSup are detected and corrected.
-s option is used when one or
more files have been modified locally, the results are undefined. Local
file damage may remain uncorrected, updates may be missed, or
cvsup may abort prematurely.
- Prints the version number and exits, without contacting the server.
- Enables compression for all collections, as if the
compress keyword were added to every collection in
- 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
Default settings may be specified in lines whose collection name
*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:
- 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
- This specifies a directory under which
maintain its bookkeeping files, describing the state of each collection on
the client machine. The base directory must already
cvsup 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;
cvsup will not create it.
As a special case, if prefix is a
symbolic link pointing to a nonexistent file named
cvsup will skip the collection. 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.
- 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 collections from
several different hosts, you must run
- The presence of this keyword gives
permission to delete files. If it is missing, no files will be deleted.
The presence of the
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.
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 that were previously created or updated by
- Checked-out versions of files which are marked as dead on the
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.
- 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 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 between these two
extremes, let experimentation be your guide.
-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 option for all collections.
- Disables special processing for RCS files. They will be treated the same
as other files.
- Disables the use of Tridgell & Mackerras' rsync
algorithm for updating regular (non-RCS) files. The algorithm works
correctly for any kind of file, but it may be ineffective and
computationally expensive for files such as compressed tar archives.
- Causes updated RCS files to be checked using strict byte-by-byte MD5
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
- Disables the comparison of MD5 checksums for updated RCS files. This
option is turned on automatically if the
keyword is not specified.
- Enables the execution of shell commands received from the server. This
should be used with caution, since it may constitute a security risk.
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:
- Modification time.
Of these, the first four are controlled by the
preserve keyword, while the fifth is preserved
in all cases.
preserve keyword is not intended
to be used for updating user files or CVS repositories. It is intended
only for specialized 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
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 permissions to have unintended
meanings. In addition, each subsequent update run will cause further
unsuccessful attempts to correct the file's owner on the client, wasting
time and bandwidth. Finally,
increases the network traffic and slows down updates.
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.
preserve keyword is ignored in
cvsup to use a umask value of
n (an octal number) when updating the files in the
collection. This option is ignored if
Some additional, more specialized keywords are described below.
Unrecognized keywords are silently ignored for backward compatibility with
cvsup includes a graphical user interface (GUI) which
allows one to monitor its progress and performance during an update. The GUI
is disabled if the
-g command line option is given, or
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 patterns are as described for
-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.
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,
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 functionality,
however. The client can specify any CVS symbolic tag, or any date, or both,
CVSup 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
- 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
- The ‘
- The main branch (the ‘
release). This is the default, if only the
date keyword is given.
- This specifies a date that should be used to select the revisions 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
To enable checkout mode, you must specify at least one of these
keywords. If both are missing,
CVSup defaults to CVS
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
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 ‘
versions to the ‘
stable’ versions. In
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
keyword in the supfile, to ensure that the same list
file is used both before and after the transformation. The list file is
described in THE LIST FILE,
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
Because the list file is not essential,
cvsup is able to “adopt” an existing
file tree acquired by FTP or from a CD-ROM.
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 list file is stored in a collection-specific directory; see
FILES for details. Its name always begins
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:
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.
- 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
There is currently no provision for comments in refuse files.
The patterns are similar to those of
except that there is no special treatment for slashes or for filenames that
begin with a period. For example, the pattern
*.c’ will match any file name ending
.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
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
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
which applies to all collections and releases. There can be a per-collection
refuse file named
which applies to a specific collection. 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 ‘
cvs’, respectively. 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:
-b /bar is used
(even with base=/foo in the
-c stool as
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.
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 ‘
Each record of the file has the following form:
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
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
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
To set up authentication for a given server, one must perform the
- Obtain the official serverName from the
administrator of the server or from some other source.
- 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.
- Choose an arbitrary secret password.
- 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 administrator, and instruct you how
to modify your
file. You should use a secure channel to send the line to the server
contains passwords, you should ensure that it is not readable by anyone
Authentication works independently in both directions. The server
administrator controls whether you must prove your identity. You control
whether to check the server's identity, by means of the
-a command line option.
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.
In its default mode,
- RCS files are updated by transferring individual tags and deltas, and
merging them into the client file.
- 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.
- Empty directories are preserved.
- Symbolic links are updated as dictated by
rsymlink commands in the server's
configuration files. See
- Hard links are preserved within each collection, but not between
- 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 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/⟩.
CVSup can be used through a SOCKS proxy server with the standard
runsocks command. Your
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.
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:
- 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.
cvsup on the local host, including the
-h localhost’ on the
John Polstra ⟨email@example.com⟩.
CVSup is a registered trademark of John D. Polstra.
An RCS file is not recognized as such unless its name ends with
- Default base directory.
- Default collDir subdirectory.
- List files.
- Global refuse file.
- Per-collection and per-release and tag refuse files.
- Authentication password file.
Any directory named ‘
is assumed to be a CVS Attic, and is treated specially.
The GUI interacts poorly with some window managers, notably older
versions of FVWM. Adding the line
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 ‘
protocol. As a work-around, you can always use the
-g option to disable the GUI entirely.
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.