After a brief review of ClearCase storage registry concepts and terminology, this chapter describes the procedure for adding a new network region. It concludes with a set of general guidelines for registry-related administration.
At this point, you should be familiar with the ClearCase storage registry and, possibly, with network regions as well. Chapter 3, “Network-Wide Access to ClearCase Data”, introduces the ClearCase storage registry, including the VOB and view tag and object registry files. Chapter 3 also describes network regions, including a sample network with two regions, uno and dos.
Chapter 6, “Setting Up ClearCase VOBs”, describes the process of creating and registering a VOB. It introduces the subject, which this chapter expands on, of using multiple network regions to provide global network access to VOB storage directories.
Later, Chapter 19, “Changing the Location of Network-Wide Resources”, describes the procedures for moving the ClearCase storage registry and for renaming the registry server host.
All VOBs and views are registered in the ClearCase storage registry. The storage registry resides on the registry server host, in /usr/adm/atria/rgy, and it includes two distinct pieces, a VOB registry and a view registry. The VOB registry and view registry each include two files: one registers tags, the other registers storage directories. The files are vob_tag, vob_object, view_tag, and view_object.
The vob_object and view_object registry files record the location of each VOB and view using a host-local pathname. That is, the pathname to the data structure is one that is valid on the host where the storage directory resides. These pathnames are used by the ClearCase server processes (view_server, vob_server, and so on), which always run on the applicable VOB or view storage host.
For most purposes, client processes access VOBs and views via VOB-tags and view-tags, not physical storage locations. These logical locations are resolved to physical storage locations through lookups in the vob_tag and view_tag registry files. Each tag registry entry includes a global pathname to the corresponding VOB or view storage directory—a pathname that is valid on all ClearCase client hosts in the network region to which the tag applies.
Three points deserve special emphasis:
A tag entry's global access pathname must be valid on all hosts in the tag's network region, including the corresponding storage directory's host.
For all practical purposes, developers cannot access a VOB or view unless it has both an object registry entry and a tag registry entry. (An administrator can perform some specialized operations on a VOB or view storage directory that has no corresponding tag.)
If your network has more than one network region, a VOB or view needs a separate tag entry (but not a separate tag name) for each region with hosts that will access the VOB or view.
The bullet items from the previous subsection have several practical implications for the system administrator. In particular:
Be “on the lookout” for faulty global access pathnames stored in the two tag registry files.
If a VOB or view access operation fails, first make sure a VOB-tag or view-tag exists for the network region from which the access is attempted. (A common mistake is attempting to access a VOB or view that has no tag.)
Use lsvob or lsview with the -long option to report the key registry information. If you cannot “see” a VOB with lsvob, or a view with lsview, then it does not have a tag registered for the current network region (or for the region specified in the command). For a VOB or view with a registered tag, the output from lsvob -long and lsview -long includes:
the VOB-tag or view-tag
the host name for the host on which the storage directory resides
the “host-local” access pathname (from the vob_object or view_object file), which the relevant VOB or view server uses to access the storage directory
the global pathname (from the vob_tag or view_tag file), which is used to resolve references to the newly created tag
For example:
If the global and server access paths are identical, or if they don't look right to you, then you might anticipate problem reports regarding access to the VOB or view.
The mkvob and mkview commands create both the object and tag registry entries necessary for ClearCase client access. (There is one exception: if you create a VOB with a public tag, but the tag password fails, the VOB is created without the tag. You must create the tag in a separate operation with mktag.) Like lsvob and lsview, mkvob and mkview output includes:
the “host-local” access pathname (from the vob_object or view_object file)
the global pathname (from the vob_tag or view_tag file)
Sample mkvob output:
. . Host-local path: venus:/vobstore/src.vbs Global path: /net/venus/vobstore/src.vbs . . |
Sample mkview output:
. . Host-local path: venus:/viewstore/main.vws Global path: /net/venus/viewstore/main.vws . . |
Use mktag to add or replace tag entries for existing VOBs and views. Two common uses are:
creating additional VOB-tags and view-tags to support multiple network regions
converting a private VOB to a public VOB
To change a tag's name, or to change its assigned network region, use rmtag and mktag in succession, not mktag -replace. See the mktag and rmtag manual pages for more detail on tag creation and removal.
Figure 18-2 shows all of the cleartool commands that affect registry files. See also the registry_ccase manual page.
The section “Ensuring the VOB's Global Accessibility” outlines the circumstances which may require you to adjust the automatically generated registry entry for a VOB or view. That section goes on to present some sample mktag commands that “fix” the storage registry by explicitly specifying, for a VOB or view, the host-local and global access paths. This section applies in the case where a single, global pathname to a VOB or view storage directory does not exist for all network hosts that must access it—so you must partition your network into at least two network regions. If you have not read the section “Network Regions”, please do so before proceeding.
Of the network configurations that demand multiple network regions, two are most common:
Multiple network interfaces to a VOB or view host—For example, a host might be known to some hosts (and their automounter programs) as neptune, and to other hosts as neptune-gw. In this case, the same VOB might have two “global” storage pathnames:
/net/neptune/vobstore/src.vbs /net/neptune-gw/vobstore/src.vbs
Multiple host architectures in the same network—For example, a view that is accessed as /net/neptune/viewstore/main.vws on a UNIX host may be accessed as V:\viewstore\main.vws on a Windows/NT host. (Note that when pathnames differ syntactically between hosts, it is not just storage access paths that are guaranteed to differ, but VOB-tags as well.)
Figure 18-3 illustrates a simple two-region network. Two network regions are required because a (shared) VOB host has two network interfaces and is known to some hosts as neptune, and as neptune-gw to others. Although hosts in both regions use the same VOB-tags (and view-tags), they access VOB/view storage—at least on neptune/neptune-gw—using different pathnames. Therefore, separate tag registry entries are required.
Sample commands in this procedure use host and pathnames from the network in Figure 18-3.
 | Note: If you are a new ClearCase installation, and you are partitioning the network into regions from the start, then use this procedure to add regions 2 through n after (1) ClearCase has been installed on each host, and (2) shared VOBs and views have been created on the network's VOB and view storage hosts. |
