[-i pattern] [-l lockfile] [-L verbosity] [-p port] [-r maxRetries]
          supfile

DESCRIPTION

     csup 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 csup client program.

     Unlike more traditional network distribution packages, such as rdist and
     sup, csup has specific optimizations for distributing CVS repositories.
     csup 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.

     csup 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 csup requires at least a single argument, supfile.  It
     names a file describing one or more collections of files to be trans-
     ferred and/or updated from the server.  The supfile has a format similar
     to the corresponding file used by sup.  In most cases, csup can use
     existing sup supfiles.

     The following options are supported by csup:

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

     -4          Forces csup to use IPv4 addresses only.

     -6          Forces csup 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 csup 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

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

     -k          Causes csup 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, csup fails without
                 performing automatic retries.  This option is useful when
                 csup 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
                 csup 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 csup 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, csup 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.

     -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 explic-
     itly 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 convention-
                 ally use release=current.

     base=base   This specifies a directory under which csup will maintain its
                 bookkeeping files, describing the state of each collection on
                 the client machine.  The base directory must already exist;
                 csup 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; csup will not create it.

                 As a special case, if prefix is a symbolic link pointing to a
                 nonexistent file named `SKIP', then csup 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
                 supfile on several machines, yet control which collections
                 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,
                 csup 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 csup falls back upon transferring the entire file.

                 In general, csup 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, csup is willing
                 to delete two classes of files:
                 o   Files that were previously created or updated by csup
                     itself.
                 o   Checked-out versions of files which are marked as dead on
                     the server.

     use-rel-suffix
                 Causes csup 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 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 -z command line option enables the compress keyword for
                 all collections, regardless of what is specified in the sup-
                 file.  Likewise, the -Z command line option disables the
                 compress option for all collections.  csup 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 numer-
                 ous unneeded ``fixups'', and thus to slow updates.

     umask=n     Causes csup 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.  Unrecog-
     nized keywords are silently ignored for backward compatibility with sup.

CVS MODE

     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 csup will provide the correspond-
     ing 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 sup-
                 ported.

                 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 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 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, csup 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 csup to edit the checked-out files in
     such a way as to transform them from the `current' versions to 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, csup 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, csup is able to ``adopt'' an
     existing file tree acquired by FTP or from a CD-ROM.  csup 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 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 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
     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 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.

     csup 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

csup AND FIREWALLS

     In its default mode, csup will work through any firewall which permits
     outbound connections to port 5999 of the server host.

USING csup WITH SOCKS

     csup can be used through a SOCKS proxy server with the standard runsocks
     command.  Your csup executable needs to be dynamically-linked with the
     system libraries for runsocks to work properly.
          update has begun, ssh will keep the forwarded channels open as long
          as they are needed.

     2.   Run csup 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.

SEE ALSO

     cvs(1), rcsintro(1), ssh(1).

     http://mu.org/~mux/csup.html

AUTHORS

     Maxime Henrion <mux@FreeBSD.org> is the author of csup, the rewrite of
     CVSup in C.  John Polstra <jdp@polstra.com> is the author of CVSup.

LEGALITIES

     CVSup is a registered trademark of John D. Polstra.

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

FreeBSD                        February 1, 2006                        FreeBSD