Linux Tutorial: Clearcase Server Installation

Clearcase Server Intro:

Linux is an excellent choice for an IBM Rational Clearcase Server installation. A Unix/Linux platform is the universal Clearcase server which clients of all platforms can connect. This is NOT true if Microsoft Windows is chosen as your Clearcase Server platform. If Microsoft Windows is chosen as your Clearcase server platform, then only Microsoft Windows clients may connect to the server.

The Clearcase Server installation is very specific as to which versions of Linux are supported. Currently only Red Hat Enterprise Linux and SuSE Enterprise Linux are supported. The installation PERL scripts check the contents of /etc/redhat-release or /etc/SuSE-release for the appropriate contents. The installation is so specific and tied to the specific kernel of that release. I attempted to install on versions much like the intended release but differences in the kernel data structures being passed to the Clearcase mvfs loadable module prevented a sucessful install. I recommend that one avoid pain by installing on the approved release of Linux.

Dynamic views: Dynamic views employ the Clearcase MVFS file system which allow users to imediately view changes made by other users once files (or directories) are checked in. This is the prefered method of using Clearcase and the installation detailed in this tutorial.

Snapshot views: These are used by ClearCase LT and are created by Clearcase by copying directories and files to the user's local platform. Changes can not be viewed until an update is performed on the local files.

Clearcase Server Installation:

Preparation:
As user "root"

* Requires RPM packages gcc, glibc-devel, ncurses-devel, kernel-source (for 2.4.XX kernels).
RHEL Notes:
o RHEL3: Install RPM kernel-source. (See: /usr/src/linux-2.4.XXX)
o RHEL4: Clearcase 6.0 comes with a precompiled loadable module for RHEL4 so no compiling of kernel modules is required. RHEL4 also includes source (See: /usr/src/kernles/2.6.XXX) with the binary release of the kernel.

SuSE Notes:
o For SuSE, there are two kernel-source RPMs. One RPM resides on the "Source" DVD-2 and the other resides on the "Installation" DVD-1. Use the kernel-source RPM found on the "Installation" DVD-1. This one will register in the RPM database and creates the directories expected by the Clearcase installation program.
Check with the command: rpm -q kernel-source
o The SuSE kernel-source RPM will not produce a ".config" file for the kernel compilation.
Produce this by: zcat /proc/config.gz > /usr/src/linux/.config
* Prepare kernel source: (not required for RHEL3, RHEL4)

cd /usr/src/linux
make oldconfig
make clean
make bzimage


Test to see if kernel source compiles but do not install. (not necessary, just a test)

* Create modules target directory: mkdir /lib/modules/fs
* Edit /etc/services and add the following:

albd 371/udp


* Create user "vobadm" in group "devel" (use group appropriate for your environment)
* cd /usr
* Create release area: mkdir clearcase_rls
This directory is used to unpack the Clearcase tar archive and for applying patches to this area. It can then be an exported file system for use in client Clearcase installations so the installation files and patches do not have to be redeployed on each and every client.
* chown vobadm:devel clearcase_rls

Installation:
As user "vobadm"

