Yolinux.com Tutorial

IBM/Rational Clearcase Client 6.0 Installation on Linux

This tutorial is for software developers using IBM/Rational Clearcase for change management (CM) on Linux. Unlike many of the text file based CM systems like RCS and CVS, Clearcase used its Multi Version File System (MVFS) to hold various revisions of a file and control locking of files checked out to a developer.

This tutorial covers the installation and configuration of Cleacase client (6.0) on Linux (Red Hat Enterprise Linux 4 [RHEL4] or 3 [RHEL3]) connecting to a Clearcase server. This tutorial covers the client installation only. IBM states that the Clearcase client is only supported on the Red Hat Linux or SuSE "Enterprise" distributions but the only thing limiting you to this distribution is the kernel version, files, directory structure and the version of gcc. The directory structure can be duplicated and the version of the kernel, C libraries and compiler can be matched to that used on Red Hat "Enterprise" or use a RHEL clone such as CentOS or WhiteBox. See details below.

Also see:

Related YoLinux Tutorials:

°Clearcase Server installation

°Clearcase Commands

°Subversion And Trac Server Installation / Configuration

°Subversion Commands

°Subversion vs Clearcase

°C++ Info, links

°Software development tools

°C++ String Class

°C++ STL vector, list

°Emacs and C/C++

°YoLinux Tutorials Index




Free Information Technology Magazines and Document Downloads
TradePub link image


Prerequisites:

  • Check for installed packages: rpm -q gcc glibc-devel ncurses-devel
  • Also requires RPM ncompress: rpm -ivh ncompress-X.X.X-XX.i386.rpm
    This RPM contains the command uncompress required during installation.
  • Linux Kernel source is required: Check to see if kernel source is installed:
    Red Hat Enterprise 4 Red Hat Enterprise 3
    Source instals with kernel RPM:
        # ls /usr/src/kernels
    2.6.9-34.EL-smp_i686
    Source is included in a separate RPM:
        # rpm -q kernel-source
    kernel-source-2.4.18-14
    Installs to: /usr/src/linux-2.4.21-32.EL/
    The kernel source is required to build a new kernel module. We will be compiling a kernel module only and we will not be building or installing a new kernel. This step is required for building new kernel loadable modules (RHEL4: mvfs.ko and vnode.ko or RHEL3: mvfs.o and vnode.o) Clearcase ships with a pre-compiled kernel module for RHEL4.
  • Snare kernels contain their source in the RPM package kernel-smp-devel-2.6.9-34_snare.EL (RHEL4)
  • Clearcase server note: Note that the Clearcase server needs to be a Unix/Linux hosted Clearcase server. A Unix/Linux server can have Microsoft Windows clients as well as Unix and Linux clients. A Microsoft Windows server can not be used to host Unix or Linux clients.
    DO NOT USE MICROSOFT WINDOWS AS A CLEARCASE SERVER!!!


Download Clearcase Client 6.0 (2003.06.00) for Linux:

  • Download Red Hat Enterprise Linux client software: The versions are very specific. You will also have to be a licensed customer in order to perform the download.
    • http://www.rational.com
    • List of supported systems - platforms, OS and versions
    • Select "Software support" + "Upgrades" + "IBM Rational downloads and licensing center" (requires a login and password)
    • Download current full product versions: Select "V2003.06.00" + "Continue"
      [Client download page]
    • Download client software: C54UDNA.tar.Z
      Select "Accept".
      Note:
      • The download manager may ask for proxy settings, etc
      • 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.
  • Download Latest IBM/Rational Clearcase Patch:
    • http://www.rational.com
    • Select "Software support" + "Upgrades" + "IBM Rational downloads and licensing center"
      (requires a login and password)
    • Select: "Available Patches and service releases"
    • Enter in search box: "clearcase redhat" + Limit by type of support: "Downloadable files"
    • Download patch: clearcase p2003.06.00-28 for (Red Hat: clearcase_p2003.06.00-28.rhat_x86.tar.gz)
    • Download patch: clearcase p2003.06.00-29 for (Red Hat: clearcase_p2003.06.00-29.rhat_x86.tar.gz)

