Index: ossp-pkg/shiela/shiela.pod RCS File: /v/ossp/cvs/ossp-pkg/shiela/shiela.pod,v co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/shiela/shiela.pod,v' | diff -u /dev/null - -L'ossp-pkg/shiela/shiela.pod' 2>/dev/null --- ossp-pkg/shiela/shiela.pod +++ - 2024-05-17 04:18:26.269024421 +0200 @@ -0,0 +1,502 @@ +## +## Shiela - CVS Access Control and Logging Facility +## Copyright (c) 2000 Ralf S. Engelschall +## +## 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 . +## +## shiela.pod: Shiela manual page (syntax: POD) +## + +=pod + +=head1 NAME + +B - Access Control and Logging Facility for CVS + +=head1 VERSION + +B 0.9.0 (18-Jun-2000) + +=head1 DESCRIPTION + +B is an access control and logging facility for use with the +I (CVS). It is intended to be hooked +into CVS's processing through the C<$CVSROOT/CVSROOT/>IC +callbacks. This way B 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 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 from the +users environment or the one implicitly provided by CVS because of the +scope of C 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 command line option B<--config>. + +This file uses a C-style syntax which is described by the following +grammar rooted at I: + + 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'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 ; + Name ; + Contact ; + Home ; + Users { + User ; + [...] + }; + [Groups { + Group { [...] }; + [...] + };] + }; + +The individual parts of this are: + +=over 4 + +=item BstringE;> + +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 + +=item BstringE;> + +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 + +=item BemailE;> + +The Email address under which the project can be contacted. +Example: C + +=item BurlE;> + +The URL under which the project home can be found. +Example: C + +=item BuseridE EusernameE EemailE;> + +A user/member of the project. The EuseridE has correspond to a Unix +user id and should match the entry in the C database. The EusernameE +is the real name of the user and EemailE 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 + +=item BgroupidE EgroupnameE { EuseridE [...] };> + +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 EgroupidE is a single word, EgroupnameE is +a description text of the group and the EuseridE arguments have to +correspond to users which are configured with B directives. +Example: C + +=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 ; + Name ; + Contact ; + Home ; + Host ; + Path ; + History ; + Modules { + Module { + [Acl [!][:] [...];] + [...] + [Log : [...];] + [...] + }; + [...] + }; + }; + +The individual parts of this are: + +=over 4 + +=item BstringE;> + +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 + +=item BstringE;> + +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 + +=item BemailE;> + +The Email address under which the repository administrator can be contacted. +Example: C + +=item BurlE;> + +The URL under which the repository home can be found. +Alternatively this just can be the URL of the project. +Example: C + +=item BhostnameE;> + +The canonical hostname on which the repository resides. This should be the +same FQDN which usually is used for SSH connections, etc. +Example: C + +=item BpathE;> + +The filesystem path on the repository host under which the repository resides. +This usually is equal to the C<$CVSROOT> variable. +Example: C + +=item BpathE;> + +The filesystem path where the B history file is written to. Do not +confuse this with the CVS C file. The B history file logs +only B commits and can be used to reconstruct commit operations later. +Example: C + +=item BmodulepathE EmodulenameE { ... };> + +This defines a module with the top-level path EmodulepathE, +i.e., the modules stays under the directory C<$CVSROOT/>I/. +The EmodulenameE is just a description text for the module. +The access control and logging parameters are controlled by B and +B directives enclosed in the third argument of B. +Example: C + +=item BfilepathE [!]EuseridE[:EgroupidE] [...];> + +This defines an access control list for +C<$CVSROOT/>EmodulepathE/EfilepathE. It ensures that a +repository operation to this path can only be done by the specified +users/groups. + +The argument EfilepathE can be either a full path (e.g. +"C"), or a shell wildcard pattern (e.g. +"C") or even a regular expression (e.g. "C"). +Additionally EfilepathE can be extended with "C<:>I" 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 EuseridE and +EgroupidE strings have to correspond to configured users and groups +(see B and B directives) or can be given as "C<*>" (which means +"any"). So, a specification of "C" means the user C, "C<*:bar>" +means any user of group C and "C<*:*>" means any user of any group. +Similarily, nobody can be expressed as C. + +Example: C + +=item BfilepathE EreportidE:EtargetE [...];> + +This defines a logging operation for +C<$CVSROOT/>EmodulepathE/EfilepathE. It produces one or more +logging messages. The EreportidE has to correspond to the defined +reports (see B directive). To disable logging one can use "C" as +the EreportidE (and leave out the ":EtargetE" part). + +The occurance of the logging message depends how the specified report is +defined (by C). After it is produced it is send to EtargetE +which can be either an Email address of the form IC<@>I or a +filesystem path. + +Example: C + +=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 { + Content [...]; + [Details :;] + [Prefix ;] + }; + [...] + }; + }; + +The individual parts of this are: + +=over 4 + +=item BreportidE { ... };> + +This defines a report with the identification name EreportidE for use +with B directives. How the report message is constructed is defined with +other directives in its second argument. + +=item BcontentidE [...];> + +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 EcontentidE arguments. + +The available content blocks are: +C: 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 +