|-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 identity) to the client. If authentication of the server fails, the update is canceled. See AUTHENTICATION, below.|
|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.|
|Specifies the base directory under which cvsup will maintain its bookkeeping files, overriding any base specifications in the supfile.|
|Specifies the subdirectory of base where the information about the collections is maintained. The default is sup.|
|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 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.|
|-e||Enables the execution of shell commands received from the server, as if the execute keyword were added to every collection 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.|
|Specifies the server host to contact, overriding any host specifications in the supfile.|
to include only files and directories matching
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
operation. If no
options are given, the default is to update all files in each
The pattern is a standard file name pattern. It is interpreted relative to the collections 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 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.|
Creates and locks the
while the update is in progress.
is already locked,
fails without performing automatic retries.
This option is useful when
is executed periodically from
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.
|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
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 -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 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 -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 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 -P -. 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, cvsup will retry indefinitely until an update is successfully completed. 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.|
Suppresses the check of each client files 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 clients 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
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 outside 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 damage 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 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 conventionally use release=current.|
|This specifies a directory under which cvsup will maintain its bookkeeping files, describing the state of each collection on the client machine. The base directory must already exist; cvsup will not create it. The default base directory is /usr/local/etc/cvsup.|
This is the directory under which updated files will be placed.
By default, it is the same as
If it is not an absolute pathname, it is interpreted relative to
directory must already exist;
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 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 cvsup several times.|
The presence of this keyword gives
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 clients 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 clients tree are left alone, even in exact mode. More precisely, CVSup is willing to delete two classes of files:
|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.|
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
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
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 supfile. 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.|
|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 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.|
|Disables the comparison of MD5 checksums for updated RCS files. This option is turned on automatically if the delete 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.|
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:
Of these, the first four are controlled by the preserve keyword, 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 specialized applications in which a hosts 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 permissions to have unintended meanings. In addition, each subsequent update run will cause further unsuccessful attempts to correct the files 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.
|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. Unrecognized keywords are silently ignored for backward compatibility with sup.
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 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 patterns 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.
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 interpretation.
In checkout mode, the client receives specific revisions of files, checked out directly from the servers 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, and 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 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_3 The stable branch. . The main branch (the current release). This is the default, if only the date keyword is given.
.Sm on 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 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 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 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 transformation. The list file is described in THE LIST FILE, below.
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 clients 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 clients 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 clients 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 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.
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 special 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 collections 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:
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
.Sm off base / collDir /refuse
.Sm on which applies to all collections and releases. There can be a per-collection refuse file named
.Xo Ar base / Ar collDir / Ar collection /refuse
.Sm on 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 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
CVSup implements an optional authentication mechanism which can be used by the client and server to verify each others 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:
.Xo Ar serverName No : Ar clientName No : 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 servers 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 following steps:
- 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 $ 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 administrator controls whether you must prove your identity. You control whether to check the servers identity, by means of the -a command line option.
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.
- 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 symlink and rsymlink commands in the servers configuration files. See cvsupd(8).
- Hard links are preserved within each collection, but not between collections.
- 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.
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/>.
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.
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.
- Run cvsup on the local host, including the arguments -h localhost on the command line.
/usr/local/etc/cvsup Default base directory. sup Default collDir subdirectory.
.Sm on List files.
base / collDir /refuse
.Sm on Global refuse file.
.Sm on Per-collection and per-release and tag refuse files.
$ HOME /.cvsup/auth Authentication password file.
.An John Polstra Aq firstname.lastname@example.org .
CVSup is a registered trademark of John D. Polstra.
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 versions of FVWM. Adding the line
Style cvsup ClickToFocus
to FVWM2s .fvwmrc file helps quite a bit. The problem appears to be caused by window manager bugs, triggered by the GUIs use of the WM_TAKE_FOCUS protocol. As a work-around, you can always use the -g option to disable the GUI entirely.