IBM/Rational use the following release numbers:


NFS mount Clearcase server:

For directories/mount points exported by the Clearcase server look at the NFS exports file /etc/exports (Solaris: /etc/dfs/dfstab).

Clearcase Client Configuration:

Typical Linux NFS client config file /etc/fstab:
(Solaris /etc/vfstab)
name-of-clearcase-server:/path-goes-here/vobstore  /net/name-of-clearcase-server/vobstore nfs auto  0 0
name-of-clearcase-server:/path-goes-here/viewstore /net/name-of-clearcase-server/viewstore nfs auto 0 0
For use with separate mount points for views and VOBs.
Note: The mount point /vob is NOT an NFS mount. It is an internal Clearcase mount which will be generated by Clearcase.
or
name-of-clearcase-server:/net/cleardata /net/cleardata nfs auto  0 0
In this example we use a single mount point for views and VOBs where the cleardata directory contains the sub-directories clearcase_rls/, viewstore/ and vobstore/.
Another format, if one is using multiple VOB servers: /net/hostname/cleardata.

Clearcase Server Configuration:

Typical Clearcase NFS server (Linux) /etc/exports:
...
/opt/rational/clearcase_rls 192.168.0.0/16(rw insecure sync no_root_squash) - Used for install /net/vobstore 192.168.0.0/16(rw insecure sync no_root_squash) /net/viewstore 192.168.0.0/16(rw insecure sync no_root_squash) ...
The "no_root_squash" option allows root from other systems to have root privaleges on that filesystem. It fixes view deletion problems by root. The "no_root_squash" option can be assigned temporarily to fix problems when they occur.

Typical Solaris server /etc/dfs/dfstab:
...
share -F nfs /opt/rational/clearcase_rls
share -F nfs /net/vobstore -nohide
share -F nfs /net/viewstore -nohide
...

Mount NFS file systems:

After your /etc/fstab is configured properly you are ready to mount the Clearcase NFS server file system:
[client root prompt]# mount /net/name-of-clearcase-server/vobstore
[client root prompt]# mount /net/name-of-clearcase-server/viewstore


Installation of IBM/Rational Cleacase Client on Linux Red Hat Enterprise Linux:

As user root:

  • Prepare directory structure:
    • Create modules directory:
      • RHEL3: mkdir /lib/modules/fs
      • RHEL4: Creates directory for you /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs
    • Create installation directory: mkdir /opt/rational/clearcase
    • Create release directory: mkdir /opt/rational/clearcase_rls
    • Files C54UDNA.tar.Z clearcase_p2003.06.00-28.rhat_x86.tar.gz and clearcase_p2003.06.00-29.rhat_x86.tar.gz are loaded to the release directory /opt/rational/clearcase_rls and the installation is performed from here (or the directory of your choice).
  • Unpack basic client software:
    • uncompress C54UDNA.tar.Z
    • tar -xf C54UDNA.tar
      This creates directory ./2003.06.00
      (/opt/rational/clearcase_rls/2003.06.00)
  • Unpack the patch:
    • mv clearcase_p2003.06.00-28.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
    • mv clearcase_p2003.06.00-29.rhat_x86.tar.gz 2003.06.00/rhat_x86/clearcase/patches
    • cd 2003.06.00/rhat_x86/clearcase/patches
    • tar xzf clearcase_p2003.06.00-28.rhat_x86.tar.gz
    • tar xzf clearcase_p2003.06.00-29.rhat_x86.tar.gz
  • Apply patch to release area:
    • cd clearcase_p2003.06.00-28/clearcase/install
    • ./apply_patch
    • cd ../../clearcase_p2003.06.00-29/clearcase/install
    • ./apply_patch


