CVSUP(1) FreeBSD General Commands Manual CVSUP(1)
NNAAMMEE
ccvvssuupp - network distribution package for CVS repositories
SSYYNNOOPPSSIISS
ccvvssuupp [--11aaDDeeEEggkkssvvzzZZ] [--AA _a_d_d_r] [--bb _b_a_s_e] [--cc _c_o_l_l_D_i_r] [--dd _d_e_l_L_i_m_i_t]
[--hh _h_o_s_t] [--ii _p_a_t_t_e_r_n] [--ll _l_o_c_k_f_i_l_e] [--LL _v_e_r_b_o_s_i_t_y] [--pp _p_o_r_t]
[--PP _m_|_a_|_p_o_r_t_|_l_o_-_h_i_|_-] [--rr _m_a_x_R_e_t_r_i_e_s] _s_u_p_f_i_l_e [_d_e_s_t_D_i_r]
DDEESSCCRRIIPPTTIIOONN
CCVVSSuupp is a software package for distributing and updating collections of
files across a network. The name CCVVSSuupp refers to the package as a whole.
It consists of a client program, ccvvssuupp, and a server program, ccvvssuuppdd.
This manual page describes the general aspects of the CCVVSSuupp package, as
well as the particulars of the ccvvssuupp client program. For detailed infor-
mation about ccvvssuuppdd, see cvsupd(8).
Unlike more traditional network distribution packages, such as rrddiisstt and
ssuupp, CCVVSSuupp has specific optimizations for distributing CVS repositories.
CCVVSSuupp 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.
CCVVSSuupp 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.
OOPPTTIIOONNSS
The client program ccvvssuupp requires at least a single argument, _s_u_p_f_i_l_e.
It names a file describing one or more collections of files to be trans-
ferred and/or updated from the server. The _s_u_p_f_i_l_e has a format similar
to the corresponding file used by ssuupp. In most cases, ccvvssuupp can use
existing ssuupp _s_u_p_f_i_l_e_s.
An optional argument _d_e_s_t_D_i_r may also be specified. If given, it names a
directory under which all updated files will be placed. When _d_e_s_t_D_i_r is
specified, the client's original files are left untouched. This feature
is primarily intended for testing.
The following options are supported by ccvvssuupp:
--11 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 ccvvssuupp to
retry repeatedly, using randomized exponential backoff to
space the retries. This option is equivalent to --rr 00,, and is
implied when the GUI is used.
--aa Requires the server to authenticate itself (prove its iden-
tity) to the client. If authentication of the server fails,
the update is canceled. See _A_U_T_H_E_N_T_I_C_A_T_I_O_N, below.
--AA _a_d_d_r 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.
--bb _b_a_s_e Specifies the base directory under which ccvvssuupp will maintain
its bookkeeping files, overriding any bbaassee specifications in
the _s_u_p_f_i_l_e.
--cc _c_o_l_l_D_i_r Specifies the subdirectory of _b_a_s_e where the information
about the collections is maintained. The default is _s_u_p.
--dd _d_e_l_L_i_m_i_t
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.
--DD Causes ccvvssuupp 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 ccvvssuupp with the --DD option, to free up as much space
as possible. Then a second run can be made, this time with-
out the --DD 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.
--ee Enables the execution of shell commands received from the
server, as if the eexxeeccuuttee keyword were added to every collec-
tion in the _s_u_p_f_i_l_e.
--EE Disables the execution of shell commands received from the
server, as if the eexxeeccuuttee keyword were removed from every
collection in the _s_u_p_f_i_l_e.
--gg Disables the use of the graphical user interface. This
option is implied if the DISPLAY environment variable is not
set.
--hh _h_o_s_t Specifies the server host to contact, overriding any hhoosstt
specifications in the _s_u_p_f_i_l_e.
--ii _p_a_t_t_e_r_n Causes ccvvssuupp to include only files and directories matching
_p_a_t_t_e_r_n 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 --ii options are
given, the default is to update all files in each collection.
The _p_a_t_t_e_r_n 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.
--kk Causes ccvvssuupp 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.
--ll _l_o_c_k_f_i_l_e
Creates and locks the _l_o_c_k_f_i_l_e while the update is in
progress. If _l_o_c_k_f_i_l_e is already locked, ccvvssuupp fails without
performing automatic retries. This option is useful when
ccvvssuupp is executed periodically from ccrroonn. 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.
--LL _v_e_r_b_o_s_i_t_y
Sets the verbosity level for non-GUI output. A level of 0
causes ccvvssuupp 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.
--pp _p_o_r_t Sets the TCP port to which ccvvssuupp 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 --PP option), the server also uses the next
lower port to establish a second connection back to the
client.
--PP _m_|_a_|_p_o_r_t_|_l_o_-_h_i_|_-
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
sssshh'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 --PP mm.
Multiplexed mode can be used in conjunction with a SOCKS
proxy server. Simply run ccvvssuupp under the rruunnssoocckkss command,
and add @@MM33nnoovvmm to the end of the ccvvssuupp 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 --PP _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 --PP _p_o_r_t,
or a range of ports with --PP _l_o_-_h_i. 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 --PP --. Passive mode cannot be
used through a SOCKS proxy server.
--rr _m_a_x_R_e_t_r_i_e_s
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, ccvvssuupp
will retry indefinitely until an update is successfully com-
pleted. The retries are spaced using randomized exponential
backoff. Use of the GUI implies --rr 00. Note that --rr 00 is
equivalent to the --11 option.
--ss 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 ccvvssuupp occasionally (perhaps once a day) without
the --ss option.
Without the --ss option, ccvvssuupp 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 CCVVSSuupp are detected and corrected.
If the --ss 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 ccvvssuupp
may abort prematurely.
--vv Prints the version number and exits, without contacting the
server.
--zz Enables compression for all collections, as if the ccoommpprreessss
keyword were added to every collection in the _s_u_p_f_i_l_e.
--ZZ Disables compression for all collections, as if the ccoommpprreessss
keyword were removed from every collection in the _s_u_p_f_i_l_e.
The _s_u_p_f_i_l_e 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
**ddeeffaauulltt. Such defaults will apply to subsequent lines in the _s_u_p_f_i_l_e.
Multiple **ddeeffaauulltt lines may be present. New values augment or override
any defaults specified earlier in the _s_u_p_f_i_l_e. Values specified explic-
itly for a collection override any default values.
The most commonly used keywords are:
rreelleeaassee==_r_e_l_e_a_s_e_N_a_m_e
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
rreelleeaassee==ccvvss by convention. Non-CVS collections convention-
ally use rreelleeaassee==ccuurrrreenntt.
bbaassee==_b_a_s_e This specifies a directory under which ccvvssuupp will maintain
its bookkeeping files, describing the state of each collec-
tion on the client machine. The _b_a_s_e directory must already
exist; ccvvssuupp will not create it. The default _b_a_s_e directory
is _/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_c_v_s_u_p.
pprreeffiixx==_p_r_e_f_i_x
This is the directory under which updated files will be
placed. By default, it is the same as _b_a_s_e. If it is not an
absolute pathname, it is interpreted relative to _b_a_s_e. The
_p_r_e_f_i_x directory must already exist; ccvvssuupp will not create
it.
As a special case, if _p_r_e_f_i_x is a symbolic link pointing to a
nonexistent file named `SKIP', then ccvvssuupp 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
_s_u_p_f_i_l_e on several machines, yet control which collections
get updated on a per-machine basis.
hhoosstt==_h_o_s_t_n_a_m_e
This specifies the server machine from which all files will
be taken. ccvvssuupp 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 ccvvssuupp sev-
eral times.
ddeelleettee The presence of this keyword gives ccvvssuupp permission to delete
files. If it is missing, no files will be deleted.
The presence of the ddeelleettee keyword puts ccvvssuupp into so-called
_e_x_a_c_t mode. In exact mode, CCVVSSuupp 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,
CCVVSSuupp 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 CCVVSSuupp falls back upon transferring the entire file.
In general, CCVVSSuupp 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, CCVVSSuupp is willing
to delete two classes of files:
·· Files that were previously created or updated by CCVVSSuupp
itself.
·· Checked-out versions of files which are marked as dead on
the server.
uussee--rreell--ssuuffffiixx
Causes ccvvssuupp to append a suffix constructed from the release
and tag to the name of each list file that it maintains. See
_T_H_E _L_I_S_T _F_I_L_E for details.
ccoommpprreessss 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 --zz command line option enables the ccoommpprreessss keyword for
all collections, regardless of what is specified in the sup-
file. Likewise, the --ZZ command line option disables the
ccoommpprreessss option for all collections.
nnoorrccss Disables special processing for RCS files. They will be
treated the same as other files.
nnoorrssyynncc Disables the use of Tridgell & Mackerras' _r_s_y_n_c 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.
ssttrriiccttrrccss Causes updated RCS files to be checked using strict byte-by-
byte MD5 checksums. Normally, CCVVSSuupp 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.
nnoocchheecckkrrccss Disables the comparison of MD5 checksums for updated RCS
files. This option is turned on automatically if the ddeelleettee
keyword is not specified.
eexxeeccuuttee Enables the execution of shell commands received from the
server. This should be used with caution, since it may con-
stitute a security risk.
pprreesseerrvvee Causes ccvvssuupp 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:
·· Owner.
·· Group.
·· Permissions.
·· Flags.
·· Modification time.
Of these, the first four are controlled by the pprreesseerrvvee key-
word, while the fifth is preserved in all cases.
The pprreesseerrvvee 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 pprreesseerrvvee 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, pprreesseerrvvee mode increases the network
traffic and slows down updates.
For pprreesseerrvvee 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 pprreesseerrvvee keyword is ignored in checkout mode.
uummaasskk==_n Causes ccvvssuupp to use a umask value of _n (an octal number) when
updating the files in the collection. This option is ignored
if pprreesseerrvvee is specified.
Some additional, more specialized keywords are described below. Unrecog-
nized keywords are silently ignored for backward compatibility with ssuupp.
OOPPEERRAATTIIOONN
ccvvssuupp 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 --gg 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 --ii 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 _s_u_p_f_i_l_e. That is planned for a future release. Despite its relative
uselessness, the GUI is fun to watch.
CCVVSS MMOODDEE
CCVVSSuupp supports two primary modes of operation. They are called _C_V_S mode
and _c_h_e_c_k_o_u_t 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.
CCHHEECCKKOOUUTT MMOODDEE
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 CCVVSSuupp 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 _s_u_p_f_i_l_e:
ttaagg==_t_a_g_n_a_m_e
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 ddaattee keyword is given.
ddaattee==[_c_c]_y_y_._m_m_._d_d_._h_h_._m_m_._s_s
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 _c_c. For earlier
years, specify only the last two digits _y_y. 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, CCVVSSuupp 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 CCVVSSuupp to edit the checked-out files in
such a way as to transform them from the `current' versions to the
`stable' versions. In general, CCVVSSuupp 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 lliisstt keyword in the _s_u_p_f_i_l_e, to
ensure that the same list file is used both before and after the trans-
formation. The list file is described in _T_H_E _L_I_S_T _F_I_L_E, below.
TTHHEE LLIISSTT FFIILLEE
For efficiency, ccvvssuupp 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, ccvvssuupp falls back upon a less
efficient method of identifying the client's files and performing its
updates. Depending on CCVVSSuupp's mode of operation, the fallback method
employs time stamps, checksums, or analysis of RCS files.
Because the list file is not essential, ccvvssuupp is able to ``adopt'' an
existing file tree acquired by FTP or from a CD-ROM. ccvvssuupp 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 _F_I_L_E_S for
details. Its name always begins with `checkouts'. If the keyword
uussee--rreell--ssuuffffiixx is specified in the _s_u_p_f_i_l_e, 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 _s_u_p_f_i_l_e:
lliisstt==_s_u_f_f_i_x
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
_c_h_e_c_k_o_u_t_s_._s_t_a_b_l_e, regardless of the release, tag, or
uussee--rreell--ssuuffffiixx keyword.
RREEFFUUSSEE FFIILLEESS
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 _r_e_f_u_s_e 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 _b_a_s_e called `doc'. If `Makefile' from
that directory is not required then the line
_d_o_c_/_M_a_k_e_f_i_l_e
will not work because the file on the server is called `Makefile,v.' A
better solution would be
_d_o_c_/_M_a_k_e_f_i_l_e_*
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:
_d_o_c_/_j_a_*
_d_o_c_/_r_u_*
_d_o_c_/_z_h_*
As many as three refuse files are examined for each _s_u_p_f_i_l_e line. There
can be a global refuse file named _b_a_s_e_/_c_o_l_l_D_i_r_/_r_e_f_u_s_e which applies to
all collections and releases. There can be a per-collection refuse file
named _b_a_s_e_/_c_o_l_l_D_i_r_/_c_o_l_l_e_c_t_i_o_n_/_r_e_f_u_s_e 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.
ccvvssuupp has a built-in default value of _/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_c_v_s_u_p for _b_a_s_e and
_s_u_p for _c_o_l_l_D_i_r but it is possible to override both of these. The value
of _b_a_s_e can be changed using the --bb option or a _b_a_s_e_=_p_a_t_h_n_a_m_e entry in
the _s_u_p_f_i_l_e. (If both are used the --bb option will override the _s_u_p_f_i_l_e
entry.) The value of _c_o_l_l_D_i_r can only be changed with the --cc option;
there is no _s_u_p_f_i_l_e command to change it.
As an example, suppose that the _b_a_s_e and _c_o_l_l_D_i_r 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:
_/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_c_v_s_u_p_/_s_u_p_/_r_e_f_u_s_e
_/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_c_v_s_u_p_/_s_u_p_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e
_/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_c_v_s_u_p_/_s_u_p_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e_._c_v_s_:_R_E_L_E_N_G___3
If the _s_u_p_f_i_l_e includes the command _b_a_s_e_=_/_f_o_o the refuse files would be:
_/_f_o_o_/_s_u_p_/_r_e_f_u_s_e
_/_f_o_o_/_s_u_p_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e
_/_f_o_o_/_s_u_p_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e_._c_v_s_:_R_E_L_E_N_G___3
If --bb _/_b_a_r is used (even with _b_a_s_e_=_/_f_o_o in the _s_u_p_f_i_l_e):
_/_b_a_r_/_s_u_p_/_r_e_f_u_s_e
_/_b_a_r_/_s_u_p_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e
_/_b_a_r_/_s_u_p_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e_._c_v_s_:_R_E_L_E_N_G___3
and with --cc _s_t_o_o_l as well:
_/_b_a_r_/_s_t_o_o_l_/_r_e_f_u_s_e
_/_b_a_r_/_s_t_o_o_l_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e
_/_b_a_r_/_s_t_o_o_l_/_s_r_c_-_a_l_l_/_r_e_f_u_s_e_._c_v_s_:_R_E_L_E_N_G___3
AAUUTTHHEENNTTIICCAATTIIOONN
CCVVSSuupp 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_/_._c_v_s_u_p_/_a_u_t_h 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:
_s_e_r_v_e_r_N_a_m_e:_c_l_i_e_n_t_N_a_m_e:_p_a_s_s_w_o_r_d:_c_o_m_m_e_n_t
All fields must be present even if some of them are empty. _S_e_r_v_e_r_N_a_m_e 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.
_C_l_i_e_n_t_N_a_m_e 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.
_P_a_s_s_w_o_r_d is a secret string of characters that the client uses to prove
its identity. It may not contain any `:' or newline characters.
_C_o_m_m_e_n_t 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 _s_e_r_v_e_r_N_a_m_e from the administrator of the server
or from some other source.
2. Choose an appropriate _c_l_i_e_n_t_N_a_m_e. 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 _p_a_s_s_w_o_r_d.
4. Run the ccvvppaasssswwdd utility, and type in the _p_a_s_s_w_o_r_d 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_/_._c_v_s_u_p_/_a_u_t_h
file. You should use a secure channel to send the line to the
server administrator.
Since $HOME_/_._c_v_s_u_p_/_a_u_t_h 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 --aa command line
option.
UUSSIINNGG CCVVSSuupp FFOORR MMIIRRRROORRIINNGG
Although CCVVSSuupp 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 ssyymmlliinnkk and rrssyymmlliinnkk com-
mands in the server's configuration files. See cvsupd(8).
·· Hard links are preserved within each collection, but not between col-
lections.
·· 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.
CCVVSSuupp AANNDD FFIIRREEWWAALLLLSS
In its default mode, ccvvssuupp 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 --PP option for details.
For more information on using CVSup with specific kinds of firewalls, see
the CVSup FAQ at .
UUSSIINNGG CCVVSSuupp WWIITTHH SSOOCCKKSS
CVSup can be used through a SOCKS proxy server with the standard rruunnssoocckkss
command. Your ccvvssuupp executable needs to be dynamically-linked with the
system libraries for rruunnssoocckkss to work properly. Also, when using
rruunnssoocckkss you must add the magic parameter @@MM33nnoovvmm to the end of the ccvvssuupp
command line.
UUSSIINNGG sssshh PPOORRTT FFOORRWWAARRDDIINNGG
As an alternative to SOCKS, a user behind a firewall can penetrate it
with the TCP port forwarding provided by the Secure Shell package sssshh.
The user must have a login account on the CCVVSSuupp server host in order to
do this. The procedure is as follows:
1. Establish a connection to the server host with sssshh, like this:
ssh -f -x -L 5999:localhost:5999 serverhost sleep 60
Replace _s_e_r_v_e_r_h_o_s_t with the hostname of the CVSup server, but type
`localhost' literally. This sets up the required port forwarding.
You must start ccvvssuupp before the 60-second sslleeeepp finishes. Once the
update has begun, sssshh will keep the forwarded channels open as long
as they are needed.
2. Run ccvvssuupp on the local host, including the arguments `-h localhost'
on the command line.
FFIILLEESS
/usr/local/etc/cvsup Default _b_a_s_e directory.
sup Default _c_o_l_l_D_i_r subdirectory.
_b_a_s_e_/_c_o_l_l_D_i_r_/_c_o_l_l_e_c_t_i_o_n/checkouts*
List files.
_b_a_s_e_/_c_o_l_l_D_i_r/refuse Global refuse file.
_b_a_s_e_/_c_o_l_l_D_i_r_/_c_o_l_l_e_c_t_i_o_n/refuse* Per-collection and per-release and tag
refuse files.
$HOME/.cvsup/auth Authentication password file.
SSEEEE AALLSSOO
cvpasswd(1), cvs(1), cvsupd(8), rcsintro(1), ssh(1).
http://www.cvsup.org/
AAUUTTHHOORRSS
John Polstra .
LLEEGGAALLIITTIIEESS
CVSup is a registered trademark of John D. Polstra.
BBUUGGSS
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 _._f_v_w_m_r_c 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 --gg
option to disable the GUI entirely.
FreeBSD January 1, 2002 FreeBSD