=head1 NAME

Configuration -- Configuration for ClearCase::Wrapper::MGi

=head1 SYNOPSIS

Four methods, to configure different aspects:

=over 4

=item C<##:BranchOff: root> in the config spec

=item .clearcase_profile.pl

=item environment variables

=item variables in the configuration modules

=back

=head1 DESCRIPTION

The I<extra> directory contains files which can be used to configure
the wrapper for specific needs, either on a site on a user basis.

=head2 VobPathConv.pm

I<VobPathConv.pm> (and its pod file) does however not require any
configuration and may be used as such. I may even consider to extract
it and publish it as a separate package in its own, albeit modest,
right.

It offers functions to convert paths from Windows to Unix, using the registry
to map the tags in associated regions.

It must be installed in the C<@INC> path as C<ClearCase::VobPathConv>.

=head2 ForceLock

The remaining files are mostly concerned with locking and unlocking label
types owned by other people (colleagues, members of the same group, vob
owner...).

The lack of such an ability is considered a bug in ClearCase, and is the
object of an RFE (currently rejected...). It defeats the use of locking in
general.

The installer must select the solution best adapted to her case,
possibly edit a few fields appropriate to her environment, and copy
the suitable file by hand to the parl lib/site_perl directory.

I<ForceLockSudo.pm> implements the simplest, safest and most efficient
solution, from unix. As its alternatives, dealing with cases in which
this superior solution could not be used, it is meant to be installed
in the C<@INC> path, under a ClearCase directory, and accessed via an
environment variable

  FORCELOCK=ClearCase::ForceLockSudo

This is so its use would not penalize functions which do not require locking.
Two other versions are provided for now, one for unix, and one for Windows
(and cygwin):

  FORCELOCK=ClearCase::ForceLockUnix #Unix
  FORCELOCK=ClearCase::ForceLock     #Windows

These can be used as examples or a templates. They require some customization.
The two latter build upon I<locklbtype>, a standalone script, to be installed
suid enabled, owned by an account, which is itself authorized in the ssh
configurations of the respective vob owners of all vobs in the local region,
to run locking commands. It acts as a switch, allowing to simplify the
maintainance of the I<~/.ssh/authorized_keys> files.

The customization it requires is mostly the name of the host running an sshd
daemon which it will use. One needs to avoid using I<localhost> here, so that
different host keys do not overwrite each other in the I<~/.ssh/known_hosts>
files.

One may also set the name of the log used to save the identity of the
unlocking users (for lock events, this is saved in a comment of the locks).
The paths to ssh and cleartool are likely to be satisfying.

In order to use this script, you need to define a pair of functions, for
locking and unlocking.

The unix version of the I<ClearCase::ForceLock> module, is meant to
invoke locklbtype via a system call, therefore using the suid bit
mechanism offered by unix shells.  The only customization is the path
to the locklbtype utility.

In a Windows environment, the related module fills the same role, but
invokes the suid script on a unix host, via ssh.
As perl is found in a vob on my unix environment, I need to customize
a view tag in addition to the host name and the path to the script.

Ssh is accessed with the Net::SSH::Perl module.

It depends on a long list of modules, which I could successfully
install on:
I<cygwin 1.7 / perl 5.10 / libgmp-devel 4.3.1-1, libssh2, pari-gp 2.3.5>
and on I<Windows Vista / Strawberry perl 5.12 / GMP-4.1.2>:

  Digest-SHA1-2.1
  Digest-HMAC-1.01
  Class-ErrorHandler-0.01
  Convert-ASN1-0.22
  Crypt-CBC-2.30
  Crypt-DES-2.05
  Crypt-Blowfish-2.10
  Crypt-DES_EDE3-0.01
  Convert-PEM-0.07
  Data-Buffer-0.04
  Class-Loader-2.03
  Convert-ASCII-Armour-1.4
  Digest-MD2-2.03
  Sort-Versions-1.5
  Tie-EncryptedHash-1.24
  Digest-BubbleBabble-0.01
  String-CRC32-1.4
  Math::GMP-2.05
  Math::BigInt::GMP-1.24
  Math::BigInt-1.89
  Net::SSH::Perl-1.34

On cygwin, I had in addition to install:

  Crypt-DH-0.06
  Crypt-DSA-0.14
  Crypt-IDEA-1.08
  Math-Pari-2.01080604
  Crypt-Random-1.25
  Crypt-Primes-0.50
  Crypt-RSA-1.98

Note that these are just the versions I use, and which work for me.
I cannot claim that this list is a minimal requirement.

=head2 .clearcase_profile.pl

An example of I<.clearcase_profile.pl> sets the ipc mode for all
commands apart for setview (unavailable then, assuming the wrapper
itself is used from a vob).

An other setting for this file is:

  $ClearCase::Wrapper::MGi::global = 1;

This setting drives I<mklbtype> and I<mkbrtype> to create I<global>
types (including the metadata types) in vobs having an admin vob.

This used to be the default with I<ClearCase::Wrapper::DSB>.

=head2 environment variables

Currently, only one such variable (see earlier):

  FORCELOCK