Installation Log:

Site Preparation log:

[root prompt]# cd ../../../install    
- Same as: /opt/rational/clearcase_rls/2003.06.00/rhat_x86/clearcase/install [root prompt]# ./site_prep

Updating release area '/opt/rational/clearcase/2003.06.00/rhat_x86'

For any of the queries that follow, help is available
by entering 'help', 'h' or '?' at the prompt.


Site default ClearCase license host: [Unknown] node-name-of-license-server Site default ClearCase registry host: [Unknown] node-name-of-clearcase-server Site default ClearCase registry data backup host: [Unknown] Site default ClearCase registry region: [Unknown] devel - or the name you are using at your site. 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]

[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

Information for the previous entries can be obtained from an existing installation with the following Clearcase command: ct hostinfo -l
(/opt/rational/clearcase/bin/cleartool hostinfo -l)

The bold text indicates an entry. The rest were defaults chosen by the "Enter" key.

The "host", "license" and "region" are stored in the following configurations files:

  • Host: /var/adm/rational/clearcase/rgy/rgy_hosts.conf
    (Linked to /var/adm/atria/rgy/rgy_hosts.conf)
  • Region: /var/adm/rational/clearcase/rgy/rgy_region.conf
  • License server: /var/adm/rational/clearcase/config/license_host
The host and region are a single entry in their respective file. This file and the appropriate NFS mount points will be changed when connecting to a different VOB server.


Clearcase Client Installation log:

(/opt/rational/clearcase_rls/2003.06.00/rhat_x86/clearcase/install/install_release)
[root prompt]# ./install_release
This release area contains the following Atria product(s):

MultiSite
ClearCase ClearQuest Integration
ClearCase Web Interface Server
ClearCase
ClearCase ClearDDTS Integration

A transcript of this installation will be initially written
to /tmp/Rational_install.XXXXXX.XX:XX.
After a successful installation, the transcript will be located
at /var/adm/rational/clearcase/log/Rational_install.XXXXXX.XX:XX.


The following installation methods are available:

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.

Type "Help" or "h" for expanded descriptions

Type "Quit" or "q" to exit the installation

Please select the installation method by number.


Method of installation>> 1 - Type the letter "q" to get out of reading full text of agreement Do you accept the terms of this license agreement? (y/n): y - Type the letter "q" to get out of reading full text of agreement Do you accept the terms of this license agreement? (y/n): y The following installation operations or models are available: 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. Type "Help" or "h" for expanded descriptions Type "Quit" or "q" to exit Please select the installation type by number. Model of installation>> 2 User specified:Install model:full Specify directory in which Rational products are to be installed [/opt/rational]: Pathname to the network-wide release directory (used as target of symbolic links) [/opt/rational/clearcase_rls/2003.06.00/rhat_x86]: 1 : ClearCase Minimal Developer Installation - No GUI, import or integration tools 2 : ClearCase Server-only Installation - Needed for view or vob server. No docs, mvfs, client 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 - All features and functionality. a : Select all f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit Selection number(s)>> 5 Selection number(s)>> 6 Selection number(s)>> 9 Next selection, '*' denotes a selected component 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 f : Finish selection x : Toggle expanded descriptions r : Reset selections q : Quit Selection number(s)>> f ClearCase License Server Host[node-name-of-license-server]:
ClearCase Registry Server Host[node-name-of-clearcase-server]:
ClearCase Registry Backup Host(s)[Unknown]:
ClearCase Registry Region[devel]:

Do you want to rebuild the vnode module when install is
complete (yes, no, quit, help)[no]:
Choose whether to install extended VOB support.
Install this feature? (yes, no, quit, help) [no]:

Continue installation?(yes, no, quit)[yes]:

Log file for this session: /var/adm/rational/clearcase/log/Rational_install.XXXXXX.XX:XX
Comes with pre-compiled load modules for Red Hat Enterprise 4.
Using vnode module as released, copied to /lib/modules/2.6.9-34.EL/kernel/fs/mvfs.
Updated: /lib/modules/2.6.9-34.EL/kernel/fs/mvfs/vnode.ko
Updated: /lib/modules/2.6.9-34.EL/kernel/fs/mvfs/mvfs.ko

Red Hat Enterprise 3 will result in a request to build new modules:

This requires the presence of the RPM kernel-source.
Do you want to rebuild the vnode module when install is 
complete (yes, no, quit, help)[no]:
User specified:Rebuild vnode module: yes

Enter path to your toplevel kernel source directory.
Default is [/lib/modules/2.4.21-32.ELsmp/build]:
User specified:Linux source directory: /lib/modules/2.4.21-32.ELsmp/build

If you switch to a custom built kernel, then the Clearcase modules will not load and may not build. This problem is resolved in the next step.
This is also true if running the "Snare" kernel or a custom kernel for RHEL4.


Generate a new MVFS loadable modules:

Red Hat "Enterprise" Linux 4 kernels include kernel source and install to /usr/src/kernels/2.6.9-34.ELsmp_i686/
Red Hat "Enterprise" Linux 3 kernels require the installation of the separate kernel source RPM kernel-source, which installs to /usr/src/linux (linked to kernel source directory /usr/src/linux-2.4.XX).

If you change or modify your kernel or if the newly compiled modules from "install_release" produces "unresolved symbols" error, then perform the following:

Build new RHEL4 modules: (as root)

[root prompt]# cd /var/adm/rational/clearcase/mvfs/vnode_src
[root prompt]# make clean
[root prompt]# make
Queries for kernel modules source path: /lib/modules/2.6.9-34.ELsmp/build [root prompt]# make install

Build new RHEL3 modules:

(Compile kernel source but do not install.)
[root prompt]# cd /usr/src/linux-2.4.21-40
[root prompt]# make mrproper
[root prompt]# make oldconfig
[root prompt]# make dep
[root prompt]# cd /var/adm/rational/clearcase/mvfs/vnode_src
[root prompt]# make
[root prompt]# make install

Creates loadable modules:

  • RHEL4: (kernel 2.6)
    • /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/mvfs.ko.
    • /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/vnode.ko.
  • RHEL3: (kernel 2.4)
    • /lib/modules/fs/mvfs.o.
    • /lib/modules/fs/vnode.o.

Also see: /var/adm/rational/clearcase/mvfs/vnode_src/README.txt


Start Clearcase client:

Create internal Clearcase mount points:

[root prompt]# service clearcase start
This start script (/etc/rc.d/init.d/clearcase) will create the directory /vob/... and generate internal mount points. This configuration is generated for you and will reside in the config file /etc/mtab. It will also perform a cleartool mount. The start script will also be executed during system boot. Once the service is started or the systems re-booted there is no need to re-execute this command manually.

The start script will load the kernel modules:

  • insmod -f mvfs
  • insmod -f vnode
  • Performs a: cleartool mount -a

Check Clearcase vob and view mount points: df

To make sure the Clearcase service is started during system boot, see if it is turned on for init levels 3 and 5: chkconfig --list | grep clearcase
For more information, see the YoLinux init tutorial.


User configuration:

Unix permissions will permit and prevent users from editing files. Thus developers should permit others in their group to read and write files. Set this as a default by setting the umask in thier $HOME/.bahsrc file:

   umask 002
or
   umask 0002

Installing Clearcase with site_prep option "setuid_mounts" can change this behavior.


Clearcase uses .bashrc for it's clearcase "view" shell.

Append the following to your $HOME/.bashrc

if [ $CLEARCASE_ROOT ]
then
export PS1='[`basename $CLEARCASE_ROOT`]$PWD>'
fi

alias ct=cleartool
This will change your prompt whenever you are in a Clearcase "view" (shell). The "view" will be listed in the prompt adding sanity to your experience.


Append the following to your $HOME/.bash_profile

export PATH=/opt/rational/clearcase/bin:$PATH
export CLEARCASE=/opt/rational/clearcase
alias ct=cleartool
Either re-login or initialize your shell session with the new changes: . $HOME/.bash_profile


Test installation with the following commands:

  • ct lsvob
  • ct hostinfo -l


The user's uid (user id) as defined in /etc/passwd and the user's gid (group id) as defined in /etc/passwd and /etc/group MUST match that used on the Clearcase server otherwise file permissions may not be compatable on the Clearcase MVFS file system. Other users defined on the Clearcase server may have to be defined locally on the client system to resolve uid/gid references. (i.e. When the command ls -l is issued, it will list the user/group as defined by the gid/uid) This can be supported by added entries to the local /etc/passwd and /etc/group files, NIS or LDAP.

Check your uid/gid with the command "id"


The developer must create a view in order to use Clearcase:
cleartool mkview -tag user1_view -stgloc viewstore

Where "viewstore" is the view storage location name.

Find list of view storage locations: cleartool lsstgloc


Clearcase GUI xclearcase:

Gui tools loaded:

/opt/rational/clearcase/bin/xclearcase
xcleardiff
xlsvtree

Use the following shell script to launch xclearcase:
File: /opt/bin/startXclearcase

#!/bin/bash
# For older systems: export LANG=C
PATH=/opt/rational/clearcase/bin:$PATH
cd /vob
/opt/rational/clearcase/bin/cleartool setview -exec /opt/rational/clearcase/bin/xclearcase name_of_view &
Desktop launcher icon:

[Potential Pitfall]: For older releases of Linux (i.e. Red Hat 8.0 or 9.0), the environment variable LANG MUST be set to "C" or "en_US.iso885915". The default in Red Hat 8.0 and 9.0 is en_US.UTF-8 which will crash xclearcase.

To use a different editor other than the default "vi" set the editor environment variable.
Example: export EDITOR=emacs

Tip: To view the additional collumns of information select "File" + "Preferences..." + select the collumns to display.

This script is for a single user system as it specifies a given view. For a multiuser system use the command /opt/rational/clearcase/bin/xclearcase & which is not tied to a view but will allow the user to interactively select the view upon startup.


Licenses:

One can keep track of the number of client licenses used with the following Gnome desktop launcher.

File:

  • Fedora/RHEL4: ~/Desktop/ClearcaseLicenses.desktop
  • Old Red Hat 8/9: ~/.gnome-desktop/ClearcaseLicenses.desktop
[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Exec=/usr/X11R6/bin/xterm -bg black -fg green -s -hold -geometry x50 \
-title "Clearcase licenses currently used:" \
-e /opt/rational/clearcase/bin/clearlicense
TryExec= Icon=/usr/share/pixmaps/gnome-gnomoku.png X-GNOME-DocPath= Terminal=false Name[en_US]=Clearcase Licenses GenericName[en_US]= Comment[en_US]=

One may release a license with the command: clearcaselicense -release user-id


De-Install/Removal:

To remove Clearcase, remove the following:

/usr/rational/clearcase
/var/adm/rational/clearcase
/etc/rc.d/...clearcase
/opt/rational/clearcase_rls - or whatever directory you used.
/opt/rational/clearcase
/lib/modules/fs/mvfs.o (kernel 2.4) OR /lib/modules/2.6.9-34.ELsmp/kernel/fs/mvfs/* (kernel 2.6)
entries in: /etc/fstab
/etc/mtab

/vob
/view
Also the mount point to the VOB server would be deleted after unmounting the NFS file system.


Clearcase Client installation Distribution Dependancies:

The Red Hat Clearcase dependencies as shipped in its original form:


Red Hat Enterprise Linux 4 Red Hat Enterprise Linux 3
Kernel: 2.6.9-34 2.4.21-40
gcc: 3.4.5-2 3.2.3-52
glibc: 2.3.4-2.19 2.3.2-95.33

File: /etc/redhat-release:

  • Red Hat Enterprise Linux Workstation 4:
    Red Hat Enterprise Linux Server WS release 4 (Nahant)
  • Red Hat Enterprise Linux Server 4:
    Red Hat Enterprise Linux Server ES release 4 (Nahant)
  • Red Hat Enterprise Linux Workstation 3:
    Red Hat Enterprise Linux WS release 3 (Taroon Update 5)
  • Red Hat 9.0:
    Red Hat Linux release 9.0 (Shrike)
  • Red Hat 8.0:
    Red Hat Linux release 8.0 (Psyche)
Lock file path: /var/lock/subsys/
(File: /var/lock/subsys/clearcase)


Switching Clearcase Servers:

Script to switch to a new Clearcase server:

service clearcase stop
rm /var/adm/rational/clearcase/rgy/rgy_hosts.conf
echo "server_X" > /var/adm/rational/clearcase/rgy/rgy_hosts.conf
rm /var/adm/rational/clearcase/rgy/rgy_region.conf
echo "region_A" > /var/adm/rational/clearcase/rgy/rgy_region.conf
rm /var/adm/rational/clearcase/config/license_host
echo "license-server" > /var/adm/rational/clearcase/config/license_host
service clearcase start
Note the file system NFS mount should be in effect. It is not a problem to mount all the NFS servers at once. Only one can be an active Clearcase server at any given time. this script activates a single server. I have a script for each Clearcase server.


Clearcase Notes:

  • Info:
  • A lower version of the Clearcase client will work with a higher version of the Clearcase view and VOB server or a matching version. The client can not have a higher version than the server.
  • Clearcase uses port 371
  • System tuning: One can set parameters in the startup script /opt/rational/clearcase/etc/clearcase_start
    • For environments with a large number of users (client or server), increase the limit of files that lockmgr can handle. Default:
              .../etc/lockmgr .... -f 256 ...
      It is not unusual to increase this to 512.
  • System tuning: MVFS scaling factors:
    • mvfs_largeinit=(available RAM in GBytes)/2 + 1
      Where mvfs_largeinit < 8.
      You must reboot ccase after defining the mvfs_largeinit parameter.
    • mvfs_vobfreemax=1800 Default =900
    • mvfs_mnmax<=4096 Sets max number of objects. Grows dynamically if more required.
    • mvfs_dncregmax: Number of files to cache.
    • mvfs_dncdirmax: Number of directory names to cache.
  • Only required if VOB/View is mounted non-NFS: Slocate will not index NFS mounted drives and thus Clearcase clients rarely have to change the slocate configuration. It is not desirable to have "slocate" index the view files. Disable this if necessary.
    See the YoLinux Clearcase server slocate configuration.
  • IBM/Rational:
    • North America: 1-800-728-1212, 1-800-433-5444
      Cupertino CA (408)863-4000
      20 Maguire Road, Lexington MA 02421 (781)676-2460
    • Europe/Middle East: 31-(0)20-4546-200 Netherlands
    • Asia Pacific: 61-2-9419-0111 Australia


Books:

Software Configuration Management Strategies and IBM(R) Rational(R) ClearCas e(R) : A Practical Introduction
by David E. Bellagio, Tom J. Milligan
ISBN #0321200195, IBM Press May 23 2005

Amazon.com
The Art of ClearCase(R) Deployment : The Secrets to Successful Implementatio n
by Christian D. Buckley, Darren W. Pulsipher
ISBN #0321262204, Addison-Wesley Professional (July 13, 2004)

Amazon.com
Software Configuration Management Strategies and Rational ClearCase: A Practical Introduction
by Brian White
ISBN #0201604787, Addison-Wesley Professional; 1st edition (August 25, 2000)

Amazon.com
   

    Bookmark and Share


Advertisements




Copyright © 2006 by Greg Ippolito