* Use working directory for Clearcase server release:
cd /usr/clearcase_rls
(Discretionary. i.e. /opt/rational/clearcase_rls or anything you want.)
* Copy Clearcase server software and patches from CD:
cp /media/cdrecorder/* .
* chmod +w *
* uncompress C54UDNA.tar.Z
Note:
o This tar archive is good for installing Clearcase server and Clearcase client. It is the options chosen during installation and configuration which differentiate a server installation from a client installation.
o Red Hat: uncompress command is included in the "ncompress" RPM
o SuSE: uncompress command is included in the "gzip" RPM
* tar xf C54UDNA.tar
* Create patches directory: (if it doesn't exist)
mkdir 2003.06.00/rhat_x86/clearcase/patches
* cp clearcase_p2003.06.00-28.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
* cp clearcase_p2003.06.00-29.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
* Extract patches:
o tar xzf clearcase_p2003.06.00-28.rhat_x86.tar.gz
o tar xzf clearcase_p2003.06.00-29.rhat_x86.tar.gz
* Apply patches to release area:
o cd clearcase_p2003.06.00-28/clearcase/install
o ./apply_patch
o cd /usr/clearcase_rls/2003.06.00/rhat_x86/clearcase/patches/clearcase_p2003.06.00-29/clearcase/install
o ./apply_patch
* Configure installation:
o cd /usr/clearcase_rls/2003.06.00/rhat_x86/clearcase/install
o service ypbind stop
o ./site_prep
o service ypbind start

Interaction with install program site_prep:

Site default Clearcase license host: [Unknown] ccserver
Site default Clearcase registry host: [Unknown] ccserver
Site default Clearcase registry data backup host: [Unknown] ccserver
Site default Clearcase registry region: [Unknown] devel
Would you like to change the existing host data for setuid operation [no]
Would you like ClearCase Remote Administration to be enabled on clients [no]
Port on which Rational Web Platform listens for HTTP requests: [81]
Account name for Rational Web Platform server: [nobody]
Group name for Rational Web Platform server: [nobody]


Note:

* View all the options: site_prep -help
* The region separates MS/Windows and Unix/Linux systems into two identifiable platform types. Different region names have to be chosen for the two platform types. i.e.:
o Unix: dev or unix
o MS/Windows: dev_mswin or mswin

[Potential Pitfall]: Turn off the NIS service "ypbind" if you get the following error:

ERROR: The albd_server is not correctly registered in the services
file of the Network Information database.

This results when the installation expects the services file to be fed by NIS and ignores the /etc/services file you edited and the added port albd/371.

Turn off ypbind:

* RHEL: service ypbind stop
* SuSE: /etc/init.d/ypbind stop

Interaction with install program install_release:

1. Local Install: Install occurs on the local host.
2. Remote Install: Install occurs on a single remote host.
3. Multiple Remote Installs: Install occurs on a set of remote hosts.
4. Local Deinstall: Deinstall occurs on the local host.
Method of installation>> 1

1. Standard: Regular installation, allowing links to this release area.
2. Full-copy: Regular installation, with no links to this release area.
3. Mounted: Host install via mounted or pre-populated
/opt/rational/clearcase or CLEARCASEHOME.
4. Link-only: Host install via a symbolic link to this release-area.
5. Deinstall: Deinstall software from the local installed host.
Model of installation>> 1

[/opt/rational]:
[/usr/clearcase_rls/2003.06.00/rhat_x86]:

1 : ClearCase Minimal Developer Installation
* 2 : ClearCase Server-only Installation
* 3 : ClearCase MultiSite Full Function Installation
* 4 : ClearCase Web Interface Server
* 5 : ClearQuest Integration with Clearcase
6 : ClearDDTS Integration with Clearcase
7 : Clearcase Mainframe Connectors
8 : Clearcase MultiSite Shipping Server-only Installation
* 9 : ClearCase Full Function Installation
a : Select all - Chooses 1 - 9
f : Finish selection
x : Toggle expanded descriptions
r : Reset selections
q : Quit
Selection number(s)>> f

ClearCase License Server Host[ccserver]:
ClearCase Registry Server Host[ccserver]:
ClearCase Registry Backup Host(s)[ccserver]:
ClearCase Registry Region[devel]:
WARNING: Install was unable to find a prebuilt vnode module
for this system. You will have to rebuild your vnode module.

Do you want to rebuild the vnode module when install is
complete (yes, no, quit, help)[yes]:
Default is [/lib/modules/2.6.8-24-default/build]:

Extended VOB support files in the VOB database to grow beyond 2 Gigabytes.
Install this feature? (yes, no, quit)[no]:yes

Port on which Rational Web Platform listens for HTTP requests [81]:
Enter account name for Rational Web Platform use [nobody]:
Enter group name for Rational Web Platform use [nobody]:
Continue installation?(yes, no, quit)[yes]:
Do you want to SPTOP the installation (yes, no, quit, help)[yes]:no

Building /lib/modules/fs/mvfs.o and /lib/modules/fs/vnode.o
See supported kernel modules: /opt/rational/clearcase/etc/conf/linux*
ERROR: /var/adm/rational/clearcase/mvfs/vnode_src
See README.txt

Note:

* An error free install will start the clearcase service.
* Selecting "a : Select all" will select options 1 through 9.
* The region is for a common set of clients. The Unix and Linux systems will be in a separate "region" than the MS/Windows systems. i.e. use devel (unix) and devel_win MS/Windows.
* If installation fails, run again and choose option "4. Local Deinstall".
Then you are ready to perform a fresh install.
* The server installation installs the license server.

[Potential Pitfall]: If the release file is not that expected by the installer, then the installer aborts.

./install_release
ERROR: Unsupported SuSE release.
Aborting install

The following files are scanned by the installer's PERL script /usr/clearcase_rls/2003.06.00/rhat_x86/clearcase/install/Kernel.pl

* Red Hat: /etc/redhat-release
o RHEL4 Server:

Red Hat Enterprise Linux ES release 4 (Nahant)

o RHEL4 Workstation:

Red Hat Enterprise Linux WS release 4 (Nahant)

o RHEW3:

Red Hat Enterprise Linux WS release 3 (Taroon Update 5)

* SuSE: /etc/SuSE-release

Building the kernel modules:

* cd /var/adm/rational/clearcase/mvfs/vnode_src
* Clean/purge old files:
make cleano
* Create kernel config parameter file:
make vnode_param.mk.config
This creates file: vnode_param.mk.config

RATL_EXTRAFLAGS := -DSLES8
LINUX_KERNEL_DIR=/lib/modules/2.6.8-24-default/build
CONFIG_MVFS=y
CONFIG_MVFS_VNODE=m

* make
* make install
* View/verify that kernel modules were created:
o RHEL4 Kernel 2.6: ls -l /lib/modules/2.6.8-24-default/kernel/fs/mvfs/
Result: mvfs.ko vnode.ko
o RHEL3 Kernel 2.4: ls -l /lib/modules/fs
Result: mvfs.o vnode.o

Notes from attempt to install on SuSE Professional Linux 9.3/2:

* First I could not do it. Use an approved release.
* Previous to kernel 2.6.9 the Linux kernel used the macro "EXPORT_SYMBOL_NOVERS()". After Linux kernel 2.6.9, the macro was renamed to "EXPORT_SYMBOL()". (as with SuSE 9.3 and kernel 2.6.11.) This kernel macro "EXPORT_SYMBOL_NOVERS()" is used in the Clearcase source file /var/adm/rational/clearcase/mvfs/vnode_src/mvfs_param.c and thus incompatible. Editing the file only lets you find the next error.
* The argument list uses an argument that is not declared in the kernel header: /var/adm/rational/clearcase/mvfs/vnode_src/mvfs_linux_mvops.c
'wait' undeclared in function mvop_linux_lockctl
err = posix_lock_file(realfp, lock_p, wait);
Solution: Remove argument 'wait'???
* There is now a mismatch in the definition of the data structure cl_timeout. Removing reference to cl_timeout.to_current allows compilation but the kernel will not load the module! I failed.
* Comparison of Linux distributions with their kernel, glibc and gcc releases.
* USE RHEL4 and avoid the pain! (or a clone like Centos or Whitebox)

[Potential Pitfall]: SuSE systems - One of the last steps of the install tries to put the init script in a Red Hat init script directory which does not exist on SuSE. Perform this manually.

ERROR: Unable to copy /var/adm/rational/common/rwp/conf/rwp_shutdown
to /etc/rc.d/init.d/rwp_shutdown


Note: SuSE uses the init directory /etc/init.d/

Cleanup:
If it all fails and you want to wipe your system clean, run install_release again and choose option "4. Local Deinstall" or manually perform a cleanup as follows:

* rm -Rf /lib/modules/2.6.8-24-default/kernel/fs/mvfs/*
or
RHEL3 kernel 2.4.XX:
* rm -Rf /lib/modules/fs/*
* rm -Rf /var/adm/rational
* rm -Rf /opt/rational

Post Install:

As user "root"

* Assign a registry password: /opt/rational/clearcase/bin/rgy_passwd
You will be asked to supply a password.
* Create VOB storage area:
o mkdir /vob
chown vobadm:devel /vob
o mkdir /path-goes-here/vobstore
chown vobadm:devel /path-goes-here/vobstore
o mkdir /path-goes-here/viewstore
chown vobadm:devel /path-goes-here/viewstore
* Export VOB storage areas using NFS:

NFS config file (example): /etc/exports

/path-goes-here/vobstore 192.168.1.0/255.255.255.0(rw)
/path-goes-here/viewstore 192.168.1.0/255.255.255.0(rw)

Note: The directory /vob is an internal mount generated by Clearcase and not an NFS mount.

Pick up NFS exports configuration: exportfs -a
See the YoLinux Systems administration tutorial covering NFS.

As user "vobadm"

* Expand path to include Clearcase commands: (add to .bashrc file)
export PATH=/opt/rational/clearcase/bin:$PATH
* Install license and test:
o cp license.db /var/adm/rational/clearcase/
(Note: This is soft linked to /var/adm/atria/)
o Test with command: clearlicense
IBM/Rational will issue a license based on the hostid or MAC address. These are found by issuing the following commands:
o Host ID: /opt/rational/clearcase/bin/clearlicense -hostid
o Linux Host ID: hostid (not necesarily unique for Linux and thus not usually used.)
o MAC address: ifconfig
* Make a storage location for VOB:
o cleartool mkstgloc -vob -region region-name -host ccserver -hpath /path-goes-here/vobstore -gpath /path-goes-here/vobstore vobstore /path-goes-here/vobstore
o cleartool mkstgloc -view -region region-name -host ccserver -hpath /path-goes-here/viewstore -gpath /path-goes-here/viewstore viewstore /path-goes-here/viewstore
When asked "Advertise existing directory [no]" answer "yes".
* Test Clearcase storage locations: cleartool lsstgloc
This will list the full paths of the "vobstore" and "viewstore" locations.
* Create the VOB:
o cleartool mkvob -region region-name -tag /vob/PROJECT -stgloc vobstore -public
You will be asked to enter the registry password assigned with the rgy_passwd command.
o cleartool mkview -region region-name -tag vobadm_proj -stgloc viewstore
* Mount the VOB: cleartool mount -a
* View VOB info: cleartool -ver
Shows VOB db schema version. The current Clearcase schema version for 2003.06.00 is 54.
* cleartool setview vobadm_proj
* Create main directory:
o Optional - make sub-directories: cleartool mkdir subdir-name
Or import (clearfsimport) as shown below.
o cd /vob/PROJECT
* Show VOBs: cleartool pwv
* Show Views: cleartool lsview
* Show Regions: cleartool lsregion
* Show VOBs: cleartool lsvob
* Show Configspec: cleartool catcs
* Import files and directories:
1. cleartool setview your_view
2. clearfsimport -recurse -identical -preview /source/directory/path/* /vob/PROJECT/path
(Preview option shows what will happen when command executes)
3. clearfsimport -recurse -identical /source/directory/path/* /vob/PROJECT/path
(Perform actual import)
Add option "-follow" to follow symbolic links.

[Potential Pitfall]: The command line option "-identical" should only be used for the initial import and NOT for later revisions as file date differences will force new entries even though the files may be identical.

Cleanup: (Removing VOBs from system)

* cleartool rmvob /path-goes-here/vobstore/PROJECT.vbs
* cleartool rmview -force -tag vobadm_proj

Slocate configuration:

The "slocate" command is run each day to create a database of all files on the system. It ignores NFS mounted file systems (thus Clearcase clients need not worry) but will search your Clearcase server storage areas which have Clearcase file storage names and not the ones you see when in a view. Configure this cron job to ignore Clearcase repositories.

Slocate cron file: /etc/cron.daily/slocate.cron

#!/bin/sh
. /etc/updatedb.conf
renice +19 -p $$ >/dev/null 2>&1
/usr/bin/updatedb

This uses the configuration file /etc/updatedb.conf.

Edit the configuration file: /etc/updatedb.conf

PRUNEFS="sysfs selinuxfs usbdevfs devpts NFS nfs afs sfs proc smbfs cifs autofs auto iso9660 udf mvfs"
PRUNEPATHS="/tmp /usr/tmp /var/tmp /afs /net /sfs /selinux /udev /mnt/floppy /path-goes-here/viewstore /vob /view"
export PRUNEFS
export PRUNEPATHS

Note the addition of mvfs to the file system types to be ignored and /path-goes-here/viewstore, the viewstore directory to be ignored.

ClearCase Web Access: ccweb

Clearcase Web Access uses Linux system authentication which uses md5 encrypted passwords. This requires Clearcase patches 19, 37 and 38 in adition to 28 and 29 as shown in the installation above.

Access via the URL:

* http://clearcase-server-name/ccweb
* https://clearcase-server-name/ccweb

Pam authentication configuration: Clearcase web uses the system PAM login authentication. The configuration is identical to "login". Thus:

cp /etc/pam.d/login /etc/pam.d/clearcase

[Potential Pitfall]: The init service "rwp_startup" (Rational Web Process) may hang on system boot. The last visible message on the screen is "Enabling Swap Space". The system then hangs indefinitely. The only fix is to enter "Interactive Mode" during the boot process by entering the letter "I". Read the boot messages and enter the mode when the oportunity is displayed in the boot messages by entering "I". Accept all init services by pressing the "Enter" key to take the yes [y] default. When presented with the option to launch "rwp_startup", enter the letter "N" for no, and skip this process.

To fix CCWeb and enable it to work, fix the broken link: /opt/rational/common/rwp/conf/include/msweb.conf by creating and linking to the file: /var/adm/rational/clearcase/config/msweb.conf

#
# Licensed Materials - Property of IBM
# Rational ClearCase
# (C) Copyright IBM Corp. 2003, 2004 All Rights Reserved
# US Government Users Restricted Rights -
# Use, duplication or disclosure restricted by GSA ADP Schedule
# Contract with IBM Corp
#

# This is a template for the MultiSite Web Interface configuration file.
# It should not be modified in its installed location.
# Instead, it should be copied to the host's ClearCase config directory
# (Unix: /var/adm/rational/clearcase/config/msweb.conf,
# NT: CCASEHOME\var\config\msweb.conf) and modified there.
#
#
# The following should be added at install time to support mapping the
# MultiSite web interface to the Rational Web Platform. Install should
# substitute the ClearCase home directory for CCASEHOME
#
ScriptAlias /msweb/bin "/opt/rational/clearcase/msweb/bin"
Alias /msweb "/opt/rational/clearcase/msweb"

DirectoryIndex bin/msweb
Options -Indexes


SetEnv LANG C


Thanks to Tech Support at IBM Rational ClearCase for this file.

(msweb refers to a web admin tool for Multisite)

Note, your system requires Java installation and browser plug-in configuration for Java. See YoLinux Mozilla / Firefox web browser Java configuration.

Note: I have been running both the native Apache server which was issued with RHEL4 on port 80 and the Clearcase web server on port 81 with no apparent problems.

Connecting MS/Windows clients:

Steps to support MS/Windows clients:

On Clearcase server:

* Create a region for use by MS/Windows clients: cleartool mkregion -tag devel_win
* Show Regions: cleartool lsregion

There are two methods of exporting the filesystems from the Clearcase server:

1. Export the Clearcase filesystem system using NFS and use an NFS client on the MS/Windows client to mount the exported filesystem. This is fast and free of many MS/Windows authentication hagups.
2. Export the Clearcase filesystem using SAMBA.

2) Use SAMBA to export two shares:

* vobstore
* viewstore

Using MS/Active Directory with "Unix services for Windows" NIS server for authentication, configure the Linux Clearcase server's SAMBA authentication as follows:

File: /etc/krb5.conf

[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log

[libdefaults]
default_realm = win-domain.domain.com
dns_lookup_realm = true
dns_lookup_kdc = true

[realms]
win-domain.domain.com = {
kdc = authserver.win-domain.domain.com:88
admin_server = authserver.win-domain.domain.com:88
}

[kdc]
profile = /var/kerberos/krb5kdc/kdc.conf

[appdefaults]
pam = {
debug = false
ticket_lifetime = 36000
renew_lifetime = 36000
forwardable = true
krb4_convert = false
}


File: /etc/samba/smb.conf

[global]
workgroup = win-domain
server string = clearcase-server Samba Server

printcap name = /etc/printcap
load printers = yes
cups options = raw
log file = /var/log/samba/%m.log
max log size = 50
password server = authserver

socket options = TCP_NODELAY SO_RCVBUF=8192 SO_SNDBUF=8192

dns proxy = yes

# SHare definitions

idmap uid = 16777216-33554431
idmap gid = 16777216-33554431
template shell = /bin/false
realm = win-domain.domain.com
security = ADS
windbind use default domain = no

[printers]
comment = All Printers
path = /var/spool/samba
browsable = no
printable = yes

[vobstore]
path = /path-goes-here/vobstore
writeable = yes
create mask = 0777
force directory mode = 0777
force group = devel

[viewstore]
path = /path-goes-here/viewstore
writeable = yes
create mask = 0777
force directory mode = 0777
force group = devel

[home]
path = /home
writeable = yes
guest ok = no
create mask = 0766
force directory mode = 0766
force group = devel


Intallation:

* siteprep.exe
Choose client install
Create region: devel_win
* setup.exe
* Verify installation from control panel and check settings.
* From "Start" menu: "Rational Software" + "Administration" + "Syncronize region"

Links:

* File corruption by editing with Visual Studio using a view server - Download Microsoft patch.
* IBM/Rational Clearcase-SAMBA interoperational tips

Backup:

To perform a tape backup, unmount the VOBs, stop the Clearcase daemon and backup the "viewstore" and "vobstore" directories.

* cleartool umount -a
* service clearcase stop
(or use the start and stop scripts in /opt/rational/clearacase/etc/)

There is no need to backup the MVFS /vob and /view as this is just a Clearcase view of data in the "viewstore" and "vobstore" directories.

Links:

* IBM/Rational ClearCase Install Guide for Linux