is a software package for updating collections of files across a network.
It is a rewrite of the
CVSup
software in C.
This manual page describes the usage of the
client program.
Unlike more traditional network distribution packages, such as
rdist
and
sup
has specific optimizations for distributing CVS repositories.
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.
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
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,
can use existing
sup supfiles
The following options are supported by
:
-1
Disables automatic retries when transient failures occur.
Without this option, a transient failure such as a dropped network
connection causes
to retry repeatedly, using randomized exponential backoff to space the
retries.
This option is equivalent to
-r 0
-4
Forces
to use IPv4 addresses only.
-6
Forces
to use IPv6 addresses only.
-A addr
Specifies a local address to bind to when connecting to the server.
The local address might be a hostname or a numeric host address string
consisting of a dotted decimal IPv4 address or an IPv6 address.
This may be useful on hosts which have multiple IP addresses.
-b base
Specifies the base directory under which
will maintain its bookkeeping files, overriding any
base
specifications in the
supfile
-c collDir
Specifies the subdirectory of
base
where the information about the collections is maintained.
The default is
sup
-d delLimit
Specifies the maximum number of files that may be deleted in a
single update run.
Any attempt to exceed the limit results in a fatal error.
This can provide some protection against temporary configuration
mistakes on the server.
The default limit is infinity.
-h host
Specifies the server host to contact, overriding any
host
specifications in the
supfile
-i pattern
Causes
to include only files and directories matching
pattern
in the update. If a directory matches the pattern, then the entire
subtree rooted at the directory is included. If this option is
specified multiple times, the patterns are combined using the
`or'
operation. If no
-i
options are given, the default is to update all files in each
collection.
The
pattern
is a standard file name pattern.
It is interpreted relative to the collection's prefix directory.
Slash characters are matched only by explicit slashes in the pattern.
Leading periods in file name are not treated specially.
-k
Causes
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,
fails without performing automatic retries.
This option is useful when
is executed periodically from
cron
It prevents a job from interfering with an earlier job that is perhaps
taking extra long because of network problems.
The process-ID is written to the lock file in text form when the lock
is successfully acquired.
Upon termination of the update, the lock file is removed.
-L verbosity
Sets the verbosity level for output.
A level of 0 causes
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.
-p port
Sets the TCP port to which
attempts to connect on the server host.
The default port is 5999.
-r maxRetries
Limits the number of automatic retries that will be attempted when
transient errors such as lost network connections are encountered.
By default,
will retry indefinitely until an update is successfully completed.
The retries are spaced using randomized exponential backoff.
Note that
-r 0
is equivalent to the
-1
option.
-s
Suppresses the check of each client file's status against what is
recorded in the list file. Instead, the list file is assumed to be
accurate. This option greatly reduces the amount of disk activity and
results in faster updates with less load on the client host. However
it should only be used if client's files are never modified locally in
any way. Mirror sites may find this option beneficial to reduce the
disk load on their systems. For safety, even mirror sites should run
occasionally (perhaps once a day) without the
-s
option.
Without the
-s
option,
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
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
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:
release= releaseName
This specifies the release of the files within a collection.
Like collection names, release names are defined by the server
configuration files. Usually there is only one release in each
collection, but there may be any number. Collections which come from
a CVS repository often use
release=cvs
by convention. Non-CVS collections conventionally use
release=current
base= base
This specifies a directory under which
will maintain its bookkeeping files, describing the state of each
collection on the client machine.
The
base
directory must already exist;
will not create it.
The default
base
directory is
/usr/local/etc/csup
prefix= prefix
This is the directory under which updated files will be placed.
By default, it is the same as
base
If it is not an absolute pathname, it is interpreted relative to
base
The
prefix
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
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.
host= hostname
This specifies the server machine from which all files will be taken.
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
several times.
delete
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
into so-called
exact
mode. In exact mode,
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,
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
falls back upon transferring the entire file.
In general,
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,
is willing to delete two classes of files:
Files that were previously created or updated by
itself.
Checked-out versions of files which are marked as dead on the server.
use-rel-suffix
Causes
to append a suffix constructed from the release and tag to the name of
each list file that it maintains.
See
Sx 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 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.
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.
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.
umask= n
Causes
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
CVS MODE
CVSup
supports two primary modes of operation.
They are called
CVS
mode and
checkout
mode.
only supports the checkout mode for now.
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.
CHECKOUT MODE
In checkout mode, the client receives specific revisions of files,
checked out directly from the server's CVS repository.
Checkout mode allows the client to receive any version from the
repository, without requiring any extra disk space on the server for
storing multiple versions in checked-out form.
Checkout mode provides much flexibility beyond that basic functionality,
however.
The client can specify any CVS symbolic tag, or any date, or both, and
will provide the corresponding checked-out versions of the files in the
repository.
Checkout mode is selected on a per-collection basis, by the presence of
one or both of the following keywords in the
supfile
tag= tagname
This specifies a symbolic tag that should be used to select the
revisions that are checked out from the CVS repository.
The tag may refer to either a branch or a specific revision.
It must be symbolic; numeric revision numbers are not supported.
For the FreeBSD source repository, the most commonly used tags will be:
RELENG_6
The
`stable'
branch.
.
The main branch (the
`current'
release).
This is the default, if only the
date
keyword is given.
date=
[cc
]
yy.mm.dd.hh.mm.ss
This specifies a date that should be used to select the 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,
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
to edit the checked-out files in such a way as to transform them from the
`current'
versions to the
`stable'
versions.
In general,
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
Sx THE LIST FILE ,
below.
THE LIST FILE
For efficiency,
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,
falls back upon a less efficient method of identifying the client's
files and performing its updates.
Depending on
csup 's
mode of operation, the fallback method employs time stamps, checksums, or
analysis of RCS files.
Because the list file is not essential,
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 server.
The list file is stored in a collection-specific directory; see
Sx 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 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 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
Ar base / Ar collDir / Ar collection
/refuse
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.
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:
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
-cstool
as well:
/bar/stool/refuse
/bar/stool/src-all/refuse
/bar/stool/src-all/refuse.cvs:RELENG_3
csup AND FIREWALLS
In its default mode,
will work through any firewall which permits outbound connections to
port 5999 of the server host.
USING csup WITH SOCKS
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.
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:
Establish a connection to the server host with
ssh
like this:
Replace
serverhost
with the hostname of the CVSup server, but type
`localhost'
literally.
This sets up the required port forwarding.
You must start
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
on the local host, including the arguments
`-h'
localhost
on the command line.
An -nosplit
An Maxime Henrion Aq mux@FreeBSD.org
is the author of
,
the rewrite of
CVSup
in C.
An John Polstra Aq jdp@polstra.com
is the author of
CVSup
LEGALITIES
CVSup is a registered trademark of John D. Polstra.
is released under a 2-clauses BSD license.
BUGS
An RCS file is not recognized as such unless its name ends with
`,v'
Any directory named
`Attic'
is assumed to be a CVS Attic, and is treated specially.
