This chapter presents a procedure for setting up your network's ClearCase data repository—a set of globally-accessible VOBs. The outline of this chapter makes a handy checklist:
Select a host for a new VOB
Modify operating system resources, if necessary
Create the VOB (and, if necessary, adjust its registry and identity information, in order to ensure global accessibility and implement access controls)
Synchronize the VOB with other existing VOBs
Populate the VOB with new or existing development data
The next chapter discusses the (quite similar) procedure for setting up ClearCase views.
A host on which one or more VOB storage directories reside is termed a VOB host. A typical network distributes its VOBs among several VOB hosts. Any host with a ClearCase-supported hardware/software architecture can be a VOB host; selecting an appropriate host (and making necessary adjustments to it) is crucial to obtaining satisfactory ClearCase performance.
The most important criteria for selecting a VOB host are:
Main memory (RAM)—The minimum recommended main memory size is 64Mb. This is the most important factor in VOB performance; increasing the size of a VOB host's main memory is the easiest (and most cost-efficient) way to make VOB access faster and/or to increase the number of concurrent users without degrading performance.
Disk capacity—Adequate disk storage is also very important: a VOB database must fit in a single disk partition, and VOB databases tend to grow significantly as development proceeds and projects mature. We recommend a disk capacity of at least 2Gb.
Processing power—The recommended speed for a VOB host's processor is 20–35 MIPS. Make the most of the CPU cycles by keeping “private” processes—ClearCase client tools and views—off the VOB host.
Availability—A VOB intended for shared access must be located in a disk partition that can be mounted by all ClearCase client hosts. Wherever possible, select a host that can be accessed with the same hostname by all ClearCase hosts. (A host with multiple network interfaces presents a different name through each interface.) If a VOB host has multiple names, you will need to create multiple network regions, to logically partition the network.
A VOB host that meets the description in the preceding section has this (very approximate) overall capacity:
2500 source file elements, each with a version tree that contains many versions
750 files that are build targets; the VOB typically stores multiple instances of each target (that is, multiple derived objects built at the same pathname), representing various build configurations in current use
ability to service requests from 20 concurrent users on ClearCase client hosts around the network
It is up to your organization to decide how to allocate data to one or more VOBs on a VOB host. Here are the principal tradeoffs:
Splitting data into several small VOBs greatly increases your flexibility: it is easy to move an entire VOB to another host; it is difficult to split a VOB into two parts and move one of them to another host.
Typically, having multiple small VOBs makes for fewer performance bottlenecks than having one large VOB.
Having fewer VOBs facilitates data backup.
Having fewer VOBs facilitates synchronizing label, branch, and other definitions across all the VOBs.
In your VOB planning, keep in mind that you can make several distinct VOBs appear to be a single directory tree, using VOB symbolic links (Figure 6-1).
 | Note: Be sure that the text of a VOB symbolic link is a relative pathname, not a full pathname: |
