##
##  OSSP shiela - CVS Access Control and Logging Facility
##  Copyright (c) 2000-2002 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2000-2002 The OSSP Project <http://www.ossp.org/>
##
##  This file is part of OSSP shiela, an access control and logging
##  facility for Concurrent Versions System (CVS) repositories
##  which can be found at http://www.ossp.org/pkg/tool/shiela/.
##
##  This program is free software; you can redistribute it and/or
##  modify it under the terms of the GNU General Public  License
##  as published by the Free Software Foundation; either version
##  2.0 of the License, or (at your option) any later version.
##
##  This program is distributed in the hope that it will be useful,
##  but WITHOUT ANY WARRANTY; without even the implied warranty of
##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
##  General Public License for more details.
##
##  You should have received a copy of the GNU General Public License
##  along with this file; if not, write to the Free Software
##  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
##  USA, or contact Ralf S. Engelschall <rse@engelschall.com>.
##
##  shiela.pod: manual page (syntax: POD)
##

=pod

=head1 NAME

B<OSSP shiela> - Access Control and Logging Facility for CVS

=head1 VERSION

B<OSSP shiela> 1.0.2 (23-Dec-2002)

=head1 DESCRIPTION

B<OSSP shiela> is an access control and logging facility for use with
the I<Concurrent Versions System> (CVS). It is intended to be hooked
into CVS's processing through the C<$CVSROOT/CVSROOT/>I<xxx>C<info>
callbacks. This way B<OSSP shiela> provides access control on a path and
branch basis to particular repository users and user groups.

Additionally, repository operations are monitored, accumulated and
logged. The lookout of logging messages can be configured individually
on a module path and branch basis and messages can be both saved to
files and/or delivered by email.

=head1 CONFIGURATION

The whole configuration of B<OSSP shiela> takes place in a single
configuration file. Per default this is C<$CVSROOT/CVSROOT/shiela.cfg>
where C<$CVSROOT> is either the environment variable C<CVSROOT> from the
users environment or the one implicitly provided by CVS because of the
scope of C<CVS/Root> files or because of an active B<-d> CVS command
line option. But one can also override the location of the configuration
file with the B<OSSP shiela> command line option B<--config>.

This file uses a C-style syntax which is described by the following
grammar rooted at I<config>:

  config    ::= directive
              | config directive
  directive ::= name ';'
              | name args ';'
  args      ::= arg
              | args arg
  arg       ::= '{' config '}'
              | m/[^ \t\n]+/

Or in words: a configuration consists of one or more directives, every
directive has a leading name, zero or more arguments and is terminated with a
semicolon. And an argument can be either a plain word (one or more
non-whitespace characters) or a complete sub-configuration enclosed in braces.
So, the syntax has only one recursion and this way is rather simple but still
powerful enough.

But this is only the general structure as understood by B<OSSP shiela>'s parser.
For semantical reasons only a particular structure is allowed to be created
with the syntax. This is described in the following.

=head2 Environment Configuration

The last configuration block is optional and for setting the run-time
environment. This configuration block has to be of the following
structure:

 Environment {
     [Program sendmail <path>;]
     [Program cvs <path>;]
     [Program diff <path>;]
     [Program xdelta <path>;]
     [Program uuencode <path>;]
 };

The individual parts of this are:

=over 4

=item B<Program sendmail E<lt>pathE<gt>;>

This overrides the path to the F<sendmail> executable. Per default
B<OSSP shiela> determines this automatically through the inherited C<$PATH>
variable. Use this either if you have B<Sendmail> not in C<$PATH> or if you
have multiple B<Sendmail> instances installed. The F<sendmail> executable
is mandatory for the operation of B<OSSP shiela>.

=item B<Program cvs E<lt>pathE<gt>;>

