26.2 Adding a Network Region

Ensuring Global Access to the VOB-Special Cases for UNIX outlines the circumstances that may require you to adjust the registry entry generated for a VOB or view. That section presents 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 addresses the situation in which 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.

NOTE: The most common multiple region scenario involves a mixed network environment of Windows and UNIX hosts. If you are working in, or planning, such an environment, read the remainder of this section to acquaint yourself with the procedure for adding a network region. Then use procedures described in Chapter 7, Configuring VOB and View Access in Mixed Environments, to perform the actual work of registering VOBs and views.

When to Create Additional Regions

There are several aspects of a computer network that may require you to create one or more additional registry regions:

• Multiple host architectures. Network naming conventions differ between UNIX and Windows. If you have to support ClearCase on both UNIX and Windows hosts, you will need at least two registry regions. For example, a VOB that is accessed as /net/neptune/vobstore/incl.vbs on a UNIX host may be accessed as \\neptune\vobstore\incl.vbs on a Windows host.

• Multiple network interfaces. A UNIX or Windows VOB host or view host may have two or more interfaces to the network, each corresponding to a different host name. A VOB with storage on such a host will have one global storage pathname for each network interface (and host name) the host supports. For example, for a host with two interfaces and two names (neptune and neptune-gw), the global storage path to a VOB with local storage at /public/project.vbs is different for each host name:

/net/neptune/public/project.vbs
/net/neptune-gw/public/project.vbs

• UNIX hosts with multiple aliases. The standard UNIX facilities for assigning names to hosts-file /etc/hosts or NIS map hosts-allow each host to have any number of alternate names, or aliases. This is a possible hosts entry:

195.34.208.17 betelgeuse bg (alias)

If shared storage resides on this host, ClearCase clients may be able to access the storage using either a /net/betelgeuse/... pathname or a /net/bg/... pathname.

There is another partitioning scenario with a different focus: you want to prevent, not promote, VOB and view sharing. You can create a separate region-or even a separate registry, served by a second registry host-to administer a cluster of hosts for which some or all VOBs and views visible in another region are not registered and, hence, not visible.

Multiple locales. ClearCase supports use of multibyte characters in VOB-tags and view-tags. Because the interpretation of multibyte characters is controlled by a host's locale setting (established on UNIX through the LOCALE environment variable and on Windows using the Regional Options tool in Control Panel), all hosts in a region must use the same locale setting or they will not be able to interpret multibyte VOB-tags and view-tags correctly.

No matter how many regions you have, each ClearCase host can belong to only one region.

Multiple Regions vs. Multiple Registries

Instead of, or in addition to, creating multiple network regions in a single ClearCase registry, you can construct a network with multiple registry hosts, each serving separate clusters of ClearCase hosts that may or may not share VOBs and views. This approach complicates the administration process; it is not recommended unless specific circumstances require it.

The procedures here are intended primarily to support single registry installations and offer only basic guidance for multiple registry (as opposed to multiple region) sites. Some general guidelines are available in the section Multiple Registries.

A Example Using Network Regions

Figure 36 illustrates a mixed-architecture (Windows and UNIX) network. There are two network regions, one for Windows hosts and one for UNIX hosts. Two regions are required because UNIX servers store VOBs and views that must be accessed by all network hosts. In this example, hosts in both regions use the same view-tags, but not the same VOB-tags. Furthermore, each region's hosts access VOB and view storage using different pathnames. Therefore, separate tag registry entries are required.

Figure 36 Sample Network with Two Regions

Procedure for Adding a Network Region

Use this procedure to create one or more additional regions after your first region has been created. This procedure assumes that these conditions are true:

• ClearCase has been installed on each host.

• VOBs and views have been created on the region's VOB and view storage hosts.

To Create a New Region

Use the ClearCase Administration Console to create a new region (in this example, the region is named dev_nt):

1. Start the ClearCase Administration Console.

2. Navigate to the Regions subnode of the ClearCase Registry node.

3. Click Action > New > Region Tag. This command opens a dialog box in which you create the new region.

You can also use the mkregion command to create region dev_nt:

cleartool mkregion -tag dev_nt -tcomment "Windows ClearCase hosts"

To Move a Host into a New Registry Region

A ClearCase host's default region and registry server are established when ClearCase is installed. To move the host into a different region served by the same registry server:

• On a UNIX host, edit the file /var/adm/atria/rgy/rgy_region.conf to contain the name of the new region. You must be logged in as root to change this file.

• On a Windows host use the Registry tab of the ClearCase program in Control Panel to specify the new region.

• Stop ClearCase on the host.

• Restart ClearCase on the host.

To Change a Host's Registry Server

To move the host into a region served by a different registry server:

