.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright 2000-2001 Olaf Wagner.
.\" 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 Olaf Wagner.
.\" 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.class.5,v 1.12 2001/01/26 01:42:48 jdp Exp $
.Dd December 10, 2000
.Dt cvsupd.class 5
.Os FreeBSD
.Sh NAME
.Nm cvsupd.class
.Nd client class based access restrictions on CVSup collections
.Sh DESCRIPTION
.Nm cvsupd.class
is the configuration file read by the
.Xr cvsupd 8
daemon to specify access rights and restrictions to collections of
files based on the class of the client.
If
.Nm
does not exist,
.Nm cvsupd
grants free access to all collections by default.
.Pp
The
.Nm cvsupd.class
file resides in the base directory of the
.Nm cvsupd
server.
By default, the base directory is
.Pa /etc/cvsup ,
but the location can be overridden with the
.Fl b
option to
.Nm cvsupd .
.Pp
The
.Nm cvsupd.class
file contains specifications of client classes with a syntax similar to
other configuration files such as
.Pa /etc/printcap
and
.Pa /etc/login.conf .
Comment lines beginning with
.Ql #
are ignored, as are empty lines.
All other lines are considered to contain class specifications.
Each line contains a single class specification.
Long lines can be broken up by using the backslash
.Pq Ql \e
as a continuation character at the end of the line.
.Pp
A class specification consists of fields separated by colons
.Pq Ql \&: .
The first field of each entry contains the name of the class.
The remaining fields contain attribute-value pairs in the form
.Ql Ar attribute Ns = Ns Ar value .
Empty fields and fields containing only white space are ignored.
.Sh PATTERNS
Many of the values consist of comma-separated lists of
.Em patterns .
Patterns are by default shell-style patterns as described in
.Xr sh 1 ,
using the wild card constructs
.Ql * ,
.Ql ? ,
and
.Ql [...] .
Unlike
.Xr sh 1 ,
however, there is no special treatment for
.Ql /
or for leading
.Ql \&.
characters.
That is, these characters are matched by wild cards just the same
as other characters.
.Pp
If a pattern begins with
.Ql +
then it is instead interpreted as a regular expression.
The leading
.Ql +
is removed and the regular expression is anchored implicitly, as if
it began with
.Ql ^
and ended with
.Ql $ .
To begin a shell-style pattern with
.Ql + ,
use
.Ql [+] .
.Pp
If a pattern is preceded by
.Ql !
then it is negated.
A negated pattern selects whatever the pattern does
.Em not
match.
When negating a regular expression pattern, the
.Ql !
should come first, followed by the
.Ql + .
.Pp
For more complex matching, patterns can be combined into comma-separated
lists.
The patterns in a list are applied in order from left to right.
Later patterns override the earlier ones; i.e., the last match wins.
For example, the pattern list
.Ql f*,!fu*
would match all strings beginning with
.Ql f
except for those beginning with
.Ql fu .
.Sh ATTRIBUTES
The following attributes apply to all collections:
.Pp
.Bl -tag -width Fl
.It Cm collections Ns = Ns Ar patternlist
Clients in this class will only be able to access collections that are
matched by the pattern list.
Other collections will be treated as if they did not exist.
.It Cm collection-dirs Ns = Ns Ar patternlist
Clients in this class will only be able to access collections in
subdirectories matched by the pattern list.
Other collections will be treated as if they did not exist.
.Pp
These subdirectories are relative to the server's
.Ar base
directory.
By default the server looks for collections in a single subdirectory
.Pa sup ,
but a list of subdirectories can be specified on the command line
with the
.Fl c
option.
The
.Cm collection-dirs
specification is applied to that list.
In other words,
.Cm collection-dirs
can be used to eliminate certain subdirectories for a given class,
but it cannot be used to add new subdirectories which were not
specified on the command line.
.El
.Pp
The remaining attributes apply only to collections containing RCS
files:
.Pp
.Bl -tag -width Fl
.It Cm branches Ns = Ns Ar patternlist
Only branches matched by the pattern list will be visible to
clients in this class.
Valid branch names are all special CVS branch tags and the
literal
.Ql .
which specifies the main branch of the revision tree.
.Sm off
.It Cm branches/ Ar collection No = Ar patternlist
.Sm on
This attribute can be used to further refine the
.Cm branches
specification for a specific collection.
The given pattern list is appended to the end of the
.Cm branches
pattern list, and the result is used to control which branches are
visible in the specified collection.
Note:
.Ar collection
must be the exact name of a collection; it is not a pattern.
.It Cm tags Ns = Ns patternlist
Only tags matched by the pattern list will be visible to clients in
this class.
.Sm off
.It Cm tags/ Ar collection No = Ar patternlist
.Sm on
This attribute can be used to further refine the
.Cm tags
specification for a specific collection.
The given pattern list is appended to the end of the
.Cm tags
pattern list, and the result is used to control which tags are
visible in the specified collection.
Note:
.Ar collection
must be the exact name of a collection; it is not a pattern.
.It Cm opaque-collections Ns = Ns patternlist
All collections matched by the pattern list will be treated as
.Em opaque .
In an opaque collection, certain branches and tags are hidden from the
client.
.Pp
Normally the opaque collections are determined automatically, based
on the values of other attributes.
The
.Cm opaque-collections
attribute is provided for completeness, but it is not expected to be
needed.
.El
.Pp
Finally, each class specification may contain this attribute:
.Bl -tag -width Fl
.It Cm default Ns = Ns Ar class
Any attributes not specified for the current class will be copied
from the class named by the
.Cm default
attribute.
The named class must have already been defined earlier in the
.Pa cvsupd.class
file; forward references are not allowed.
.Pp
If a class has no
.Cm default
attribute specification, its defaults are taken from the
class named
.Ql default .
The
.Ql default
class may be defined in
.Pa cvsupd.class
as the first entry in the file.
If it is missing, the server provides a
.Ql default
class which gives free access to all collections, equivalent to the
following:
.Bd -literal
default:\e
  :collections=*:\e
  :collection-dirs=*:\e
  :branches=*:\e
  :tags=*:\e
  :opaque-collections=!*:
