/ 
ClearCase-Wrapper-MGi-1.00
River stage zero No dependents
/ Configuration

NAME

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

SYNOPSIS

Four methods, to configure different aspects:

##:BranchOff: root in the config spec
.clearcase_profile.pl
environment variables
variables in the configuration modules

DESCRIPTION

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

The features described here are not enabled by default.

One functionality is highly experimental (the FSCBROKER environment variable): fixing the layout of source containers for elements of text_file and derivate types, in conjunction with the BranchOff mechanism

BranchOff

The BranchOff mechanism is one of the two driving forces of this wrapper (the other one being incremental type families).

The intention is to make it possible to always branch off, when checking out a version not already on a branch one created oneself; this without ending up cascading 'forever', i.e. until meeting system limits.

The setup is simple, and per view. Start your config spec with a meta-comment such as:

##:BranchOff: root

The effect will be to interpret mkbranch directives (in the config spec) as injonctions to branch off the root of the version tree for every element (usually /main/0).

The relation to the predecessor version is not lost: it is reestablished with a Merge hyperlink.

As this might result in 'bloated' source containers (in fact a very minor concern, even with certain advantages), an additional, optional setup may be considered: see below.

fixsrccnt, FixSrcCont.pm, FSCbrokerSuDo, FSCbrokerSsh

These files implement the experimental feature: fix source containers.

The rationale is documented in:

http://code.google.com/p/clearcase-cpan/wiki/TypeMgr

These files are not installed by make install, and are largely provided as templates for you to configure according to yourown environment.

fixsrccnt

This should be installed in a path accessible from every client, possibly in a vob. The path to perl is the only part I changed myself.

FixSrcCont.pm

This must be installed as ClearCase::FixSrcCont in a path in $INC.

Note that installing the file (e.g. for one user) is not enough to enable its use (e.g. for others).

Remember to set there the path to the previous script, unless the default is suitable (unlikely since host local):

my $fxsc = '/usr/local/bin/fixsrccnt';

FSCbrokerSuDo and/or FSCbrokerSsh

These two scripts implement alternatives to make it possible to run fixsrccnt as vob owner, for every possible argument (hence potentially multiple vob owner accounts).

The sudo alternative is preferred on UNIX, but the ssh one is needed from Windows or Cygwin (note: that the current implementation is restricted to UNIX vob servers!)

Install in a path reachable from every client, and setuid to an account trusted by every vob server account in the appropriate way (i.e. using sudo, this may be restricted to using fixsrccnt but in a passwordless way).

Adjust the paths to perl and to fixsrccnt.

In addition, check the path to sudo for FSCbrokerSuDo, which uses the Sudo CPAN package (which you have to install).

For FSCbrokerSsh, the $sshhost must be set. The template also assumes an installation in a vob, hence uses a $view. Otherwise, it uses the same Net::SSH::Perl CPAN package as does ForceLock (see below).

To enable the functionality, you must select the variant of the script suitable for your system, and set the environment variable accordingly:

FSCBROKER=ClearCase::FSCbrokerSuDo

VobPathConv.pm

VobPathConv.pm (and its pod file) does 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 @INC path as ClearCase::VobPathConv.

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(s) best adapted to her case, possibly edit a few fields appropriate to her environment, and copy the suitable file by hand to the lib/site_perl directory.

Users must pick up these configurations with environment variables, e.g. setting them in their ~/.clearcase_profile.pl file

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 @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 locklbtype, a standalone script, to be installed suid enabled, owned by an account, which is itself authorized in the 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 authorization setup.

Two variants are proposed: one using ssh, the other using sudo. Only the most suitable one needs to be installed, as locklbtype. The appropriate setup will have to be performed respectively in the vob owner accounts' ~/.ssh/authorized_keys files, or in the host based or system-wide /etc/sudoers file.

Both variants require a minimal customization.

For ssh, one needs to set the name of the host running an sshd daemon Note that one needs to avoid using localhost here, so that different host keys do not overwrite each other in the ~/.ssh/known_hosts files.

For both, 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 or sudo, cleartool and perl are likely to be satisfying.

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

The unix version of the 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: cygwin 1.7 / perl 5.10 / libgmp-devel 4.3.1-1, libssh2, pari-gp 2.3.5 and on 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.

.clearcase_profile.pl

This file is meant to be found in the user home directory. It is common to all possible wrappers derived from ClearCase::Wrapper. It may be symlinked from a shared version, for sitewise configuration.

An example of .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 mklbtype and mkbrtype to create global types (including the metadata types) in vobs having an admin vob.

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

Next possible setting:

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

If this is set, the baseline type is locked in the end of a rollout. Conversely, a next rollout is aborted if the baselin is found unlocked on entry, in order to prevent possible collisions of independent rollouts. This would be the default if locking/unlocking by group members was supported natively by ClearCase, instead of depending on user configuration.

Note that one might e.g. add there code such as:

umask(002);

This ensures that under cleartool (from the wrapper), group members are granted write access e.g. to directory elements being created.

The example provided also sets an environment variable (see below).

environment variables

Four variables to consider (see earlier for the two first):

FORCELOCK
FSCBROKER
CLEARCASE_TAB_SIZE: affects the annotate format (default: 2)
CCMGI_ANNF: annotate format
CCMGI_ANNL: length of the prefix in the annotate format
  (before the actual file contents)

The default annotate format is:

%Sd %25.-25Vn %-9.9u,|,%Sd %25.-25Vn %-9.9u

This means: a short date, a 25 chars right aligned, possibly truncated field for the version specification, a 9 chars left aligned field for the author. The same format is used for elisions as for additions.

Its corresponding prefix length is: 49 (10 for the date, 25 for the version, 9 for the id, 2 for space separators, and 3 for the deletion marker--including spaces).

This prefix is used to compute the beginning of the text upon which to apply regexps in case of using the -grep option of annotate.