This overrides the path to the F<cvs> executable. Per default B<OSSP shiela>
determines this automatically through the inherited C<$PATH> variable.
Use this either if you have B<CVS> not in C<$PATH> or if you have multiple
B<CVS> instances installed. The F<cvs> executable is mandatory for the
operation of B<OSSP shiela>.

=item B<Program diff E<lt>pathE<gt>;>

This overrides the path to the F<diff> executable. Per default B<OSSP
shiela> determines this automatically through the inherited C<$PATH>
variable. Use this either if you have B<GNU Diffutils> not in C<$PATH>
or if you have multiple B<GNU Diffutils> instances installed. The
F<diff> executable is required for the operation of B<OSSP shiela>
if change summary information on text files is used in reports (see
C<details> in C<Content>).

=item B<Program xdelta E<lt>pathE<gt>;>

This overrides the path to the F<xdelta> executable. Per default B<OSSP
shiela> determines this automatically through the inherited C<$PATH>
variable. Use this either if you have B<XDelta> not in C<$PATH> or if
you have multiple B<XDelta> instances installed. The F<xdelta>
executable is required for the operation of B<OSSP shiela> if change
summary information on binary files is used in reports (see C<summary>
in C<Content>).

=item B<Program uuencode E<lt>pathE<gt>;>

This overrides the path to the F<uuencode> executable. Per default
B<OSSP shiela> determines this automatically through the inherited
C<$PATH> variable. Use this either if you have B<GNU Sharutils> not in
C<$PATH> or if you have multiple B<GNU Sharutils> instances installed.
The F<uuencode> executable is required for the operation of B<OSSP
shiela> if change summary information on binary files is used in reports
(see C<summary> in C<Content>).

=back

=head2 Project Configuration

The first configuration block is for the project to which the repository
belongs to. The configuration block has to be of the following structure:

 Project {
     Tag <string>;
     Name <string>;
     Contact <email>;
     Home <url>;
     Users {
         User <userid> <username> <email>;
         [...]
     };
     [Groups {
         Group <groupid> <groupname> { <userid> [...] };
         [...]
     };]
 };

The individual parts of this are:

=over 4

=item B<Tag E<lt>stringE<gt>;>

A short tag for the project. This usually is the abbreviation
of the project name and should be only a few characters long.
Example: C<Tag FOO;>

=item B<Name E<lt>stringE<gt>;>

The name of the project. This usually is the full name and
not an abbreviation. But it should be only a few words.
Example: C<Name "The FOO Project";>

=item B<Contact E<lt>emailE<gt>;>

The Email address under which the project can be contacted.
Example: C<Contact foo@foo.dom;>

=item B<Home E<lt>urlE<gt>;>

The URL under which the project home can be found.
Example: C<Home http://www.foo.dom/;>

=item B<User E<lt>useridE<gt> E<lt>usernameE<gt> E<lt>emailE<gt>;>

A user/member of the project. The E<lt>useridE<gt> has correspond to a Unix
user id and should match the entry in the C<passwd> database. The E<lt>usernameE<gt>
is the real name of the user and E<lt>emailE<gt> is the Email address
under which the user can be contacted. Every user which should
have access to the repository has to be configured this way.
Example: C<User foo "Mr. Foo" foo@foo.dom;>

=item B<Group E<lt>groupidE<gt> E<lt>groupnameE<gt> { E<lt>useridE<gt> [...] };>

A group of project members. This is optional and does not correspond to any
Unix groups, i.e., there is no requirement that one defines groups of users
and even if one defines one, they are used to make access control lists more
readable only.  The E<lt>groupidE<gt> is a single word, E<lt>groupnameE<gt> is
a description text of the group and the E<lt>useridE<gt> arguments have to
correspond to users which are configured with B<User> directives.
Example: C<Group team "FOO Development Team" { foo bar quux };>

=back

=head2 Repository Configuration