Pick a region name—In this example, we use west as the region name.
Determine the “global” access paths for the new region—For each shared VOB and view, determine a network address to the storage directory that is valid on every host that will be in the new region. (You may need to take into account a nonstandard automount program or other local mounting policies.) For example, on sierra:
% ls -d /net/neptune-gw/vobstore/src.vbs /net/neptune-gw/vobstore/src.vbs % ls -d /net/saturn/viewstore/view1.vws /net/saturn/viewstore/view1.vws % ls -d /net/neptune/vobstore/incl.vbs ... No such file or directory (no good; can't see neptune...) % ls -d /net/neptune-gw/vobstore/incl.vbs ( ...try again with neptune-gw) /net/neptune-gw/vobstore/incl.vbs % ls -d /net/dvalley/viewstore/view3.vws (storage on host in west region) /net/dvalley/viewstore/view3.vws . .For each VOB or view storage directory, make sure the same pathname “works” from all hosts in the new region.
Move some hosts to the new region—Use the procedure in “Moving a Host to a New Network Region”.
Log in to any host in the new network region—You need not be root, but you should know the network's VOB-tag password, in order to create public VOB-tags in the new region.
% rlogin sierra
Create VOB-tags for the new region—Each VOB can have at most one tag in a region. In a typical network with n regions, each VOB or view storage directory has n tag entries.
Note: A VOB or view need not have a tag in every region. However, a VOB or view is inaccessible for development work on hosts in any region for which it is “tagless”. This suggests that you might use network regions as “access domains” instead of “naming domains”. For a VOB or view to be visible in multiple network regions, it must have a separate tag entry for each region. However, the actual tag name (/vobs/src or proj2_main_view, for example) should be the same for all regions. The ideal is consistent, transparent access from any network region; this is possible only if the tag itself is constant across regions.
For example:
% cleartool mktag -vob -tag /vobs/src \ /net/neptune-gw/vobstore/src.vbs % cleartool mktag -vob -tag /vobs/incl \ /net/earth/vobstore/incl.vbs . .This command creates an entry for VOB /net/neptune-gw/vobstore/src.vbs, for region west, in the vob_tag registry file. (Because we are in the target region, the -region argument to mktag is not required.)
Note: The mktag command may fail if the VOB does not currently have a tag entry for its storage host's network region. Verify the new VOB-tags—On a host in the west region:
% cleartool lsvob -long
On a host in a different region:
% cleartool lsvob -long -region west
To verify the correctness of your work in Step #5, mount each shared VOB from a host in the west region. For example:
% cleartool mount /vobs/src
If access fails, and your network connection to the VOB storage host is good: use the guidelines in this chapter and in Chapter 6, “Ensuring the VOB's Global Accessibility”, to determine whether to supply new access path information for the VOB, using the -host, -hpath, and -gpath arguments to mktag.
Create view-tags for the new region—On a host in the west region, for each shared view:
% cleartool mktag -view -tag view1 /net/saturn/viewstore/view1.vws % cleartool mktag -view -tag view3 /net/dvalley/viewstore/view3.vws . .
Verify the new view-tags—On a host in the west region:
% cleartool lsview -long
On a host in a different region:
% cleartool lsview -long -region west
To verify the correctness of your work in Step #7, activate each view from a host in the new region.
% cleartool startview view1
If access fails, and your network connection to the view storage host is good: use the guidelines in this chapter (and in chapters this one references) to determine whether to supply new access path information for the view, using the -host, -hpath, and -gpath arguments to mktag.
This completes the procedure for adding a new network region. From this point on, each new shared VOB or view created on the network requires a tag entry for each region. That is, if a new VOB or view is created anywhere on the network, and it must be visible to hosts in both the east and west regions, you must execute an additional mktag command. For example:
After creating VOB /vobs/lib on neptune in the east region:
% cleartool mktag -vob -tag /vobs/lib -region west \ /net/neptune-gw/vobstore/src2.vbs
After creating view view4 on host dvalley in the west region:
% cleartool mktag -view -tag view4 -region east \ /net/dvalley/viewstore/view4.vws
| Note: Following the guidelines set out in this chapter, you would log in to a host in the target region before executing the mktag command. This makes the -region option unnecessary. |
Once network regions are established, moving a host from one region to another (to balance the network load between two interface cards, for example) is straightforward. The following steps move host niagra to the west region:
Verify VOB and view access paths—Make sure that the tag registry entries for the west region are valid on niagra as well. List all VOBs and views registered in the west region.
% cleartool lsvob -long -region west . . Tag: /vobs/src Global path: /net/neptune-gw/vobstore/src.vbs . . % cleartool lsview -long -region west . . Tag: main Global path: /net/saturn/viewstore/view1.vws . .
On niagra, verify the global access paths.
% ls -d /net/neptune-gw/vobstore/src.vbs /net/neptune-gw/vobstore/src.vbs % ls -d /net/saturn/viewstore/view1.vws /net/saturn/viewstore/view1.vws . .
Log in as root on the host to be moved.
Stop ClearCase processing.
% /etc/rc.atria stop (startup/shutdown command is architecture-dependent)Change the region assignment—Put the new region name into file /usr/adm/atria/rgy/rgy_region.conf.
% echo west > /usr/adm/atria/rgy/rgy_region.conf
Restart ClearCase processing.
% /etc/rc.atria start
At some point, you may want to dissolve a network region and re-incorporate its hosts back into one or more existing regions. Move each host to its “new” region as described in the preceding paragraph. Then, delete the region's VOB-tags and view-tags with rmtag.
Following are some general tips, warnings, and guidelines regarding ClearCase storage registry administration:
You cannot access a VOB or view (even to remove it) unless it has both a tag registry entry and an object registry entry. Use lsvob or lsview to see if either the tag is missing (no listing at all) or the object entry is missing (no storage paths appear in the -long output).
If you cannot access a VOB or view, first make sure it has a tag. If it does not appear in the output of an lsvob/lsview command, it has no tag. Create one with mktag.
If it has a tag, list the tag with lsvob -long or lsview -long. If the output includes incorrect pathnames (identical local and global pathnames usually mean trouble), you can try to re-register the object (with mktag and/or register) to supply correct pathnames. If everything looks OK, contact Atria Customer Support.
Don't use full pathnames in links on VOB or view hosts. The global pathname may be unresolvable for non-local hosts. For example:
/usr/vobs -> /usr/vobstore
Wrong. When this link is resolved on a client host, the full pathname “/usr/vobstore” references the /usr directory on the client host./usr/vobs -> ../vobstore
Right. When this link is resolved on a client host, the relative pathname “../vobstore” references a location on the VOB host.Similarly, beware of full pathnames in VOB symbolic links that point to locations in other VOBs.
On VOB and view hosts, watch out for links to unexported disk partitions. If you cannot access a VOB and suspect a faulty registry pathname, follow the registered global pathname to the storage host and pwd to see where you are. Make sure a link does not point to a location in an unexported partition. For example:
/usr/vobs -> ../vobstore
This link causes failures if the location “/usr/vobstore” is in another partition which is not exported.Don't rm a storage directory; this doesn't clean up the registry entries.
Don't delete tags as a precursor to deleting the storage directory; let rmvob or rmview delete tags for you.
When creating a VOB or view, creating a VOB-tag or view-tag, registering or unregistering a storage directory, or reformatting a VOB—especially when using the -host/-hpath/-gpath triplet—execute the command on the host where the VOB or view storage directory resides. This enables ClearCase to perform some pathname validations, which it cannot perform when the command is executed from a remote host.
Don't administer VOBs and views from a host running ClearCase Release 1.1.x. This will leave the storage registry in an inconsistent state. For example, deleting a VOB using ClearCase Release 1.1.x fails to remove vob_tag and vob_object registry entries. The deleted VOB appears in lsvob output, even though its storage directory no longer exists. In addition, the VOB scrubbing utilities scrubber and vob_scrubber use the vob_object entry to locate the VOB. They will report errors when they fail to find the deleted storage directory.
Use the same VOB-tags for all network regions. Each VOB or view that must be visible in multiple network regions must have a separate tag entry for each region. However, the tag name (/vobs/src or proj2_main_view, for example) should be the same for all regions. The goal is consistent, transparent access from any network region; this is possible only if the tag is constant across regions.
Use consistent naming conventions for directories that hold VOB mount points, and for directories that store VOB/view storage directories.
Create VOBs and views, VOB-tags and view-tags, from a host in the network region to which the tag applies.
Don't remote VOB storage pools for a VOB that must be accessed by hosts in more than one network region. The remote storage pool pathname must apply to all hosts that will access the VOB, but the existence of multiple network regions implies that different sets of pathnames are required to access VOBs from different hosts in the network. To repeat, if you use a remote storage pool for a shared VOB, the pool must be accessible from all hosts, in all regions, using the same global pathname.
You can isolate an arbitrary group of hosts with a separate network region, or by setting up a separate registry host with its own registry files and assigning the desired hosts to the new registry. It is more common to use a network region for this purpose, as reassigning hosts to a new registry renders all VOBs and views in the pre-existing registry invisible to the reassigned hosts.
A VOB's first tag (the one created by mkvob) must be in the “home region”—the region in which the VOB host resides. The same restriction applies to a view's first tag. You can then create additional tags for other regions, but make sure that a “home region” tag always exists.