.\" Copyright 1996-2003 John D. Polstra.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgment:
.\"      This product includes software developed by John D. Polstra.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: cvsupd.8,v 1.39 2003/03/04 18:24:47 jdp Exp $
.\"
.Dd January 1, 2002
.Os FreeBSD
.Dt CVSUPD 8
.Sh NAME
.Nm cvsupd
.Nd network distribution server for CVS repositories
.Sh SYNOPSIS
.Nm
.Op Fl efv
.Op Fl A Ar addr
.Op Fl b Ar base
.Op Fl c Ar collPath
.Op Fl C Ar maxClients
.Op Fl l Ar log
.Op Fl p Ar port
.Op Fl P Ar range
.Op Fl s Ar scanDir
.Op Fl Z Ar comprLevel
.Sh DESCRIPTION
.Nm
is the server program for the
.Nm CVSup
network distribution package.
For information about the companion client program, see
.Xr cvsup 1 .
.Pp
In normal usage,
.Nm
should be started with the
.Ql Fl C Ar maxClients
option.  Unless
.Fl f
is specified, it runs as a background daemon, fielding connection
requests from remote clients.  For each connection,
.Nm
forks a child process to serve the files requested by the client.
.Pp
The following options are supported:
.Bl -tag -width Fl
.It Fl A Ar addr
Specifies a local address (dotted quad or hostname) on which the
server will accept connections.  This may be useful on hosts which
have multiple IP addresses.
.It Fl b Ar base
Uses
.Ar base
as the base directory for the configuration files.
The default is
.Pa /usr/local/etc/cvsup .
.It Fl c Ar collPath
Searches the specified directories for information about the collections
being offered.
.Ar collPath
contains of one or more directory names, separated by colons.
Non-absolute pathnames are interpreted relative to the base
directory.
The default search path is
.Ql sup .
.It Fl C Ar maxClients
Limits the number of simultaneous clients to
.Ar maxClients .
Clients beyond the specified maximum are politely refused service.
.Pp
If this option is not specified,
.Nm
serves one client in the foreground and then exits.
.It Fl e
Suppresses the redirection of the standard output and standard
error when running as a daemon and logging to a syslog facility.
Otherwise, these descriptors are redirected to
.Pa /dev/null .
This option is useful for capturing any panic messages which might
be emitted in the rare event of a crash of the server.
Such messages are very helpful for debugging, but there
is no reliable way to send them to syslog.
A recommended way to use the option is like this:
.Dl cvsupd -e ... >>/var/tmp/cvsupd.out 2>&1
assuming that the command line syntax of
.Xr sh 1
is used.
.It Fl f
When
.Fl C Ar maxClients
is specified, causes
.Nm
to stay in the foreground instead of becoming a background daemon.
.It Fl l Ar log
Directs log messages to
.Ar log .
If
.Ar log
is of the form
.Cm @ Ns Ar facility
(e.g.,
.Ql @local0 )
then logging is done via syslog to the indicated facility.
Otherwise,
.Ar log
is treated as the name of a log file.
If the file
already exists, new messages are appended to its end.
.Pp
For each client served, at least two messages are logged.  The first
message identifies the client by username and hostname.  The last
message reports the success or failure of the update and gives the
total network I/O in Kbytes (1K = 1024).  Additional messages may be
emitted to report errors or other noteworthy conditions.
.\" FIXME - default
.It Fl p Ar port
Listens for connections on an alternate TCP port.
The default port is 5999.
When not in passive mode, the server also uses the next lower port
to establish a second
connection (called the data connection) back to the client.
.It Fl P Ar range
Sets the range of server TCP ports to be used for the data connection,
when in passive mode.
.Ar Range
may be a single integer or a range given as
.Ql lo-hi .
.It Fl s Ar scanDir
Enables mirror mode, and specifies the directory under which the scan
files can be found.  If it is not an absolute pathname,
.Ar scanDir
is interpreted relative to the base directory.  See
.Sx RUNNING A CVSup MIRROR SITE ,
below.
.It Fl v
Prints the version number and exits, without serving any clients.
.It Fl Z Ar comprLevel
Sets the compression level to
.Ar comprLevel .
The compression level must be between 0 and 9.
A level of 0 means no compression, while 9 provides maximum compression.
The default level is 1.
Higher levels provide relatively little improvement, at a rather high
cost in CPU cycles.
.El
.Sh PREPARING A FILE COLLECTION REPOSITORY
The file collections which
.Nm
makes available to clients are described by various configuration files.
The configuration files reside under the directory
.Sm off
.Ar base / Ar collDir ,
.Sm on
where
.Ar base
is the directory specified by the
.Fl b Ar base
command line option, or
.Pa /usr/local/etc/cvsup
by default.
.Ar collDir
is any of the directories specified with the
.Fl c
option, or
.Ql sup
by default.
.Pp
Each collection's configuration files are kept in a separate
subdirectory of
.Sm off
.Ar base / Ar collDir ,
.Sm on
named after the collection itself.
For example, the configuration for the
.Ql src-base
collection would be found in
.Sm off
.Ar base / Ar collDir Pa /src-base .
.Sm on
Within the collection's subdirectory, there should be a
.Pa releases
file and a list file.
The
.Pa releases
file contains one line per release.
The first word of each line is the name of the release, e.g.,
.Ql cvs .
That must be followed by the following phrases, in any order:
.Bl -tag -width Fl
.It Cm list= Ns Ar file
Specifies the name of the list file, relative to the collection's
subdirectory.  The list file is described below.
.It Cm prefix= Ns Ar directory
Specifies where the files making up the collection are to be found.
If
.Ar directory
is not an absolute pathname, it is interpreted relative to the base
directory
.Ar base .
If there is no
.Cm prefix
clause, the prefix defaults to
.Ar base .
.It Cm keywordprefix= Ns Ar directory
Specifies a
.Dq pseudo-prefix
which is used only for expanding the absolute pathnames for the
.Ql $\&Header$
and
.Ql $\&Source$
RCS keywords.
The
.Ar directory
should normally be the absolute pathname of the CVS repository on the
machine containing the master copy of the repository.
The use of
.Cm keywordprefix
ensures that
.Nm CVSup
will expand the RCS keywords identically on all machines, even though
the repositories may reside in different directories.
.It Cm super= Ns Ar collection
Specifies the immediate super-collection of the current collection.
In large distributions, the collections are often organized in a
hierarchical manner.  At the top of the hierarchy is a collection
containing all of the distributed files.  At the next level are
several sub-collections, each containing a subset of the files.
Each sub-collection may in turn have further sub-collections, and so
forth.  The
.Cm super
keyword specifies the collection's parent in such a hierarchical
arrangement.
.Pp
This keyword is optional.  If it is omitted,
.Nm
assumes nothing about the relationship between the current
collection and the other available collections.
.Pp
Information from the
.Cm super
keywords is used for finding the appropriate scan files when the
server is running as a mirror site.  See
.Sx RUNNING A CVSup MIRROR SITE .
.It Cm nocheckrcs
Disables the comparison of MD5 checksums for updated RCS files.
Checksum mismatches for RCS files may not be meaningful, since a given
logical RCS file can have many different textual renditions.
.It Cm norcs
Disables special processing for RCS files.  They will be treated the
same as other files.
.It Cm norsync
Disables the use of the
.Em rsync
algorithm.
.Sy Note:
this keyword is deprecated in the
.Pa releases
file.  Use
.Cm norsync
or
.Cm rnorsync
in the list file instead.  (See below.)
.El
.Pp
Unrecognized phrases are accepted but ignored, for backward
compatibility with the
.Nm sup
package.
Note that even though
.Nm
often serves only a single release, the
.Pa releases
file is still required.
.Pp
The list file specifies the details of how to upgrade the client's
version of the collection.
Each line contains a single command.  Blank lines are ignored, as are
lines beginning with
.Ql # .
Any filenames specified are taken as relative to the
.Cm prefix
directory given in the
.Pa releases
file.
.Pp
Many of the list file commands accept file name patterns as
arguments.
These are similar to the patterns accepted by
.Xr sh 1 ,
and may include the wild card constructs
.Ql * ,
.Ql ? ,
and
.Ql [...] .
With the exception of
.Cm omitany
patterns, any slash characters in file names must be matched
explicitly by slash characters in the pattern.
Leading periods in file names are not treated specially.
For example, the pattern
.Ql *
matches the filename
.Ql .profile .
.Bl -tag -width Fl
.It Cm upgrade Ar pattern ...
All files and directories matching any of the given patterns
will be included in the list of files to be upgraded.
If a directory name is matched, it recursively includes all
files and subdirectories within it.
.It Cm always Ar pattern ...
This command is the same as
.Cm upgrade ,
except that it overrides any
.Cm omitany
commands.
.It Cm omitany Ar pattern ...
Files or directories matching any of the given patterns will be
omitted from the upgrade.  If a directory name is matched,
then it and all files and subdirectories beneath it are omitted.
.Pp
The patterns for
.Cm omitany
are interpreted differently than other patterns.  For normal
patterns, a slash character in a pathname must be matched explicitly
by a slash character in the pattern.  For
.Cm omitany
patterns, slashes are treated the same as other characters.
Thus the pattern
.Ql *.c
will match any pathname ending in
.Ql \&.c ,
including, for example,
.Ql foo/bar/lam.c .
.It Cm symlink Ar pattern ...
Symbolic links matching any of the given patterns will be upgraded
as symbolic links, rather than as the files they refer to.
Otherwise, symbolic links are followed and their target files are
sent to the client.
.It Cm rsymlink Ar pattern ...
This command is similar to
.Cm symlink ,
but if a directory is matched, all symbolic links beneath it in the
tree are treated as matched.
.It Cm norsync Ar pattern ...
The rsync algorithm will not be used for updating files matching any
of the given patterns.  This is useful for log files, where
.Nm CVSup Ns "'s"
.Dq append
optimization is more effective than the rsync algorithm.
.It Cm rnorsync Ar pattern ...
This command is similar to
.Cm norsync ,
but if a directory is matched, all files beneath it in the tree are
treated as matched.
.It Cm execute Ar command Pq Ar pattern ...
The given
.Ar command
will be executed by the client whenever a file matching one of the
.Ar pattern Ns s
is successfully updated.
The
.Ar command
comprises all words up to the first
.Ql (
character.  Any occurrences of the string
.Ql %s
are replaced by the pathname of the updated file on the client host.
Occurrences of
.Ql %%
are replaced by
.Ql % .
The command is executed by passing it to
.Pa /bin/sh .
.Pp
There may be multiple patterns, separated by white space.
They are interpreted relative to the
.Cm prefix
directory.
Each pattern should be written to match the appropriate files as they
exist on the
.Em server .
For example, the
.Ql ,v
suffix of an RCS file name must be matched, even though that suffix
will not be present on the client if checkout mode is in effect.
Slashes in file names must be matched by explicit slashes in the pattern.
CVS
.Ql Attic
directories are implicitly included in the matching process, and
should not be specified directly in the patterns.
A matching file will be found whether it is in the Attic or not.
.Pp
If an
.Cm execute
statement matches a directory, its command is executed if the
directory is created for the first time, or if its attributes are
changed.
The command is executed when ascending out of the directory, i.e.,
after its files and subdirectories have been processed.
.Pp
If multiple
.Cm execute
statements match a file, all of the associated commands are executed
in sequence.
.Pp
For security reasons, the client may choose to ignore all
.Cm execute
statements.
.El
.Pp
Unrecognized commands are accepted but ignored, for backward
compatibility with
.Nm sup .
.Sh RUNNING A CVSup MIRROR SITE
A mirror is a server which obtains and updates its files from a master
site by means of
.Nm CVSup ,
and redistributes them via
.Nm CVSup
to other sites.  Mirror sites are commonly used in large projects
to spread the load among a number of servers.  The files being
distributed originate at a master site.  Each mirror site updates its
own copies of the files periodically from there.  Clients in turn
obtain their updates from any of the mirror sites.
.Pp
.Nm
has a special mode of operation for mirror sites that dramatically
increases its efficiency.  This mode is enabled by the
.Fl s Ar scanDir
option on the command line.  Without the
.Fl s
option,
.Nm
makes a full file tree traversal over the files in each requested
collection, performing a
.Xr stat 2
system call on every file.  It does this for each client that connects
to it, on the assumption that any of the files could change at any
time.  Such a traversal imposes a heavy seek load on the disks
containing the files, and limits the number of clients that can be
served simultaneously.
.Pp
On a mirror site, the files in the collections are known to
change only when new versions of them come in via
.Nm CVSup .
The
.Fl s
option allows
.Nm
to take advantage of this property to completely avoid the file tree
traversals.  This reduces the disk load on the server by orders of
magnitude.  In place of the file tree traversal,
.Nm
gets the necessary information about the files in the collections by
reading
.Em scan
files.  The scan files are created by the
.Nm cvsup
client when it updates the files on the mirror site from the
originals at the master site.  In
.Xr CVSUP 1 ,
these files are referred to as
.Em list
files.  Both names refer to the same files.  Each time
.Nm
serves a client, it finds the scan files created by the most recent
update from the master site.  Thus the server always has fully
up-to-date information about the files in the collections, without the
need to perform a file tree traversal.
.Pp
The
.Fl s
option is followed by a directory name which specifies where the
scan files can be found.  It is normally a subdirectory
of the base directory, and it must match the location where the
.Nm cvsup
client maintains its list files.  By default,
.Nm cvsup
locates these files under the
.Pa sup
subdirectory of the base directory.  To match this,
.Nm
should be run with
.Ql -s sup .
If
.Nm cvsup Ns 's
list file location is changed from the default using the
.Fl c
option, then
.Nm Ns 's
scan directory must be changed the same way.  There is no default
for the
.Fl s
option.  If it is not given explicitly on the command line, no scan
files are used.
.Pp
There does not need to be a scan file for every collection.
.Nm
first looks for the scan file for the collection requested by the
client.  If that scan file does not exist,
.Nm
tries the scan files for each successive super-collection, and uses
the first one it finds.  (See the description of the
.Cm super
keyword in
.Sx PREPARING A FILE COLLECTION REPOSITORY
for details.)
If no suitable scan file is located,
.Nm
falls back on performing a file tree traversal.
.Sh ACCESS CONTROL
Access to the server is unrestricted by default, but there is a
reasonably flexible mechanism for limiting access based on the IP
addresses of connecting clients.  It is enabled by placing a set
of rules into the access file
.Ar base Ns Pa /cvsupd.access .
The access file is a text file with one rule per line.  Comments
begin with
.Ql #
and extend to the end of the line.  White space is ignored except
where it is needed to separate adjacent tokens.  Blank lines are
ignored.
.Pp
Each rule consists of the following components:
.Bl -bullet
.It
A flag indicating whether the rule is a
.Em permit
rule, an
.Em authenticate
rule, or a
.Em deny
rule.  The flag is expressed as a single character:
.Ql +
means
.Em permit ,
.Ql *
means
.Em authenticate,
and
.Ql -
means
.Em deny.
.It
An IP address to compare with the client's IP address to determine
whether the rule applies to the client.  This may be expressed either
as a numeric IP address or as a host name.  Numeric addresses consist
of 1 to 4 octet values, separated by dots.  If fewer than 4 octets are
specified, the trailing octets are assumed to contain 0.
.Pp
Host names are converted to numeric addresses when they are read.
If a host has multiple addresses, a separate rule is added for each
address.  This may or may not have the desired effect.
.Pp
Host names should be used with caution.  A name that is slow to
resolve can bog down the server significantly.
.It
A
.Em matching
mask to be ANDed with the IP addresses of the rule and the client
before comparing the addresses.  This mask is specified as
.Ql /
followed by an integer giving the number of high-order 1s in the
mask.  For example,
.Ql /24
specifies a mask of 0xffffff00.  The
.Em matching
mask is optional; if omitted, it defaults to
.Ql /32 .
.It
A
.Em counting
mask that determines how the clients that match the rule are counted.
(See below.)  It is specified the same way as the
.Em matching
mask.  The
.Em counting
mask is optional; if omitted, it defaults to the same value as the
.Em matching
mask.
.It
A
.Em limit
specifying the maximum number of matching clients allowed at the same
time.  This is specified as a decimal integer, preceded by white
space to separate it from the preceding component.  The
.Em limit
is optional.  If omitted, it defaults to 0 for a
.Em deny
rule, or to infinity for a
.Em permit
rule.
.El
.Pp
When a client connects to the server, its IP address is checked
against successive rules in sequence.  Each rule is processed as
follows:
.Bl -enum
.It
The IP address of the rule is compared with the IP address of the
client, after ANDing each address with the
.Em matching
mask.  If the addresses do not match, the rule is ignored.
.It
The IP addresses of all other currently connected clients are compared
with the IP address of the connecting client, after ANDing each
address with the
.Em counting
mask.  If the number of matching clients (not counting the connecting
client) is less than the
.Em limit ,
then the rule
.Em succeeds .
Otherwise, the rule
.Em fails .
.It
If the rule is a
.Em permit
rule and it succeeded, the client is allowed access, and the rest of the
rules are ignored.
.It
If the rule is an
.Em authenticate
rule and it succeeded, the server attempts to verify the client's
identity using a challenge-response protocol (see
.Sx AUTHENTICATION ,
below).
Access is granted or denied based on the outcome of authentication.
The rest of the rules are ignored.
.It
If the rule is a
.Em deny
rule and it failed, the client is denied access, and the rest of the
rules are ignored.
.It
Otherwise, processing continues with the next rule.
.El
.Pp
There is an implicit
.Em authenticate
rule at the end of the list which matches any IP address.  Thus,
if the processing reaches the end of the list of rules without having
allowed or denied access, access is controlled by the authentication
mechanism.
.Pp
Here are some examples illustrating how the rules are commonly used.
.Pp
.Dl -spam.cyberpromo.com
Deny all access from a specific host.
.Pp
.Dl +mirror.FreeBSD.org
Permit unlimited access from a specific host.
.Pp
.Dl -user.FreeBSD.org 1
Limit a specific host to at most 1 connection at a time.
.Pp
.Dl -198.211.214/24
Deny all access from hosts in a specific class C address block.
.Pp
.Dl -198.211.214/24 3
Allow at most 3 connections total from the hosts in a specific class C
address block.
.Pp
.Dl -198.211.214/24/32 3
Allow at most 3 connections from each of the hosts in a specific
class C address block.
.Pp
Note the difference between the previous two examples.
The first example imposes a per-network limit, while the second
example imposes a per-host limit.  The difference is in the
.Em counting
mask.  The 24 bit mask in the first example produces a single counter
that is shared by all of the hosts in the specified address block.  The
32 bit mask in this example produces a separate counter for each host.
.Pp
.Dl -0.0.0/0/24 1
Allow no more than 1 connection at a time from each block of 256
addresses.
.Pp
.Dl *0.0.0.0/0
For all clients, use authentication to decide whether access is allowed.
.Pp
When updating the access file, it is not necessary to halt the
server.  But the file should be copied for editing, and then the new
version should be moved atomically into place.  There is no need to
signal the server after updating the file.  The server will notice
that the file has been touched, and will rescan it automatically.
In addition, the server rescans the file every 3 hours to keep up
with DNS changes that might affect the resolved addresses of host
names.
.Pp
Syntax errors in individual rules are logged, and the offending
rules are ignored.  Host name lookup failures are also logged.
.Sh AUTHENTICATION
.Nm CVSup
implements an authentication mechanism which can be used to control
access to the server.  It 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.
.Pp
Authentication of the client is invoked by a successful
.Em authenticate
rule in the
.Ar base Ns Pa /cvsupd.access
file, or by
.Dq falling off the end
of the file.  If there is no
.Pa cvsupd.access
file, clients are not authenticated.
.Pp
The file
.Ar base Ns Pa /cvsupd.passwd
holds the information used for performing authentication.  This file
contains a record for each client who is allowed access to the
server.  Each record occupies one line in the file.  Lines beginning
with
.Ql #
are ignored, as are lines containing only white space.
White space is significant everywhere else in the file.  Fields are
separated by
.Ql \&:
characters.
.Pp
The first record of the file is special.  It specifies the identity
of the server itself.  This server record has the form:
.Pp
.Dl Ar serverName Ns No : Ns Ar privateKey
.Pp
.Ar ServerName
is the canonical name of the server, e.g.,
.Ql CVSup.FreeBSD.ORG .
This name is sent to the client, which uses it to choose an
appropriate client name and shared secret for authentication.  The
name is case-insensitive.
.Pp
.Ar PrivateKey
is any string of characters except
.Ql \&: .
When the server generates random challenges to send to the client,
it uses
.Ar privateKey
to make the challenges harder to guess.  Challenges are random and
quite unpredictable in any case, so the
.Ar privateKey
isn't really very important.  It can be left empty if desired, but
the
.Ql \&:
that precedes it must be present.
.Pp
All of the remaining records in the file correspond to individual
clients.  Each client record has the following form:
.Bd -literal -offset indent
.Sm off
.Xo Ar clientName No : Ar sharedSecret No :
.Ar class No : Ar comment
.Xc
.Sm on
.Ed
.Pp
All fields must be present even if some of them are empty.
.Ar ClientName
is the name of the client to which the record applies.  By
convention, e-mail addresses are used for all client names, e.g.,
.Ql BillyJoe@FreeBSD.ORG .
Client names are case-insensitive.
.Pp
.Ar SharedSecret
is a secret string of characters known only to the client and the server.
It is generated from a password chosen by the client, using the
.Nm cvpasswd
utility.
The client proves its identity to the server (and vice versa) by
demonstrating that it knows the
.Ar sharedSecret .
A client's access may be disabled by changing its
.Ar sharedSecret
field to
.Ql * .
.Pp
The shared secret is never sent across the network, nor can it be used
to find out the client's password.  However, given the shared secret,
a modified version of
.Nm cvsup
could impersonate the client.  Thus, care must be taken to ensure that
the
.Pa cvsupd.passwd
file is readable only by the server.
.Pp
.Ar Class
is reserved for future use.  It should be empty.
.Pp
.Ar Comment
contains any additional information about the client that might be
useful to the server administrator.  For example, it may contain
the client's full name and other contact information.
.Pp
When updating the
.Pa cvsupd.passwd
file, it is not necessary to halt the server.  But the file should
be copied for editing, and then the new version should be moved
atomically into place.  There is no need to signal the server after
updating the file.
.Pp
Syntax errors in individual records of the
.Pa cvsupd.passwd
file are logged, and the offending records are ignored.
.\" ---------------------------------------
.Sh HOW ACCESS CONTROL AND AUTHENTICATION INTERACT
Here is a summary of the interactions between the access control and
authentication mechanisms.  The key principle is that access control
takes place first.  The outcome of access control determines whether
authentication is performed too.
.Bl -enum
.It
If there is no
.Pa cvsupd.access
file, then all clients are granted access.  No authentication is
done, even if
.Pa cvsupd.passwd
exists.
.It
If the
.Pa cvsupd.access
file exists but is empty, all clients are subjected to
authentication.  If
.Pa cvsupd.passwd
does not exist, nobody can access the server.
.It
If
.Pa cvsupd.access
exists and has some rules in it, but there is no
.Pa cvsupd.passwd
file, then successful
.Em authenticate
rules cause access to be denied.  Access is still granted to those
who match successful
.Em permit
rules.  Falling off the end of the
.Pa cvsupd.access
file results in denial of access.
.It
If both the
.Pa cvsupd.access
and
.Pa cvsupd.passwd
files exist, then:
.Bl -bullet -compact
.It
Successful
.Em permit
rules cause access to be granted without authentication.
.It
Successful
.Em authenticate
rules cause authentication to be performed.  Access is granted or
denied based on the outcome of that.  Falling off the end of the
.Pa cvsupd.access
file is included in this case.
.It
Failing
.Em deny
rules cause access to be denied.
.El
.El
.Sh RCS KEYWORD EXPANSION
In checkout mode,
.Nm CVSup
expands RCS keywords as described in
.Xr co 1 .
It expands all of the standard keywords, and also the non-standard
.Ql $\&CVSHeader$
keyword.
This expands the same as
.Ql $\&Header$ ,
except that the RCS file's pathname is expressed relative to the
.Cm prefix
directory, rather than as an absolute pathname.
The
.Cm prefix
is assumed to be the root of the CVS repository.
.Pp
It is also possible to define aliases for the standard RCS keywords,
and to selectively enable or disable the recognition of individual
keywords.
These properties are controlled on a repository-wide basis by
directives in a file named
.Ar prefix Ns Pa /CVSROOT/options .
Each directive occupies one line of the file.
Comments begin with
.Ql #
and extend to the end of line.
Blank lines are ignored.
The syntax is ridiculous, for historical reasons.
.Pp
To define a keyword alias, use a line of the form:
.Sm off
.Dl tag= Ar alias Op Li = Ar keyword
.Sm on
For example:
.Dl tag=FreeBSD=CVSHeader
defines a new RCS keyword
.Ql $\&FreeBSD$ ,
which expands the same as
.Ql $\&CVSHeader$ .
If the second
.Ql =
and the
.Ar keyword
are omitted, the keyword defaults to
.Ql Id .
.Pp
To disable all but certain selected keywords, use a line of the
form:
.Sm off
.Dl tagexpand=i Ar keyword Op , Ar ...
.Sm on
For example:
.Dl tagexpand=iFreeBSD,Id
disables the expansion of all keywords except
.Ql $\&FreeBSD$
and
.Ql $\&Id$ .
The leading
.Ql i
stands for
.Dq include .
.Pp
To enable all but certain selected keywords, use a line of the
form:
.Sm off
.Dl tagexpand=e Ar keyword Op , Ar ...
.Sm on
For example:
.Dl tagexpand=eFreeBSD,Id
enables the expansion of all keywords except
.Ql $\&FreeBSD$
and
.Ql $\&Id$ .
The leading
.Ql e
stands for
.Dq exclude .
.Sh SHUTDOWN
If there exists a file
.Ar base Ns Pa /cvsupd.HALT
that is newer than the time when the server was started, then the server
will reject all new incoming connection requests.
Clients which had already started will run to completion, but no new
ones will be accepted.
This mechanism is awkward and weak, and will probably be changed in a
future release.
.Sh SECURITY
.Nm
does not create or write any files, except for its log file if one
is specified on the command line.
There is thus little risk that
.Nm
can be subverted into damaging the system on which it is running.
A more likely risk is that
.Nm
might be spoofed into sending out files that are not intended to be
publicly distributed.
.Nm
is very careful to prevent this from happening.
Nevertheless, for maximum protection it is a good idea to run
.Nm
as a completely unprivileged user analogous to
.Ql nobody ,
serving only files that are readable by everyone.
.Pp
.Nm CVSup
has no provision for encrypting the data sent across the network.  If
secrecy is desired then the connection can be tunneled through
.Nm ssh .
.Sh FILES
.Bl -tag -width base/sup/collection/releasesxx -compact
.It Pa /usr/local/etc/cvsup
Default
.Ar base
directory.
.It Pa sup
Default
.Ar collDir
subdirectory.
.Sm off
.It Xo Ar base / Ar collDir / Ar collection
.Pa /releases
.Xc
.Sm on
Releases file.
.Sm off
.It Xo Ar base / Ar collDir / Ar collection
.No / Ar list
.Xc
.Sm on
List file.
.It Ar base Ns Pa /cvsupd.HALT
Shutdown file.
.It Ar base Ns Pa /cvsupd.access
Access control file.
.It Ar base Ns Pa /cvsupd.passwd
Authentication password file.
.Sm off
.It Ar prefix Pa /CVSROOT/options
.Sm on
RCS keyword configuration file.
.El
.Sh SEE ALSO
.Xr co 1 ,
.Xr cvpasswd 1 ,
.Xr cvs 1 ,
.Xr cvsup 1 .
.Pp
.Bd -literal
http://www.cvsup.org/
.Ed
.Sh AUTHORS
.An John Polstra Aq jdp@polstra.com .
.Sh LEGALITIES
CVSup is a registered trademark of John D. Polstra.
.Sh BUGS
An RCS file is not recognized as such unless its name ends with
.Ql \&,v .
.Pp
Any directory named
.Ql Attic
is assumed to be a CVS Attic, and is treated specially.