The second configuration block is for the repository and its modules.  The
configuration block has to be of the following structure:

 Repository {
     Tag <string>;
     Name <string>;
     Contact <email>;
     Home <url>;
     Host <hostname>;
     Path <path>;
     History <path>;
     Modules {
         Module <modulepath> <modulename> {
             [Acl <filepath> [!]<userid>[:<groupid>] [...];]
             [...]
             [Log <filepath> <reportid>:<target> [...];]
             [...]
         };
         [...]
     };
 };

The individual parts of this are:

=over 4

=item B<Tag E<lt>stringE<gt>;>

A short tag for the repository. This usually is the abbreviation of the
repository name or can be also just the same as the project tag.  It should be
only a few characters long.
Example: C<Tag FOO;>

=item B<Name E<lt>stringE<gt>;>

The name of the repository. This usually is the full name and not an
abbreviation. But it should be only a few words.
Example: C<Name "FOO CVS Repository";>

=item B<Contact E<lt>emailE<gt>;>

The Email address under which the repository administrator can be contacted.
Example: C<Contact cvsmaster@foo.dom;>

=item B<Home E<lt>urlE<gt>;>

The URL under which the repository home can be found.
Alternatively this just can be the URL of the project.
Example: C<Home http://cvs.foo.dom/;>

=item B<Host E<lt>hostnameE<gt>;>

The canonical hostname on which the repository resides.  This should be the
same FQDN which usually is used for SSH connections, etc.
Example: C<Host cvs.foo.dom;>

=item B<Path E<lt>pathE<gt>;>

The filesystem path on the repository host under which the repository resides.
This usually is equal to the C<$CVSROOT> variable.
Example: C<Path /e/foo/cvs;>

=item B<History E<lt>pathE<gt>;>

The filesystem path where the B<OSSP shiela> history file is written to.  Do not
confuse this with the CVS C<history> file. The B<OSSP shiela> history file logs
only B<OSSP shiela> commits and can be used to reconstruct commit operations later.
Example: C<History CVSROOT/shiela.log;>

=item B<Module E<lt>modulepathE<gt> E<lt>modulenameE<gt> { ... };>

This defines a module with the top-level path E<lt>modulepathE<gt>,
i.e., the modules stays under the directory C<$CVSROOT/>I<modulepath>/.
The E<lt>modulenameE<gt> is just a description text for the module.
The access control and logging parameters are controlled by B<Acl> and
B<Log> directives enclosed in the third argument of B<Module>.
Example: C<Module CVSROOT "CVS Administrative Files" { ... };>

=item B<Acl E<lt>filepathE<gt> [!]E<lt>useridE<gt>[:E<lt>groupidE<gt>] [...];>

This defines an access control list for
C<$CVSROOT/>E<lt>modulepathE<gt>/E<lt>filepathE<gt>.  It ensures that a
repository operation to this path can only be done by the specified
users/groups.

The argument E<lt>filepathE<gt> can be either a full path (e.g.
"C<subdir1/subdir2/file>"), or a shell wildcard pattern (e.g.
"C<subdir1/*.c>") or even a regular expression (e.g. "C<m/^[a-z].*\.[ch]/>").
Additionally E<lt>filepathE<gt> can be extended with "C<:>I<branchname>" to
restrict the operation to both a particular path and a branch.

The following arguments describe the user and groups which are allowed (or
disallowed if argument is prefixed with C<!>).  The E<lt>useridE<gt> and
E<lt>groupidE<gt> strings have to correspond to configured users and groups
(see B<User> and B<Group> directives) or can be given as "C<*>" (which means
"any").  So, a specification of "C<foo>" means the user C<foo>, "C<*:bar>"
means any user of group C<bar> and "C<*:*>" means any user of any group.
Similarly, nobody can be expressed as C<!*:*>.

