ossp-pkg/shiela/shiela-install.pod
##
## OSSP shiela - CVS Access Control and Logging Facility
## Copyright (c) 2000-2006 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2000-2006 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-install.pod: install manual page (syntax: POD)
##
=pod
=head1 NAME
B<shiela-install> - OSSP shiela installation utility
=head1 VERSION
B<OSSP shiela>
=head1 DESCRIPTION
B<OSSP shiela> is an access control and logging facility for use with
the I<Concurrent Versions System> (CVS). Read shiela(1) for more
details about B<OSSP shiela> itself. This B<shiela-install> program is a
small utility intended to help in adding B<OSSP shiela> to an existing CVS
repository for testing or production purposes.
=head1 INSTALLATION: MANUALLY
B<OSSP shiela> can be installed and activated in a CVS repository either
manually or via the B<shiela-install> program. The manual steps would
be:
=over 4
=item B<1.>
make sure that you are using CVS version 1.12.6 or higher. Older
versions are no longer supported due to the new I<xxxx>C<info> hooking
(C<UseNewInfoFmtStrings=yes>) which is a mandatory configuration for
B<OSSP shiela>.
=item B<2.>
checkout a working copy of the C<CVSROOT> module from your repository.
=item B<3.>
make sure the file C<$CVSROOT/CVSROOT/config>
contains the directive ``C<UseNewInfoFmtStrings=yes>''.
=item B<4.>
create the files C<$CVSROOT/CVSROOT/shiela>,
C<$CVSROOT/CVSROOT/shiela.cfg> and C<$CVSROOT/CVSROOT/shiela.msg>
in this directory and list these three files in
C<$CVSROOT/CVSROOT/checkoutlist> (so CVS automatically checks them
out).
=item B<5.>
add to C<$CVSROOT/CVSROOT/rcsinfo> (the hook for providing log
messages): ``C<ALL $CVSROOT/CVSROOT/shiela.msg>''.
=item B<6.>
add to C<$CVSROOT/CVSROOT/taginfo> (the hook for checking tag
operations): ``C<ALL $CVSROOT/CVSROOT/shiela --hook=taginfo %t %o %p %{sv}>''.
=item B<7.>
add to C<$CVSROOT/CVSROOT/importinfo> (the hook for checking import
operations): ``C<ALL $CVSROOT/CVSROOT/shiela --hook=importinfo>''. This
assumes that you are using a CVS version with RSE patches applied (see
below). If you use a stock CVS version, you have to skip this step
and live with the fact that `C<cvs import>' commands cannot be access
controlled by B<OSSP shiela> (because then this hook does not exists at
all).
=item B<8.>
add to C<$CVSROOT/CVSROOT/admininfo> (the hook for checking admin
operations): ``C<ALL $CVSROOT/CVSROOT/shiela --hook=admininfo>''. This
requires that you are using a CVS version with RSE patches applied (see
below). If you use a stock CVS version, you have to skip this step
and life with the fact that `C<cvs admin>' commands cannot be access
controlled by B<OSSP shiela> (because then this hook does not exists at
all).
=item B<9.>
add to C<$CVSROOT/CVSROOT/commitinfo> (the hook for checking commit
operations): ``C<ALL $CVSROOT/CVSROOT/shiela --hook=commitinfo %r/%p %s>''.
=item B<10.>
add to C<$CVSROOT/CVSROOT/verifymsg> (the hook for post-processing log
messages): ``C<DEFAULT $CVSROOT/CVSROOT/shiela --hook=verifymsg %l>''.
=item B<11.>
add to C<$CVSROOT/CVSROOT/loginfo> (the hook for performing logging):
``C<ALL $CVSROOT/CVSROOT/shiela --hook=loginfo %p %{sVvto}>''.
This requires that you use a CVS version with RSE patches
applied (see below). If you use a stock CVS version, use ``C<ALL
$CVSROOT/CVSROOT/shiela --hook=loginfo %p %{sVv}>'' instead and live with
the fact that B<OSSP shiela>'s run-time efficiency is slightly decreased
and branch recognition might be less correct (because B<OSSP shiela> has
to determine details the hard way which CVS already would know easily).
=item B<12.>
edit C<$CVSROOT/CVSROOT/shiela.cfg> to fit your repository and
project situation. For details, see the description under
B<CONFIGURATION> in shiela(1).
=item B<13.>
finally commit all modifications at once.
=back
=head1 INSTALLATION: AUTOMATICALLY
For convenience reasons one can alternatively use the interactive
B<shiela-install> utility, which perform the above steps automatically
and especially creates initial C<shiela.cfg> and C<shiela.msg> files.
Just run C<shiela-install> and answer the questions.
For convenience reasons (while testing) one can also override the
default value of a question by using C<variable=value> on the
B<shiela-install> command line. For instance, ``C<shiela-install
repos_path=/tmp/cvs>'' sets the default path for the question about the
CVS repository to C</tmp/cvs>. Additionally one can specify C<batch=yes>
which runs B<shiela-install> non-interactively.
=head1 CVS INTERNAL PROCESSING
The administrative files in C<$CVSROOT/CVSROOT/> are consulted by CVS
internally in dependency of the used F<cvs> command. For your reference,
here are the processing steps CVS performs and into which B<OSSP shiela>
hooks into:
=over 1
=item On "C<cvs checkout>":
1. CVSROOT/config (general configuration)
2. CVSROOT/modules (determine module names)
3. CVSROOT/cvswrappers (file handling)
4. CVSROOT/history (logging of the commit step)
=item On "C<cvs commit>":
1. CVSROOT/config (general configuration)
2. CVSROOT/modules (determine module names)
3. CVSROOT/commitinfo (access control)
4. CVSROOT/rcsinfo (log message template)
5. CVSROOT/editinfo (run the log message editor)
6. CVSROOT/verifymsg (evaluate/adjust log message after editing)
7. CVSROOT/cvswrappers (file handling)
8. CVSROOT/loginfo (extra logging after commit)
9. CVSROOT/history (logging of the commit step)
=item On "C<cvs import>":
1. CVSROOT/config (general configuration)
2. CVSROOT/modules (determine module names)
3. CVSROOT/importinfo (access control)
4. CVSROOT/rcsinfo (log message template)
5. CVSROOT/editinfo (run the log message editor)
6. CVSROOT/verifymsg (evaluate/adjust log message after editing)
7. CVSROOT/cvswrappers (file handling)
8. CVSROOT/loginfo (extra logging after commit)
9. CVSROOT/history (logging of the commit step)
=item On "C<cvs tag>" (CVS with RSE patches only):
1. CVSROOT/config (general configuration)
2. CVSROOT/modules (determine module names)
3. CVSROOT/taginfo (access control and tag evaluation)
4. CVSROOT/history (logging of the tag step)
=item On "C<cvs admin>" (CVS with RSE patches only):
1. CVSROOT/config (general configuration)
2. CVSROOT/modules (determine module names)
3. CVSROOT/admininfo (access control)
4. CVSROOT/history (logging of the admin step)
=back
=head1 CVS WITH RSE PATCHES APPLIED
The stock CVS vendor version you can find on http://www.cvshome.org/.
Although B<OSSP shiela> works fine with just this version, it
unfortunately lacks some important features which make B<OSSP shiela>'s
processing less strong. For instance, the stock CVS does not allow
B<OSSP shiela> to apply access control to the "C<cvs tag>" and "C<cvs
admin>" commands. Hence Ralf S. Engelschall extended CVS with those
features (and more) and maintains a patch set in the "cvs" package of
his B<OpenPKG> project (http://www.openpkg.org/). You can find the latest
patch set under http://cvs.openpkg.org/openpkg-src/cvs/cvs.patches.rse
=head1 SEE ALSO
cvs(1), shiela(1).
=head1 AUTHOR
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
=cut