% ls -l /vobs/project/lib (wrong) /vobs/project/lib -> /vobs/lib % ls -l /vobs/project/lib (right) /vobs/project/lib -> ../lib |
This ensures the link will be traversed correctly in all view contexts. See the pathnames_ccase manual page for more on this topic.
Each VOB is managed by a battery of server processes, which run on the host where the VOB storage directory resides. These servers make significant demands on system resources. Accordingly, you should make sure that the system's configuration is adequate for ClearCase's needs.
You may need to adjust the following kernel resources on a VOB host:
Overall process table—The operating system's process table should support 96 or more concurrent user processes. If more than three or four VOBs are to reside on the host, increase the size of the process table to at least 128.
Overall file descriptor table—The size of the operating system's file descriptor table should be at least 600. If more than three or four VOBs are to reside on the host, increase the size of the file descriptor table further.
You may also find it beneficial to adjust a VOB hosts' kernel resources after ClearCase has been up and running for some time. For more on this topic, see “Manipulate Block Buffer Caches”.
Follow these steps to plan and execute the creation of each new shared VOB:
Log in to the VOB host—Log in to the host you've selected to be the VOB host. As discussed in “Network-Wide ClearCase Administrator”, we suggest that you log in as vobadm (or some other “ClearCase administrator” identity).
Choose a location for the VOB storage directory—Make sure that the location is in a disk partition that has plenty of room for VOB database growth. This partition must be visible (mounted) on all ClearCase client hosts that will need to access the VOB. For example:
/vobstore/flex.vbs
In this example, /vobstore could be a separate disk partition mounted on an empty subdirectory of “/”. Just make sure you know where the disk storage is really located, and that it is globally visible.
Choose a VOB-tag—Each ClearCase client host mounts the VOB as a file system of type MVFS. Unless there is a compelling reason (perhaps you are trying to drive yourself crazy), all clients should mount the VOB at the same pathname. For example:
/vobs/flex
The full pathname of the VOB mount point is called its VOB-tag.
Note: VOB-tags and view-tags are different in form: a VOB-tag is a full pathname; a view-tag is a simple directory name. Create the VOB storage directory—Using cleartool or xclearcase, enter a “create new VOB” command. Continuing the example from the preceding steps, the cleartool command would be:
% cleartool mkvob -public -tag /vobs/flex /vobstore/flex.vbs
You'll be prompted to enter a comment, which will be stored in an event record (create versioned object base) in the new VOB's database. You'll also be prompted to enter a password, because you're creating a public VOB. mkvob validates your entry using the contents of the VOB-tag password file—/usr/adm/atria/rgy/vob_tag.sec on the network's registry server host.
Making the VOB public has two effects:
On each client host, the command cleartool mount -all will be invoked by the ClearCase startup script to activate this VOB (and all other public VOBs).
If the VOB becomes unmounted for any reason, any user (not just root or the VOB's creator) will be able to remount it.
After the VOB is created, mkvob reports the new VOB's registry and access-control information:
Host-local path: ccsvr01:/vobstore/flex.vbs Global path: /net/ccsvr01/vobstore/flex.vbs VOB ownership: owner vobadm group dvt Additional groups: group libdvt
In many cases, you've now completed the VOB-creation process. The following sections describe special cases and optional adjustments you may wish to make to the new VOB.
This section discusses changes that you may need to make to a new VOB's identity information. We discuss both the no-change-required and the change-required situations.
There are access-control issues to be addressed if (1) the prospective users of the VOB do not all belong to the same group, and (2) non-group members are to be prohibited from accessing data. (This issue was discussed in “VOBs and Views: Owner and Groups”.)
Small development organizations, and ones in which data security is not a major issue, sometimes place all users in the same group (for example, dvt). In such organizations, all ClearCase data structures should also belong to the common group—a VOB or view belongs to the principal group of its creator—and will be fully accessible to all users.
The example commands in Steps #1–4 in “Creating a New VOB” are sufficient to create a VOB in such a situation.
If your organization has multiple user groups, there are several questions to be answered when you create a new VOB:
Who should be granted “write” access?—Determine which users will be doing development work in the VOB, and compile a list of their principal groups. All these groups must be added to the VOB's group list. (If a user group is also the VOB's principal group, it need not be added to the group list.)
Should all others be granted “read” access?—If so, then the VOB's mode should grant others (as opposed to user and group) “read” access. But if some users are to be restricted even from examining a VOB's data, then:
Make sure that the access mode of the VOB's root directory (top-level directory element) grants others no access rights at all.
Make sure that if a user is to be prohibited from accessing the VOB, his or her list of groups does not overlap the VOB's list of groups at all.
Let's revisit the example in “Creating a New VOB”. The VOB created in Step #4 is owned by vobadm, with principal group dvt, and with libdvt as its only additional group. Suppose that the VOB will be used by ten developers, whose principal groups include dvt, libdvt, exper, and visitor.
Add users' principal groups to the VOB's group list—In this example, the groups exper and visitor are to be added to the VOB's group list. Only the root user can use the protectvob command.
% su vobadm Password: <enter password> # cleartool protectvob -add_group exper,visitor \ /vobstore/flex.vbs ... <confirmation prompts and messages> ... VOB ownership: owner vobadm group dvt Additional groups: group libdvt group exper group visitor # exit %
Remove `other' access to the VOB—To prevent users who do not belong to any of the VOB's groups from accessing the VOB, change the access mode of the VOB's root directory. This requires that the VOB be mounted, so make the change on a ClearCase client host.
% rlogin neptune -l vobadm Password: <enter password> % cleartool mount /vobs/flex (just in case) % cleartool protect -chmod o-rx /vobs/flex Changed protection on "/vobs/flex". % ls -ld /vobs/flex drwxrwx--- 3 vobadm 30 Jan 31 13:24 /vobs/flex
The output from the mkvob command (Step #4 above) includes a “global” (network-wide) pathname for the VOB storage directory:
Global path: /net/ccsvr01/vobstore/flex.vbs |
This pathname is heuristically derived—that is, it's an intelligent guess. Depending on the accuracy of the guess, you may have some more work to do in guaranteeing the VOB's accessibility to all users on all ClearCase hosts.
If all ClearCase client hosts can access the VOB at the “global pathname” reported by mkvob, you have no more work to do.
It might be the case that there is a global pathname, which all ClearCase client hosts can use to access the VOB storage directory, but mkvob's heuristically-derived pathname is not the right one. The most common reasons are:
use of a nonstandard auto-mount program
use of a home-grown (perhaps manual) scheme for mounting file systems around the network
In this case, use the mktag command to correct mkvob's guess. For example:
% cleartool mktag -replace -vob -public -tag /vobs/flex \ -host ccsvr01 \ -hpath /vobstore/flex.vbs \ (the above information must be valid on the VOB host) -gpath /allvobs/flex.vbs \ (valid pathname to VOB on all hosts) /vobstore/flex.vbs (valid pathname on the local host) Vob tag registry password: <enter password> . . |
It may be that there is no global pathname for the VOB storage directory. The most common reason is that the VOB host has multiple network interfaces (is multihomed)—some client hosts might know it as ccsvr01, while others know it as ccsvr01-gw.
In this case, you must partition your network into multiple network regions; in each region, the global-pathname criterion must hold true. For background information, see “Network Regions”.
Continuing the example, suppose that the VOB host is named ccsvr01 in region “uno”, and ccsvr01-gw in region “dos”. The mkvob command (Step #4) created the VOB-tag in one of the regions—it doesn't matter which one, because you should now use mktag to update/create public VOB-tags in all network regions:
% cleartool mktag -replace -vob -public -region uno \ -tag /vobs/flex \ -host ccsvr01 \ -hpath /vobstore/flex.vbs \ -gpath /net/ccsvr01/vobstore/flex.vbs \ (valid pathname to VOB on all hosts in network region “uno”) /vobstore/flex.vbs Vob tag registry password: <enter password> . . % cleartool mktag -replace -vob -public -region dos \ -tag /vobs/flex \ -host ccsvr01-gw \ -hpath /vobstore/flex.vbs \ (valid pathname to VOB on all hosts in network region “dos”) -gpath /net/ccsvr01-gw/vobstore/flex.vbs \ /vobstore/flex.vbs Vob tag registry password: <enter password> . . |
| Note: As in Case 2, your -gpath value may need to take into account usage of a nonstandard auto-mount program or other mounting idiosyncrasies within each network region. |
For additional registry-related procedures, see Chapter 18, “Adjusting ClearCase Registry Information”.
Typically, you won't add remote storage pools to a VOB until a disk-space crisis occurs. But as you gain more experience with how ClearCase is used by your group and how VOBs grow, you may wish to add remote storage pools when you first create a VOB. This can help to postpone the disk-space crisis—perhaps even eliminate it altogether.
See “Creating Additional VOB Storage Pools” for a step-by-step procedure.
A typical project involves multiple VOBs. To ensure that they all work together, you will probably need to coordinate the VOBs' type objects: branch types, label types, and so on. (See the ClearCase Concepts Manual for an introduction to type objects.)
For example, the following config spec might be used to create a view that selects the source files that went into an old release:
element * RELEASE_3 |
In order for this strategy to succeed, all relevant VOBs must define version label RELEASE_3—that is, label type RELEASE_3 must be created in each VOB.
There is no single command that copies type objects from one VOB to another. You may be able to automate this process somewhat with a script—for example, using the output of an lstype -brtype -long command in one VOB to form a series of mkbrtype commands for use in another VOB.
The new VOB is now ready to be populated with data by the development group. At this point, the VOB contains a single directory element, the VOB's root directory. When the VOB is activated, this directory appears at the VOB-tag pathname—that is, at the VOB mount point.
| Note: The root directory also contains a lost+found directory. See the mkvob manual page for a discussion of this directory. |
To users, a VOB appears to be a single UNIX directory tree. Thus, it makes sense to consider how your sources “naturally” fall into logically separate trees, and create one VOB for each one. If two projects do not share source files, place the sources in different VOBs. Typically, several or all projects share some header (.h) files. Isolate these shared sources (for example, a /vobs/project/include directory tree) in their own VOB.
If this approach concentrates too many elements in a single VOB, it can produce a performance bottleneck in accessing the VOB database, causing the VOB host to become “CPU-bound”. Adding users to a project also increases the load on the VOB databases that they access and, thus, can also produce “CPU-bound” problems.
To illustrate migration of sources to ClearCase, we present a simple conversion scenario: using an entire RCS source tree to populate a newly-created ClearCase VOB. Suppose that the root of the RCS tree is /usr/libpub, located on a host where the empty VOB has already been activated, at /proj/libpub.
Go to the source data—Change to the root directory of the existing RCS source tree:
% cd /usr/libpub
Run the conversion utility—Use the RCS-to-ClearCase import utility, clearcvt_rcs, to create the scripts that will convert RCS files (,v files) to ClearCase elements:
A “master conversion script” is created in subdirectory cvt_dir of the current working directory; the script's full pathname is /usr/libpub/cvt_dir/cvt_script.
Set a view configured with the default config spec—You can use the catcs command to determine whether your current view (if any) has the default configuration. If not, set another view:
% cleartool setview dft
Go to the target VOB—Change to the root directory of the newly-created libpub VOB—that is, the directory specified by its VOB-tag:
% cd /proj/libpub
Run the conversion script—Invoke the “master conversion script” to populate the libpub VOB:
% /usr/libpub/cvt_dir/cvt_script Converting files from /usr/libpub to . You are using the default config_spec Created element "././Makefile" (type "text_file"). Changed protection on "././Makefile". Making version of ././Makefile Checked out "././Makefile" from version "/main/0". Comment for all listed objects: Checked in "././Makefile" version "/main/1". . .
Note that there is no need to checkout or checkin the VOB's root directory element—this is handled automatically. If problems occur that cause the conversion script to terminate prematurely, you can simply fix the problem and restart the script.