Example: C<Acl foo-src/*:FOO_1_0 *:core !badboy;>

=item B<Log E<lt>filepathE<gt> E<lt>reportidE<gt>:E<lt>targetE<gt> [...];>

This defines a logging operation for
C<$CVSROOT/>E<lt>modulepathE<gt>/E<lt>filepathE<gt>. It produces one or more
logging messages.  The E<lt>reportidE<gt> has to correspond to the defined
reports (see B<Report> directive). To disable logging one can use "C<none>" as
the E<lt>reportidE<gt> (and leave out the ":E<lt>targetE<gt>" part).

The occurrence of the logging message depends how the specified report is
defined (by C<Report>). After it is produced it is send to E<lt>targetE<gt>
which can be either an Email address of the form I<user>C<@>I<domain> or a
filesystem path.

Example: C<Log * mail:foo-cvs@foo.dom file:CVSROOT/commit.log;>

=back

=head2 Logging Configuration

The third configuration block is for the log message creation. The
configuration block has to be of the following structure:

 Logging {
     Reports {
         Report <reportid> {
             Content <contentid> [...];
             [Details <type>:<arg>;]
             [Prefix <string>;]
         };
         [...]
     };
 };

The individual parts of this are:

=over 4

=item B<Report E<lt>reportidE<gt> { ... };>

This defines a report with the identification name E<lt>reportidE<gt> for use
with B<Log> directives. How the report message is constructed is defined with
other directives in its second argument.

=item B<Content E<lt>contentidE<gt> [...];>

This defines the report contents and contents order. That is the contents is
created top to bottom by concatenating one or more content blocks which are
specified by one or more E<lt>contentidE<gt> arguments.

The available content blocks are:
C<title>: a two line title header,
C<rule>: a horizontal rule,
C<header>: a four line repository and user summary header,
C<files>: a table of added/modified/removed/touched files,
C<log>: the log message as types in by the user,
C<summary>: a table summarizing the amount of changes to each file,
and C<details>: commit operation details (depend on B<Details> directive);

Example: C<Content title rule header files log summary rule details;>

=item B<Details E<lt>typeE<gt>:E<lt>argE<gt>;>

This configures how the details (see B<Content> directive) actually look.  The
following type/argument combinations are currently supported: "C<patch:plain>"
(the default) which produces a long details text consisting of concatenated
patching shell commands for reproducing the change; "C<patch:mime>" which produces the same contents as
"C<patch:plain>", but instead of just concatenating the individual scripts,
it encapsulates them into MIME attachments (which is useful when the
E<lt>targetE<gt> of a B<Log> directive is an Email address only); and
"C<url:>I<url>" which produces just an URL per modified file by expanding
"C<%s>" (the file path relative to C<$CVSROOT>), "C<%V>" (the old revision)
and "C<%v>" (the new revision).

Example: C<Details url:http://cvs.foo.dom/cvsweb.cgi?%s&r1=%V&r2=%v;>

=item B<Prefix E<lt>stringE<gt>;>

This configures that every line of the generated report message is
prefixed with E<lt>stringE<gt>.

Example: C<Prefix "  ";>

=back

=head1 EXAMPLE

The following example shows a fictive but reasonable configuration for a
sample FOO project:

 #   override the run-time environment
 Environment {
     Program sendmail /e/foo/sw/bin/sendmail;
     Program cvs      /e/foo/sw/bin/cvs;
     Program diff     /e/foo/sw/bin/diff;
     Program xdelta   /e/foo/sw/bin/xdelta;
     Program uuencode /e/foo/sw/bin/uuencode;
 };

 #   define the project and its users
 Project {
     Tag     FOO;
     Name    "The FOO Project";
     Contact foo@foo.dom;
     Home    http://www.foo.dom/;
     Users {
         User foo  "Mr. Foo"  foo@foo.dom;
         User bar  "Mr. Bar"  bar@bar.dom;
         User quux "Mr. Quux" quux@quux.dom;
     };
     Groups {
         Group core  "FOO Core Team"      { foo };
         Group devel "FOO Developer Team" { bar quux };
     };
 };

 #   define the repository and its modules
 Repository {
     Tag     FOO;
     Name    "FOO CVS Master Repository";
     Contact foo@foo.dom;
     Home    http://cvs.foo.dom/;
     Host    cvs.foo.dom;
     Path    /e/foo/cvs;
     History CVSROOT/shiela.log;
     Modules {
         Module CVSROOT "CVS Administrative Files" {
             Acl passwd  *:core;
             Acl modules *:core *:devel;
             Acl *       *:core;
             Log passwd  none;
             Log modules mail.patch:foo-cvs@foo.dom file:CVSROOT/commit.log;
             Log *       mail.patch:foo-core@foo.dom;
         };
         Module foo-adm "FOO Administration" {
             Acl * *:core;
             Log * mail.patch:foo-core@foo.dom file:CVSROOT/commit.log;
         };
         Module foo-src "FOO Source" {
             Acl *:VENDOR  foo;
             Acl *:FOO_1_0 *:core;
             Acl *         *:core *:devel;
             Log *:VENDOR  mail.url:foo-cvs@foo.dom file:CVSROOT/commit.log;
             Log *         mail.url:foo-cvs@foo.dom file:CVSROOT/commit.log;
         };
     };
 };

 #   define the logging details
 Logging {
     Reports {
         Report mail.patch {
             Prefix "  ";
             Content title rule header files log summary rule details;
             Details patch:mime;
         };
         Report mail.url {
             Prefix "  ";
             Content title rule header files log summary rule details;
             Details url:http://cvs.foo.dom/cvsweb.cgi/%s?r1=%V&r2=%v;
         };
         Report file {
             Content rule file header files log summary;
         };
     };
 };

=head1 HISTORY

There were the scripts C<log_accum.pl> and C<commit_prep.pl> (originally
written by David Hampton E<lt>hampton@cisco.comE<gt> and Greg A. Woods
E<lt>woods@planix.comE<gt>) and the script C<cvs_acls.pl> (originally
written by David G. Grubbs E<lt>dgg@ksr.comE<gt>), as distributed
with the official CVS version. These scripts over the years were
enhanced and adjusted by lots of people for various free software
projects. For instance Peter Wemm E<lt>peter@freebsd.orgE<gt> derived
variants of these scripts for the FreeBSD project, Roy Fielding
E<lt>fielding@apache.orgE<gt> did a similar job for the Apache webserver
project and Ralf S. Engelschall E<lt>rse@engelschall.comE<gt> did it for
the initial CVS repository of the OpenSSL project.

But for the OSSP project Ralf S. Engelschall
E<lt>rse@engelschall.comE<gt> wanted a solution which was cleaned up
from the ground and which both is more easily to integrate into CVS
and uses the features of the latest CVS versions (especially those of
the enhanced CVS variant from him). So in April 2000 he decided to
rewrite the functionality of C<log_accum.pl>, C<commit_prep.pl> and
C<cvs_acls.pl> from scratch. The result is B<OSSP shiela>.

The name B<OSSP shiela> was chosen just by coincidence and has no
related meaning. It was just that while the program was written,
a code-name was needed. And because Engelschall's first baby was
forthcoming and Ralf and Daniela Engelschall reviewed lots of names, one
of the names Ralf liked was B<Shiela>. So the code-name became B<OSSP
shiela> and as it is often with code-names, they remain forever... ;)

=head1 LOCATIONS

=over 4

=item B<http://www.ossp.org/pkg/tool/shiela/>

Here you can find the official B<OSSP shiela> homepage.

=item B<http://cvs.ossp.org/pkg/tool/shiela/>

Here you can find the latest B<OSSP shiela> development sources.

=item B<ftp://ftp.ossp.org/pkg/tool/shiela/>

Here you can find the latest B<OSSP shiela> release versions as
distribution tarballs.

=back

=head1 SEE ALSO

cvs(1).

=head1 AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut