*** /dev/null Sat Nov 23 02:19:40 2024
--- - Sat Nov 23 02:19:51 2024
***************
*** 0 ****
--- 1,502 ----
+ ##
+ ## Shiela - CVS Access Control and Logging Facility
+ ## Copyright (c) 2000 Ralf S. Engelschall <rse@engelschall.com>
+ ##
+ ## This file is part of Shiela, an access control and logging
+ ## facility for Concurrent Versions System (CVS) repositories
+ ## which can be found at http://www.ossp.org/pkg/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: Shiela manual page (syntax: POD)
+ ##
+
+ =pod
+
+ =head1 NAME
+
+ B<Shiela> - Access Control and Logging Facility for CVS
+
+ =head1 VERSION
+
+ B<OSSP Shiela> 0.9.0 (18-Jun-2000)
+
+ =head1 DESCRIPTION
+
+ B<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<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<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<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<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 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<Shiela> history file is written to. Do not
+ confuse this with the CVS C<history> file. The B<Shiela> history file logs
+ only B<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.
+ Similarily, 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 occurance 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<diff:plain>"
+ (the default) which produces a long details text consisting of concatenated
+ "C<cvs diff>" outputs; "C<diff:mime>" which produces the same contents as
+ "C<diff:plain>", but instead of just concatenating the individual difference
+ texts, 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
+
+ =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 {
+ CVS <path>;
+ Sendmail <path>;
+ };
+
+ The individual parts of this are:
+
+ =over 4
+
+ =item B<CVS E<lt>pathE<gt>;>
+
+ This overrides the path to the CVS executable. Per default B<Shiela>
+ determines this automatically through the inherited C<$PATH> variable.
+ Use this either if you have CVS not in C<$PATH> or if you have multiple
+ CVS instances installed.
+
+ =item B<Sendmail E<lt>pathE<gt>;>
+
+ This overrides the path to the Sendmail executable. Per default
+ B<Shiela> determines this automatically through the inherited C<$PATH>
+ variable. Use this either if you have Sendmail not in C<$PATH> or if you
+ have multiple Sendmail instances installed.
+
+ =back
+
+ =head1 EXAMPLE
+
+ The following example shows a fictive but reasonable configuration for a
+ sample FOO project:
+
+ # 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.diff:foo-cvs@foo.dom file:CVSROOT/commit.log;
+ Log * mail.diff:foo-core@foo.dom;
+ };
+ Module foo-adm "FOO Administration" {
+ Acl * *:core;
+ Log * mail.diff: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.diff {
+ Prefix " ";
+ Content title rule header files log summary rule details;
+ Details diff: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;
+ };
+ };
+ };
+
+ # override the run-time environment
+ Environment {
+ CVS /e/foo/sw/bin/cvs;
+ Sendmail /e/foo/sw/bin/sendmail;
+ };
+
+ =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 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 OSSP). 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<Shiela>.
+
+ The name B<Shiela> was choosen 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<Shiela> and as it is
+ often with code-names, they remain forever... ;)
+
+ =head1 LOCATIONS
+
+ =over 4
+
+ =item B<http://www.ossp.org/pkg/shiela/>
+
+ Here you can find the official B<Shiela> homepage.
+
+ =item B<ftp://ftp.ossp.org/pkg/shiela/>
+
+ Here you can find the latest B<Shiela> release versions as
+ distribution tarballs.
+
+ =item B<:pserver:anonymous@cvs.ossp.org:/e/ossp/cvs>, module B<shiela>
+
+ Here you can find the latest B<Shiela> development version.
+
+ =back
+
+ =head1 AUTHOR
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+ =cut
+
|