.Ed
.El
.Sh IMPLEMENTATION NOTES
The implementation of the class concept is currently contained
completely in the CVSup server
.Nm cvsupd .
Information about hidden collections and non-visible branches of
partially hidden collections is never communicated to the client.
For partially hidden RCS files, the server pretends not to know
anything about deltas, tags, and branches that are not visible for the
client.
.Pp
Due to the structure of RCS files, it is only possible to hide parts
of branches from the branch point on the main trunk to the tip of the
branch onwards, and the top part of the main trunk (on which no other
exported branches may reside).
.Pp
When the export status of a collection changes, the client will not
get any new deltas that weren't visible to it before by default,
because the file attributes (including the modification time) will
probably not have changed. Thus in these cases it is necessary to
force the server to perform a complete detailed comparison of all RCS
files. As currently no meta-information about the export status of
collections is kept at the client, there is no way to automate this
procedure. As a workaround, both the client and the server have been
extended to recognize the
.Fl x
command line option, which enforces the complete compare. The option
only needs to be given to the server or the client, not to both.
.Pp
If the
.Nm cvsupd.class
file changes, the server needs not to be restarted or informed via a
signal; the new information will automatically be used for the next
client connection.
.Sh FILES
.Bl -tag -width /etc/cvsup/cvsupd.passwd -compact
.It Pa /etc/cvsup
Default
.Ar base
directory.
.It Pa /etc/cvsup/cvsupd.class
Client class based access rights/restrictions
.It Pa /etc/cvsup/cvsupd.access
Network/host based access rights/restrictions
.It Pa /etc/cvsup/cvsupd.passwd
.Nm CVSup
password database
.El
.Sh EXAMPLES
The following example grants default access to all collections
containing the string
.Ql pub
in their names as well as to the
.Ql src-base
collection:
.Bd -literal
default:\e
  :collections=*pub*,src-base:\e
  :branches=*:\e
  :tags=*:
.Ed
.Pp
In the next example, all collections except those whose names begin
with ``pr_'' and ``ex_'' are exported by default:
.Bd -literal
default:\e
  :collections=!pr_*,!ex_*:
.Ed
.Pp
Here is a specification for a guest class that exports all collections
whose names contain only letters.  Access to these collections is
unrestricted, except for the collection
.Ql flash ,
from which only the stable release branches and corresponding tags
are exported:
.Bd -literal
guest:\e
  :collections=+[A-Za-z]*:\e
  :branches=*:\e
  :tags=*:\e
  :branches/flash=!*,release_flash_?_?_stable:
.Ed
.Sh SEE ALSO
.Xr co 1 ,
.Xr cvpasswd 1 ,
.Xr cvs 1 ,
.Xr cvsup 1 ,
.Xr cvsupd 8 ,
.Xr cvsupd.passwd 5 .
.Pp
.Bd -literal
http://www.polstra.com/projects/freeware/CVSup/
.Ed
.Sh AUTHORS
.An John Polstra Aq jdp@polstra.com ,
.An Olaf Wagner Aq wagner@elego.de .
.Sh BUGS
.Bl -bullet
.It
Checkout mode for partially hidden collections is currently not
implemented.
.It
In exact mode (which is no more cleared by default for partially
hidden collections) the algorithm used for tags often leads to
unnecessary delete tag/add tag sequences when the export status of
tags and/or branches changes.
.It
Probably many more as the implementation has not been extensively
tested yet.
.El