• On a UNIX host, edit the file /var/adm/atria/rgy/rgy_hosts.conf to contain the name of the new registry host and optional backup registry host, then edit the file /var/adm/atria/rgy/rgy_region.conf to contain the name of a valid region on the new host. You must be logged in as root to change these files.

• On a Windows host, run Control Panel and click the Registry tab of the ClearCase program to specify the new Registry server host and region.

• Stop ClearCase on the host.

• Restart ClearCase on the host.

You can verify that the new region assignment is in effect by running the hostinfo command to display the current registry host and network region.

cleartool hostinfo -long

NOTE: If a host has been configured to allow remote administration, you can also use the host node of the ClearCase Administration Console to change the host's region, though you cannot use the ClearCase Administration Console to stop or start ClearCase on a host.

To Create VOB-tags and View-tags in a New Network Region

There are several ways to populate a newly created registry region with VOB-tags and view-tags:

• The Region Synchronizer, a Windows GUI, makes it easy to import VOB-tags and view-tags from a UNIX region to a Windows region. To start the Region Synchronizer, click Start > Programs > Rational ClearCase Administration > Region Synchronizer.

• The ClearCase Administration Console provides a more general interface to regions and tags. The ClearCase Administration Console is a Windows GUI that runs on Windows. It can be used to manipulate tags regardless of whether the registry host is running UINX or Windows. You can use it to create and delete tags, and also to copy tags to another region. When you use ClearCase Administration Console to manipulate tags, you must be careful to change the global paths of the new tags you create in this way to ensure that they are valid in the new regions. (The Region Synchronizer automates this operation for the specific case of importing a tag from a UNIX region to a Windows region.) To start the ClearCase Administration Console, click Start > Programs > Rational ClearCase Administration > ClearCase Administration Console.

• You can use the cleartool mktag command, as described in Using mktag.

Using mktag

VOB-tags and view-tags are created for the new region using mktag commands of the form:

cleartool mktag -vob -tag vob-tag -region new-network-region
-host host name
-hpath host-local-pathname
-gpath global-pathname
storage-dir

cleartool mktag -view -tag view-tag -region new-network-region
-host host name
-hpath host-local-pathname
-gpath global-pathname
storage-dir

For example, host nt1 in Figure 36 accesses a UNIX VOB through VOB-tag \vob_src, which was created for the dev_nt region with the following command:

cleartool mktag -vob -tag \vob_src -region dev_nt ^
-host saturn ^
-hpath /vobstore/src.vbs ^
-gpath \\saturn\vobstore\src.vbs ^
\\saturn\vobstore\src.vbs

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 dev_unix and dev_nt regions, you must use the ClearCase Administration Console or an additional mktag command to create a new tag in the second region. For example:

• After creating VOB /vobs/lib on saturn in the dev_unix region

cleartool mktag -vob -tag \lib ^ (Create, for all Windows hosts
-region dev_nt ^ in the dev_nt region, a VOB-tag
-host saturn ^ registry entry for the VOB
-hpath /vobstore/lib.vbs ^ whose storage directory resides
-gpath \\saturn\vobstore\lib2.vbs ^ at \\saturn\vobstore\lib.vbs)
\\saturn\vobstore\lib.vbs

The mktag command can be executed on a UNIX host. But the final argument, used by mktag itself to find the storage directory, is different on UNIX-/vobstore/lib.vbs, for example, rather than \\saturn\vobstore\lib.vbs.

• After creating view view4 on host nt2 in the dev_nt region

Do nothing. UNIX hosts cannot use Windows views, so there is no need to create a new tag for the dev_unix region.

NOTE: There must be separate tag entries for each region, but actual tag names (\src or \vob_src, myview or r2.1_view, for example) should, if possible, be the same for all regions. The ideal is consistent, transparent VOB access from any network region. However, this ideal may be impractical in some environments, because Windows VOB-tags are limited to a single pathname component.

If the New Region Is Served by a Different Registry Host

If the new region belongs to a different ClearCase registry (that is, the region is served by a separate registry host):

• You cannot use the Region Synchronizer to create tags for the new region.

• In addition to mktag, you must also use the ClearCase Administration Console or the register command to add entries to the second registry's VOB or view object file (vob_object or view_object). For example:

cleartool register -view \\saturn\viewstore\view1.vws

Guidelines for Multiple Network Regions

• If possible, use the same VOB-tags in all network regions. Each VOB or view that must be visible in multiple network regions must have a separate tag entry in each region. Making the name the same for all regions provides consistent, transparent access from any network region.

• Use consistent naming conventions for directories that hold UNIX VOB mount points and for directories that store VOB or view storage directories.

• Don't use remote VOB storage pools for a UNIX VOB that must be accessed by hosts in more than one network region. 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 either 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 (and easier to administer) to use a network region for this purpose.

• A VOB's first tag (the one created by the VOB Creation Wizard or 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.