This article provides an overview of some of the concepts and resources to help you get started with ClearCase administration. There are many resources available that address ClearCase administration. Finding the right information can be an overwhelming task for administrators new to ClearCase. This article assumes no prior knowledge of ClearCase. The first few sections of the article cover concepts and provide examples to help you get familiar with ClearCase administration. Later sections of the article cover planning and ongoing administration activities.
This article takes the approach of learning by experimentation. The article gives a brief description for each example command and provides references for further details. The examples use command line interface to illustrate greater details for deeper understanding. The article provides references to GUI wizards without going into much detail.
ClearCase is Rational's market-leading solution for software configuration management system. ClearCase is a powerful system for managing versions of files and directories, generally refers to as elements. Virtually any project artifact can be stored in ClearCase repository called Versioned Object Base or simply VOB. One unique feature of ClearCase is the ability to version directory elements. This capability proved to be invaluable for code restructuring which commonly occurs during development and new releases.
ClearCase provides a rich set of access methods and controls to its repositories. All element access must go through a view. A view specifies a configuration, or config_spec, for selecting elements within a VOB. ClearCase tightly integrates with the underlying operating system to track changes and control access. The ClearCase administrator is the most powerful user having full control of a site installation. On Unix, this would be the superuser, UID=0, on the VOB server. On Windows, it is any user who is a member of the clearcase domain group.
ClearCase provides powerful command line and graphical interfaces. In addition, ClearCase integrates well with Windows explorer and many other major IDE in the market.
ClearCase is powerful in many ways; however, a common misconception is to treat it as a build and release system. ClearCase does provide convenience utilities such as clearmake, clearaudit, or omake to facilitate integration of your build and release system with ClearCase. These utilities in themselves do not make ClearCase a build and release system.
You can find general product information about ClearCase from Rational.com. More technical information is available here on the Rational Developer Network. Additional resource references are available in section 10 below.
Let's get started with the real product. If you already have ClearCase installed and have administrative privilege, skip to the next section. If you don't already have ClearCase installed or would like to create your own sandbox environment for experimentation, then this section may be useful for you.
There are three flavors of ClearCase: ClearCase LT, full ClearCase, and ClearCase Multisite. Refer to the Rational ClearCase LT product information for the differences. This article assumes you install and configure the full ClearCase version.
Download the latest version of ClearCase. Extract the compressed file and change directory to the installation image. Follow the Installation Guide manual for installation of ClearCase onto your local system. You will need either temporary or permanent license to use ClearCase. For temporary license, submit a request to Rational Support. For permanent license, the FAQ article contains instructions on how to obtain permanent licenses.
ClearCase stores project artifacts in a VOB. A VOB is a repository for storing versioned project artifacts and metadata. Project artifacts are source, binary, or other contents that is checked into ClearCase. Metadata refers to attributes, internal object references, audit trail, and other information managed by ClearCase. A VOB is a boundary unit for managing security, performance, and Multisite. Until you actually store your project artifacts in your VOB, you can freely create and remove your test VOB. Let's create a VOB for experimental purpose. The Windows installation of Clearcase comes with a convenient Create VOB wizard in the Rational Administrative Tools folder within the Start menu. The command line interface is available on both Windows and Unix.
Before creating a VOB, you must share a directory for holding the repository. Launch <install_dir>\etc\SvrStor.exe to share a folder and publish the storage location. You can achieve the same result by sharing a folder using Windows explorer and running cleartool mkstgloc command. You can find this and other commands in the Command Reference manual.
Using the storage location above, let's create a VOB. Use the Create VOB wizard or type the following command:
C:\>cleartool mkvob -tag \myFirstVOB -stgloc -auto
That's it! You have just created a VOB capable of storing project artifacts. Let's examine the command a bit closer. The cleartool program is a command-line interface utility for invoking many ClearCase controls. Both administrators and developers can use this program for day-to-day activities. The mkvob command is one of many commands supported by the cleartool program. This command requires a tag parameter and a storage location parameter. Type the following command to see other parameters:
C:\>cleartool man mkvob
The man command brings up the manual similar in content to the Command Reference manual. You can use the man command to show the online manual of any cleartool commands.
In order to store or retrieve data, you must create a view to access VOB elements. A view specifies the configuration or version selection within one or more VOBs. You can create either a snapshot view or a dynamic view. A snapshot view is a copy of files selected by your config_spec similar to a CVS and other SCM workspace. This mode is convenient for off-line work where network connectivity to the ClearCase server may not be available. A dynamic view is a network-mapped storage similar to NFS or SMB file system. It has the benefit of automatic updates and more. Dynamic view does consume significant network bandwidth and require constant network availability. It is very convenient for administrators since creating or deleting a dynamic view is fast. Let's create a dynamic view to access the VOB you have just created.
C:\>cleartool mkview -tag myFirstView -stgloc -auto
Similar to the VOB creation above, you must specify a storage location to store the view repository. The storage location for both VOBs and Views are reserved for ClearCase to manage. As a ClearCase administrator, you may have to occasionally fix VOB and View repositories to recover an abnormal condition.
Let's make use of the VOB and view you just created. Dynamic views on Windows are mapped to a network drive. ClearCase by default uses the M: drive as root for all active dynamic views on your system. Directly within the view directory are mounted VOB tags. If you do not see the \myFirstVOB in the M:\myFirstView directory, mount the VOB with the following command:
C:\>cleartool mount \myFirstVOB
Browse to the M:\myFirstView\myFirstVOB folder. This is the top-level directory for accessing and storing project artifacts. Use Windows explorer or any other shell to add files and directories in the VOB. Refer to the mkelem manual page for more details.
Unified Change Management or UCM is a set of policies and processes on top of base ClearCase. Prior to ClearCase version 4.0, many ClearCase shops would develop their own set of triggers and scripts to enforce policies and processes. UCM tightly integrates with ClearCase to provide a standard set of policies and processes. Rational supports both base ClearCase and UCM mode of operations. UCM is an excellent solution for software development groups new to ClearCase or those requiring a more integrated change management solution.
ClearCase stores UCM metadata in a specialized VOB called project VOB. A project VOB can store files and directories just like any other VOB. Let's create a project VOB using the same storage location defined earlier. Type the following command:
C:\>cleartool mkvob -tag \myFirstPVOB -ucmproject -stgloc -auto
This command creates a VOB capable of storing UCM metadata. Notice the additional -ucmproject flag enables the myFirstPVOB to hold UCM metadata. No UCM project is created at this point. Let's create a component VOB to store project artifacts:
C:\>cleartool mkvob -tag \myFirstComp -stgloc -auto
The myFirstComp VOB is just a regular VOB at this point. Converting the myFirstComp into a component VOB requires us to create a component in the project VOB. A view context is required in this process. Let's reuse the view created earlier. Enter the following command sequence to convert myFirstComp VOB into a UCM component VOB:
M:\myFirstView>cleartool mount \myFirstPVOB
M:\myFirstView>cleartool mount \myFirstComp
M:\myFirstView>cleartool mkcomp -root myFirstComp myFirstComp@\myFirstPVOB
You can verify the association between the project VOB and the component VOB by typing the following command:
C:\>cleartool describe \myFirstPVOB
C:\>cleartool describe \myFirstComp
The AdminVOB hyperlink is used by ClearCase to associate component VOBs to a project VOB. Now that you have a component defined, let's create the UCM project and stream. Type the following:
C:\>cleartool mkproject -mod myFirstComp@\myFirstPVOB -in RootFolder
C:\>cleartool mkstream -integration -in myUCMProject@\myFirstPVOB
In order to access UCM-managed project artifacts, you need to create a UCM view. A UCM view is attached to a stream. Type the following to create a dynamic integration view:
C:\>cleartool mkview -tag myIntegrationView -stream
myUCMProject_Integration@\myFirstPVOB -stgloc -auto
The main difference between a normal view and a UCM view is the config_spec. You can display the config_spec of the myIntegrationView by typing the following command:
C:\>cleartool catcs -tag myIntegrationView
As a ClearCase administrator, there may be occasions where you may edit a UCM config_spec. For the most part, UCM view config_spec should not be manually changed.
The processes above can be done simpler using the Create VOB wizard and the Project Explorer program. You can create additional test VOBs and projects using the wizard. You can clean up your experimental VOBs and views later simply by removing your test VOBs and views. Refer to the rmvob and rmview commands for more details.
Now that you have some experience with ClearCase administration, let's rollout ClearCase to a small development group. The first thing that you need to do is to identify the following servers:
- ClearCase license server
- ClearCase registry server
- ClearCase VOBs and Views server
If your organization already has a ClearCase license server and there are sufficient licenses available, you can simply make use of it. Otherwise you need to identify a machine to host ClearCase license. Typical ClearCase shops combine both the license and registry servers onto one machine. For initial rollout, you can also put VOBs and Views on the same server. You can later migrate the VOBs and Views to another server if you experience performance problems.
If your development platform is Windows, make sure all the development machines are in the same Windows domain as your VOBs and Views server. Create a clearcase_albd domain user, a vobadm domain user and a clearcase domain group. Add vobadm, clearcase_albd, and your domain accounts to the clearcase group.
If your development platform is Unix, make sure all the development machines are in a common NIS/NIS+ domain as your VOBs and Views server. Create a vobadm account and a common group, i.e., clearcase_users. Set vobadm primary group to clearcase_users and add all developer accounts to the clearcase_users group. I will discuss the significance of these groups in Section 9 below. More detailed information is available in the Administrator's Guide for Rational ClearCase.
ClearCase comes with a site_prep program to prepare a release area for ClearCase client or server installation. This program prompts for configuration defaults and saves the responses in a sitedefs.dat file. You will need to specify the license server, registry server, region, albd account and password (Windows only), and a few other options. Make sure the servers and accounts are correct. Make sure the region is the same for the client and server machines.
Once the release area is ready, share the location as read-only so that everyone can install ClearCase onto his or her machine. Be sure to remove write permission to prevent inadvertent corruption of your release area. Refer to the Installation Guide for Rational ClearCase manual for Windows or Unix for installation details.
Prepare a training session for your developers. You can find typical issues developers may experience in the Catch-22: Rookie Mistakes in ClearCase article. The ClearCase community is a large and actively helpful group. If you run into ClearCase issue, you may find help on the ClearCase discussion forums on the Rational Developer Network.
Powerful capabilities usually lead to complexity. Native ClearCase interface provides powerful access methods and controls for development. Many ClearCase features that are crucial for software development may not be necessary for other stakeholders within a project. ClearCase provides a simple Web interface called ccweb access for access to the repository. This interface is convenient for managers, document writers, or those who needing casual access to ClearCase. The ccweb interface reduces complexity arise during development such as branching, merging, or defect tracability.
You should allocate a dedicated machine for serving ClearCase Web service. This machine should not be your VOB, view, or license server due to resource contentions. The machine need not be very powerful unless you plan to have many concurrent users. Configuration of ccweb involves setting up a Web server, a static html virtual directory, and a cgi-bin directory. The Administrator's Guide for Rational ClearCase manual provides details for configuring ccweb with Apache, IIS, and iPlanet Web servers.
Once ClearCase is in production use, there are ongoing administration tasks. One of the most important tasks for ClearCase administration is backup and restore of VOB storage. Views typically do not need to be backed up since they can be easily recreated. Refer to the Backup and Restoring VOBs section of the Administrator's Guide for Rational ClearCase manual for further details.
There are many triggers that have been developed over the years to simply ClearCase administration. Perhaps the most important one is the change-owner trigger to prevent administrative operations such as rmelem on elements. Change directory to the path below and type the following command to create this trigger.
M:\myFirstView\myFirstVOB>cleartool mktrtype -element -all -postop mkelem -nc -exec "cleartool protect -chown DOMAIN\vobadm -chgrp DOMAIN\users \"%CLEARCASE_PN%\"" mkelem_postop
This trigger is launched on the client's machine immediately after an element is added. A variation of this trigger and several other useful triggers is available in the Ten Best Triggers article.
There are many ClearCase resources available to help you along the way. You may find answers to some frequent questions in the Rational ClearCase FAQs. Rational Technical Support is another good resource to help resolve your ClearCase issues. In addition, the CCIUG mailing list is a very active International user group for ClearCase discussions. You can find answers to many technical ClearCase-related questions in this community.
As your project grows you may need to increase the hardware to improve response time. Addressing performance issues require knowing how ClearCase works. ClearCase is inherently a client-server application. Rational recommends that all the client machines and the ClearCase servers should be on the same local 100 Mbps network, preferably running full duplex. ClearCase performance drops drastically when the network latency is high.
Each VOB or view consumes resource on the server. If you find that the server is low on hardware resource, you can scale up vertically or horizontally. If your hardware is upgradeable, you can add more hardware to the existing server. You can also transfer load to another server by migrating VOBs and views to another server. Refer to the Administrator's Guide for Rational ClearCase manual for migration instructions. If a VOB is large and highly used, consider splitting it into two VOBs. Refer to the relocate command for more information.
ClearCase uses up to 7 open file handles per VOB. By defaults, ClearCase allows a maximum of 1024 open file handles per VOB server. If your VOB count exceeds 100 per server, consider tuning the ClearCase Lock Manager parameter. Refer to Technical Solutions article #704 for more details.
You may still see performance problems even though the network and server resources are fine. Verify that no single VOB is being overloaded. You can migrate elements within a VOB to another VOB to distribute the load. Use the relocate command to preserve element history. The Administrator's Guide also contains a chapter on using the relocate command to split a VOB. Refer to the Splitting VOBs with relocation chapter for more details. The Magical World of VOB Sizing article provides some guidelines for VOB boundary.
There are infrastructure security and ClearCase configurations that you should consider before rolling ClearCase out to large development groups. If there is little or no interaction between the groups, consider separating the groups by ClearCase registry regions. A region is a namespace for VOBs and view tags. Separating each group by region keeps VOB and view listings confined to that project. For each development group, create a separate release area with the group region name set in the default configuration. If a VOB server hosts VOBs from multiple projects, all the VOBs on that server must be created in the server's default region. Use cleartool hostinfo to display a machine's default region. You may need to create a VOB tag in the group region whenever you create a VOB. Refer to the man page for the mktag command for more details.
Separating development groups by regions provide some isolation. Since many cleartool commands allows overriding the default listing with a -region option, isolation by region is not strictly enforceable. The permissions page in the Command Reference manual describes the access control of administrative commands. In general the superuser, VOB owner or vobadm are administrative users. Protect these accounts with strong password. Protect the Windows domain by monitoring users of clearcase and Domain Admins group. Anyone with Domain Admins group can modify your clearcase domain group to become a ClearCase administrator. Do not use autohome for the vobadm account. Do not allow automatic rlogins as vobadm from untrusted hosts.
Assuming the administrative accounts are secured, you should restrict checkouts for each VOB. ClearCase determines whether or not a user can checkout based on his/her group membership and the groups in the VOB. You can find the VOB groups using the describe command. You can change the VOB groups using the protectvob command.
You can restrict VOB access further by protecting elements within a VOB. Use the protect command to change element permissions. ClearCase uses Unix-style security on files and directory. If you want to completely remove read, browse, or write access to everyone outside of a group, remove others permission from the VOB root element. You can even restrict access to just yourself by removing group and others permission from the VOB root element.
ClearCase is a powerful and flexible software configuration management solution. ClearCase scales well to large complex software development projects including aerospace, telecommunications, and defense projects. ClearCase can also be configured with ease of use for a small development groups. The ccweb interface allows simple access to documents and other artifacts in ClearCase. The Unified Change Management provides a quick and powerful change set management policies. There is a wide range of customizable solutions packed into ClearCase. There are many articles available in the Rational Developer Network to help you plan, design, and customize to fit your organization. The ClearCase administrator has the ultimate flexibility in configuring ClearCase to fit organizational requirements.