4.4 Replica-Creation Scenario

The replica-creation example in this section uses a fictional company whose software development takes place in Boston, Massachusetts and in a new development office in San Francisco, California. Work is about to begin on a new release.

Planning the Rules of the Road

The organization uses a common ClearCase software development strategy:

• Individual subprojects, and often individual developers, use separate subbranches. The auto-make-branch facility is used in all config specs, to place changes on the appropriate branches. For example:

element * CHECKEDOUT
element * .../sanfran_main/LATEST
element * SANFRAN_BASE -mkbranch sanfran_main
element * V1.0 -mkbranch sanfran_main
element * /main/0 -mkbranch sanfran_main

• The v2.0_integration branch is reserved for integration of the work done at the various sites. To prepare for an internal baseline or an external release, the project manager merges selected development subbranches into the v2.0_integration branch.

• When necessary, developers merge changes from the v2.0_integration branch to their subbranches, to bring themselves up to date with changes occurring on the integration branch.

With Rational ClearCase MultiSite, the organization can continue to use this strategy. The Boston replica masters the v2.0_integration branch. The San Francisco replica masters a branch named sanfran_main, as well as any additional subbranches of sanfran_main that may be needed to organize the work there. The project manager at the Boston site merges changes from the sanfran_main and boston_main branches into the v2.0_integration branch, so that the release engineers can build the product using the latest changes.

Relevant characteristics of the two replicas:

The company has not yet merged its user/group databases, so the two replicas cannot be ownership-preserving. There is IP connectivity between the two offices, so the Boston administrator can use the MultiSite store-and-forward facility to create the new replica.

Prerequisites

Before you create a new replica, you must perform these steps at the original site:

1. Make sure MultiSite licenses are installed.

After you enter the mkreplica -export command, developers at the original site cannot access the VOB without a MultiSite license (in addition to a ClearCase license).

clearlicense -product MultiSite
Licensing information for MultiSite.
License server on host "cclicense".
Running since Thursday 07/01/00 12:27:28.

LICENSES:
Max-Users Expires Password [status]
300 none 34ms5678.901234c5.67 [Valid]
...

2. Apply a version label, from which development work at the new replica will branch.

In the standard ClearCase manner, a consistent set of source versions (a baseline) is identified by a version label. The VOB administrator creates label type SANFRAN_BASE and attaches it to all the /main/LATEST versions in the original VOB. The changes at sanfran_hub are made on sanfran_main branches; all these branches are created at SANFRAN_BASE versions.

3. Rename the original replica appropriately.

Even though the original VOB has not yet been replicated, its VOB database still has a VOB replica object, named original:

MINUTEMAN% cleartool lsreplica -invob /vobs/dev
For VOB replica "/vobs/dev":
15-Aug.14:19 susan replica "original"

The administrator renames the VOB replica object to boston_hub:

MINUTEMAN% multitool rename replica:original boston_hub
Renamed replica from "original" to "boston_hub".

MINUTEMAN% cleartool lsreplica -invob /vobs/dev
For VOB replica "/vobs/dev":
15-Aug.14:19 susan replica "boston_hub"

4. Make sure the VOB is not locked.

Step #6 locks the VOB; an error occurs if the VOB is already locked.

MINUTEMAN% cleartool lslock vob:/vobs/dev
MINUTEMAN% (null output indicates VOB is not locked)

5. Determine the size of the VOB database and source pools.

The directory you specify with the -workdir option must be on a partition that has enough free space to hold the VOB database and the VOB source pools. You must have write permission on its parent directory, and the directory you specify must not exist.

To determine the size of the VOB database and source pools, use cleartool space:

cleartool space /vobs/dev
Use(Mb) %Use Directory
...
1429.0 17% VOB database /vobstg/dev.vbs/db
...
189.5 2% source pool /vobstg/dev.vbs/s/sdft
...

In this example, the work directory must have at least 1.62 GB of free space.

Export Phase

These steps take place at the original site.

1. Enter the export form of the replica-creation command. See the mkreplica reference page for information about restrictions on the command.

In this example, the administrator uses the -fship option to send the packet immediately.

