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

FreeBSD Man Pages

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

NAME
     cvsup - network distribution package for CVS repositories

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

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

     Unlike more traditional network distribution packages, such as rdist and
     sup, CVSup has specific optimizations for distributing CVS repositories.
     CVSup takes advantage of the properties of CVS repositories and the files
     they contain (in particular, RCS files), enabling it to perform updates
     much faster than traditional systems.

     CVSup is a general-purpose network file updating package.  It is
     extremely fast, even for collections of files which have nothing to do
     with CVS or RCS.

OPTIONS
     The client program cvsup requires at least a single argument, supfile.
     It names a file describing one or more collections of files to be
     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 sup supfiles.

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

     The following options are supported by cvsup:

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

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

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

     -b base     Specifies the base directory under which cvsup will maintain
                 its bookkeeping files, overriding any base specifications in
                 the supfile.

     -c collDir  Specifies the subdirectory of base where the information
                 about the collections is maintained.  The default is sup.

     -d delLimit
                 Specifies the maximum number of files that may be deleted in
                 a single update run.  Any attempt to exceed the limit results
                 in a fatal error.  This can provide some protection against
                 temporary configuration mistakes on the server.  The default
                 limit is infinity.

     -D          Causes cvsup to perform file deletions only, omitting all
                 other kinds of updates.  This is useful in some situations
                 where disk space on the client is very limited.  One can
                 first run cvsup with the -D option, to free up as much space
                 as possible.  Then a second run can be made, this time
                 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.

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

     -i pattern  Causes cvsup to include only files and directories matching
                 pattern in the update.  If a directory matches the pattern,
                 then the entire subtree rooted at the directory is included.
                 If this option is specified multiple times, the patterns are
                 combined using the `or' operation.  If no -i options are
                 given, the default is to update all files in each collection.

                 The pattern is a standard file name pattern.  It is
                 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 `Filter' type-in field where the patterns may
                 be edited.

     -k          Causes cvsup to keep the temporary copies of any incorrectly
                 edited files, in the event of checksum mismatches.  This
                 option is for debugging, to help determine why the files were
                 edited incorrectly.  Regardless of whether this option is
                 specified, the permanent versions of faulty files are
                 replaced with correct versions obtained by transferring the
                 files in their entirety.  Such transfers are called fixups.

     -l lockfile
                 Creates and locks the lockfile while the update is in
                 progress.  If lockfile is already locked, cvsup fails without
                 performing automatic retries.  This option is useful when
                 cvsup is executed periodically from cron.  It prevents a job
                 from interfering with an earlier job that is perhaps taking
                 extra long because of network problems.

                 POSIX-style file locking is used, as described in fcntl(2).
                 The process-ID is written to the lock file in text form when
                 the lock is successfully acquired.  Upon termination of the
                 update, the lock file is removed.

     -L verbosity
                 Sets the verbosity level for non-GUI output.  A level of 0
                 causes cvsup to be completely silent unless errors occur.  A
                 level of 1 (the default) causes each updated file to be
                 listed.  A level of 2 provides more detailed information
                 about the updates performed on each file.  All messages are
                 directed to the standard output.  This option is ignored when
                 the GUI is used.

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

     -P m|a|port|lo-hi|-
                 Controls the establishment of the auxiliary TCP connection(s)
                 used to carry information between the client and the server.
                 Altogether, the client and server require four unidirectional
                 channels to communicate: two from the client to the server,
                 and two from the server to the client.  These four
                 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 -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.

     -r maxRetries
                 Limits the number of automatic retries that will be attempted
                 when transient errors such as lost network connections are
                 encountered.  By default, when the GUI is not used, cvsup
                 will retry indefinitely until an update is successfully
                 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.

     -s          Suppresses the check of each client file's status against
                 what is recorded in the list file.  Instead, the list file is
                 assumed to be accurate.  This option greatly reduces the
                 amount of disk activity and results in faster updates with
                 less load on the client host.  However it should only be used
                 if client's files are never modified locally in any way.
                 Mirror sites may find this option beneficial to reduce the
                 disk load on their systems.  For safety, even mirror sites
                 should run cvsup occasionally (perhaps once a day) without
                 the -s option.

                 Without the -s option, cvsup performs a stat(2) call on each
                 file and verifies that its attributes match those recorded in
                 the list file.  This ensures that any file changes made
                 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:

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

     prefix=prefix
                 This is the directory under which updated files will be
                 placed.  By default, it is the same as base.  If it is not an
                 absolute pathname, it is interpreted relative to base.  The
                 prefix directory must already exist; cvsup will not create
                 it.

                 As a special case, if prefix is a symbolic link pointing to a
                 nonexistent file named `SKIP', then cvsup will skip the
                 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.  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.

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

                 The presence of the delete keyword puts cvsup into so-called
                 exact mode.  In exact mode, CVSup does its best to make the
                 client's files correspond to those on the server.  This
                 includes deleting individual deltas and symbolic tags from
                 RCS files, as well as deleting entire files.  In exact mode,
                 CVSup verifies every edited file with a checksum, to ensure
                 that the edits have produced a file identical to the master
                 copy on the server.  If the checksum test fails for a file,
                 then CVSup falls back upon transferring the entire file.

                 In general, CVSup deletes only files which are known to the
                 server.  Extra files present in the client's tree are left
                 alone, even in exact mode.  More precisely, CVSup is willing
                 to delete two classes of files:
                 +o   Files that were previously created or updated by CVSup
                     itself.
                 +o   Checked-out versions of files which are marked as dead on
                     the server.

     use-rel-suffix
                 Causes cvsup to append a suffix constructed from the release
                 and tag to the name of each list file that it maintains.  See
                 THE LIST FILE for details.

     compress    This enables compression of all data sent across the network.
                 Compression is quite effective, normally eliminating 65% to
                 75% of the bytes that would otherwise need to be transferred.
                 However, it is costly in terms of CPU time on both the client
                 and the server.  On local area networks, compression is
                 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.

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

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

     strictrcs   Causes updated RCS files to be checked using strict byte-by-
                 byte MD5 checksums.  Normally, CVSup uses a looser checksum
                 for RCS files, which ignores harmless differences in white
                 space.  Different versions of CVS and RCS produce a variety
                 of differences in white space for the same RCS files.  Thus
                 the strict checksum can report spurious mismatches for files
                 which are logically identical.  This can lead to numerous
                 unneeded ``fixups'', and thus to slow updates.

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

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

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

                 Of these, the first four are controlled by the preserve
                 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 host's entire file tree
                 is to be replicated exactly.  Any differences between the
                 server host and the client host can cause problems if
                 preserve is specified.  For example, if the client receives a
                 file whose owner does not exist on the client machine, it
                 will be unable to preserve the owner.  This may in turn cause
                 the 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, preserve mode increases the
                 network traffic and slows down updates.

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

                 The preserve keyword is ignored in checkout mode.

     umask=n     Causes cvsup to use a umask value of n (an octal number) when
                 updating the files in the collection.  This option is ignored
                 if preserve is specified.

     Some additional, more specialized keywords are described below.
     Unrecognized keywords are silently ignored for backward compatibility
     with sup.

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

CVS MODE
     CVSup supports two primary modes of operation.  They are called CVS mode
     and checkout mode.

     In CVS mode, the client receives copies of the actual RCS files making up
     the master CVS repository.  CVS mode is the default mode of operation.
     It is appropriate when the user wishes to maintain a full copy of the CVS
     repository on the client machine.

     CVS mode is also appropriate for file collections which are not based
     upon a CVS repository.  The files are simply transferred verbatim,
     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 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.

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

THE LIST FILE
     For efficiency, cvsup maintains a bookkeeping file for each collection,
     called the list file.  The list file contains information about which
     files and revisions the client currently possesses.  It also contains
     information used for verifying that the list file is consistent with the
     actual files in the client's tree.

     The list file is not strictly necessary.  If it is deleted, or becomes
     inconsistent with the actual client files, cvsup falls back upon a less
     efficient method of identifying the client's files and performing its
     updates.  Depending on CVSup's mode of operation, the fallback method
     employs time stamps, checksums, or analysis of RCS files.

     Because the list file is not essential, cvsup is able to ``adopt'' an
     existing file tree acquired by FTP or from a CD-ROM.  cvsup identifies
     the client's versions of the files, updates them as necessary, and
     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.

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 base/collDir/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.

     cvsup has a built-in default value of /usr/local/etc/cvsup for base and
     sup for collDir but it is possible to override both of these. The value
     of base can be changed using the -b option or a base=pathname entry in
     the supfile.  (If both are used the -b option will override the supfile
     entry.)  The value of collDir can only be changed with the -c option;
     there is no supfile command to change it.

     As an example, suppose that the base and collDir both have their default
     values, and that the collection and release are `src-all' and `cvs',
     respectively.  Assume further that checkout mode is being used with
     `tag=RELENG_3'.  The three possible refuse files would then be named:

           /usr/local/etc/cvsup/sup/refuse
           /usr/local/etc/cvsup/sup/src-all/refuse
           /usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3

     If the supfile includes the command base=/foo the refuse files would be:

           /foo/sup/refuse
           /foo/sup/src-all/refuse
           /foo/sup/src-all/refuse.cvs:RELENG_3

     If -b /bar is used (even with base=/foo in the supfile):

           /bar/sup/refuse
           /bar/sup/src-all/refuse
           /bar/sup/src-all/refuse.cvs:RELENG_3

     and with -c stool as well:

           /bar/stool/refuse
           /bar/stool/src-all/refuse
           /bar/stool/src-all/refuse.cvs:RELENG_3

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

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

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

     Each record of the file has the following form:

           serverName:clientName:password:comment

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

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

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

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

     To set up authentication for a given server, one must perform the
     following steps:

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

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

     3.   Choose an arbitrary secret password.

     4.   Run the cvpasswd utility, and type in the password when prompted for
          it.  The utility will print out a line to send to the server
          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 server's identity, by means of the -a command line
     option.

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

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

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

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

USING ssh PORT FORWARDING
     As an alternative to SOCKS, a user behind a firewall can penetrate it
     with the TCP port forwarding provided by the Secure Shell package ssh.
     The user must have a login account on the CVSup server host in order to
     do this.  The procedure is as follows:

     1.   Establish a connection to the server host with ssh, like this:

          ssh -f -x -L 5999:localhost:5999 serverhost sleep 60

          Replace serverhost with the hostname of the CVSup server, but type
          `localhost' literally.  This sets up the required port forwarding.
          You must start cvsup before the 60-second sleep finishes.  Once the
          update has begun, ssh will keep the forwarded channels open as long
          as they are needed.

     2.   Run cvsup on the local host, including the arguments `-h localhost'
          on the command line.

FILES
     /usr/local/etc/cvsup              Default base directory.
     sup                               Default collDir subdirectory.
     base/collDir/collection/checkouts*
                                       List files.
     base/collDir/refuse               Global refuse file.
     base/collDir/collection/refuse*   Per-collection and per-release and tag
                                       refuse files.
     $HOME/.cvsup/auth                 Authentication password file.

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

     http://www.cvsup.org/

AUTHORS
     John Polstra <jdp@polstra.com>.

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

BUGS
     An RCS file is not recognized as such unless its name ends with `,v'.

     Any directory named `Attic' is assumed to be a CVS Attic, and is treated
     specially.

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

           Style "cvsup" ClickToFocus

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

FreeBSD                         January 1, 2002                        FreeBSD

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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cvsup&sektion=1&manpath=FreeBSD+11.0-RELEASE+and+Ports>

home | help