MINUTEMAN% multitool mkreplica -export -work /tmp/ms_wkdir \
-fship goldengate:sanfran_hub@/vobs/dev
Enabling replication in VOB.
Comments for "sanfran_hub":
First time replication for dev VOB
Creating new replica, sanfran_hub, on host goldengate
.
Generating replica creation packet /usr/atria/shipping/ms_ship/outgoing/repl_boston_hub_16-Aug-00.09.49.36_14 075_1
- shipping order file is /var/adm/atria/shipping/ms_ship/outgoing/sh_o_repl_boston_hub_16-Aug-00.09 .49.36_14075_1
Dumping database...
...
Dumper done.
Attempting to forward/deliver generated packets...
-- Forwarded/delivered packet /usr/atria/shipping/ms_ship/outgoing/repl_boston_hub_16-Aug-00.09.49.36_14 075_1

2. Back up the original VOB.

This backup records the fact that the VOB is replicated. If you have to restore a VOB replica from a backup copy that was made before the VOB was replicated, the MultiSite replica restoration procedure fails. (Although the restorereplica command may succeed, you will not be able to import update packets from other replicas because the original VOB is marked as unreplicated.)

3. (optional) Verify the replica-related changes.

These commands show the work you've done so far. The mkreplica command creates a new replica object in the VOB database. This object is similar to the VOB object that represents the entire VOB in the database, and its properties are listed by the lsreplica command.

MINUTEMAN% multitool lsreplica -invob /vobs/dev
For VOB replica "/vobs/dev":
15-Aug.14:19 susan replica "boston_hub"
16-Aug.09:49 susan replica "sanfran_hub"

MultiSite commands process replica objects similarly to the way that ClearCase commands process type objects. The rename command renames a replica object, as described in Step #3. The cleartool lshistory lists events associated with replica objects.

MINUTEMAN% cleartool lshistory replica:boston_hub@/vobs/dev
16-Aug.09:45 susan rename replica "boston_hub"
"Changed name of replica from "boston" to "boston_hub"."
15-Aug.14:24 susan rename replica "boston_hub"
"Changed name of replica from "original" to "boston"."
15-Aug.14:19 susan make attribute "FeatureLevel" on replica "boston_hub"
"Added attribute "FeatureLevel" with value 2."
15-Aug.14:19 susan create replica "boston_hub"

CAUTION: Do not modify any properties of the new replica at this point. If you must change any properties, you must first import the replica-creation packet at the new site, export an update packet from the new replica, and import the packet at the original site.

Transport Phase

1. Send the replica-creation packet to the new site. This process differs depending on the options you used in Step #6:

• If you used -fship in Step #6, the packet was sent to the new site immediately.

• If you used -ship, you must run shipping_server to send the packet to the new site. For example:

MINUTEMAN% /usr/atria/etc/shipping_server -poll

• If you used -tape or wrote the packet to a file, you must transport the tape or file to the new site.

Import Phase

Complete these steps at the new replica's site.

1. Verify the packet's arrival by entering the lspacket command on the receiving host.

By default, lspacket searches all the MultiSite storage bays for packets. For example, if host goldengate is the receiving host:

GOLDENGATE% multitool lspacket
Packet is: /usr/atria/shipping/ms_ship/incoming/repl_boston_hub_16-Aug-00.09.49.36_14 075_1
Packet type: Replica Creation
VOB family identifier is: 12a3456b.78c901d2.e3ab.45:67:89:c0:1d:e2
Comment supplied at packet creation is:
Packet intended for the following targets:
sanfran_hub
The packet sequence number is 1

2. Enter the import form of the replica-creation command.

Notes on replica creation:

• This replica is not ownership-preserving, so the user who executes this command becomes the owner of the new VOB replica and all elements in it. This user's primary group is the group for all elements. Typically, administration is easier if this user is not the root user or a member of the ClearCase administrators group.

• As described in Step #5, the work directory must have at least 1.62 GB of free space.

• You can bypass the prompt step during replica creation by specifying the -vreplica option with the new replica's name. This example does not specify that option.

• You must specify the pathname of the incoming packet as listed by the lspacket command.

GOLDENGATE% multitool mkreplica -import -npreserve -work /tmp/wk \
-tag /vobs/dev -public -password 1234xyz -vob /vobstg/dev.vbs \
/usr/atria/shipping/ms_ship/incoming/repl_boston_hub_16-Aug-00.09.49.36_14075_1
The packet can only be used to create replica "sanfran_hub"
- VOB family is 87f6265b.72d911d4.a5cd.00:01:80:c0:4b:e7
- replica OID is 0eaa6fc3.737d11d4.adbe.00:01:80:c0:4b:e7
Should I create this replica? [no] yes
Comments for "sanfran_hub":
replica of /vobs/dev from Boston
.
Processing packet /usr/atria/shipping/ms_ship/incoming/repl_boston_hub_16-Aug-00.09.49.36_14 075_1...
Loading database...
Dumped schema version is 53
55 events loaded.
77 pass 2 actions performed.
Loader done.
Registering VOB mount tag "/vobs/dev"...
VOB replica successfully created.
Host-local path: goldengate:/vobstg/dev.vbs
Global path: /net/goldengate/vobstg/dev.vbs
VOB ownership:
owner purpledoc.com/jcole
group purpledoc.com/user

3. Delete the replica-creation packet. (Update packets are deleted automatically.)

4. (Only if new replica is ownership-preserving) Send an update packet to all other replicas in the VOB family.

If you create an ownership-preserving replica, inform other replicas in the VOB family of this property. For example, if sanfran_hub were ownership-preserving, you would enter this command:

GOLDENGATE% multitool syncreplica -export -c "ownership-preserving" -fship boston_hub
...

5. Make the new replica self-mastering. See Transferring Mastership of a Replica Object for the procedure.

You must complete this step before you can set the new replica's feature level or enable requests for branch mastership at the replica.

6. Set the feature level of the new replica to the feature level of the version of Rational ClearCase running on the replica host.

To determine the feature level of the version of ClearCase, enter the cleartool -ver command on the replica host to display the ClearCase version. Then consult the Release Notes for the feature level associated with the version.

To set the new replica's feature level, enter a chflevel command on the replica host:

cleartool chflevel -replica feature-level replica-selector

For example:

cleartool chflevel -replica 2 sanfran_hub@/vobs/dev
Replica feature level raised to 2.

7. Send an update packet to all other replicas in the VOB family, to inform them of the new replica's feature level. For example:

GOLDENGATE% multitool syncreplica -export -c "new feature level" -fship boston_hub
...

8. Create a branch type for work in the new replica.

The San Francisco developers work on the sanfran_main branch type.

GOLDENGATE% cleartool mkbrtype sanfran_main
Comments for "sanfran_main":
sanfran branch for work on dev project
.
Created branch type "sanfran_main".

Subbranches named sanfran_main are created as necessary. The following config spec automates the creation of the sanfran_main branches:

element * CHECKEDOUT
element * .../sanfran_main/LATEST
element * SANFRAN_BASE -mkbranch sanfran_main
element * V1.0 -mkbranch sanfran_main
element * /main/0 -mkbranch sanfran_main

This config spec is defined in terms of a branch type (sanfran_main) that is mastered by replica sanfran_hub, and label type (SANFRAN_BASE and V1.0) that are mastered by replica boston_hub. The San Francisco developers cannot make any changes in the SANFRAN_BASE labels, but there is no reason for them to do so.

9. Verify the mastership of the new branch type.

GOLDENGATE% cleartool describe brtype:sanfran_main@/vobs/dev
branch type "sanfran_main"
created 16-Aug-00.18:12:23 by John Cole (jcole.user@goldengate)
"sanfran branch for work on dev project"
master replica: sanfran_hub@/vobs/dev
...

10. (For IP-connected replicas) At each site, mark any sibling replicas that have IP connectivity to the current replica. For more information, see Setting the Connectivity Property.

At the boston_hub replica:

multitool chreplica -isconnected sanfran_hub@/vobs/dev
Updated replica information for "sanfran_hub".

At the sanfran_hub replica:

multitool chreplica -isconnected boston_hub@/vobs/dev
Updated replica information for "boston_hub".

11. Begin development.

Developers in San Francisco can access the new replica in the same way they would access an unreplicated VOB.