Replica-Creation Scenario for a VOB


For the example in this section, the company’s 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 company uses the following development strategy:

With Rational ClearCase MultiSite, the organization can continue to use this strategy. The Boston replica masters the v2.0_integration branch type. The San Francisco replica masters a branch type named sanfran_main, as well as any additional branch types 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:

Boston replica
 
Host name
minuteman (UNIX)
Replica name
boston_hub
VOB storage directory
/vobstg/dev.vbs
VOB tag
/vobs/dev
Config spec for development
element * CHECKEDOUT
element * .../boston_main/LATEST
element * BOSTON_BASE –mkbranch boston_main
element * V1.0 –mkbranch boston_main
element * /main/0 –mkbranch boston_main
Config spec for integration
element * CHECKEDOUT
element * .../v2.0_integration/LATEST
element * BOSTON_BASE –mkbranch v2.0_integration
element * V1.0 –mkbranch v2.0_integration
element * /main/0 –mkbranch v2.0_integration

San Francisco replica
 
Host name
goldengate (UNIX)
Replica name
sanfran_hub
VOB storage directory
/vobstg/dev.vbs
VOB tag
/vobs/dev
Config spec for development
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 company has not yet merged its user/group databases, so the two replicas cannot preserve identities. Because the administrators want to preserve changes to permissions, they decide to make the replicas permissions 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 VOB replica, you must perform these steps at the original site:

  1. Make sure MultiSite licenses are installed.
  2. After you enter the mkreplica –export command, developers who use the original VOB cannot access it 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]
    ...
  3. Apply a version label, from which development work at the new replica will branch.
  4. 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 the appropriate 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.

  5. Rename the original replica appropriately.
  6. Even though the original VOB has not yet been replicated, its VOB database 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"
  7. Make sure the VOB is not locked.
  8. 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) 
  9. Determine the size of the VOB database and source pools.
  10. The directory you specify with the –workdir option in the mkreplica command 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 the cleartool space command:

    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 combined size of the VOB database and source pool is 1.62 GB, so 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 mkreplica command. For information about restrictions on the command, see the mkreplica reference page.
  2. In this example, the administrator uses the –fship option to send the packet immediately.

    MINUTEMAN% multitool mkreplica –export –workdir /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 
    /opt/rational/clearcase/shipping/ms_ship/outgoing/repl_boston_hub_1
    6-Aug-00.09.49.36_14075_1
    - shipping order file is 
    /var/adm/rational/clearcase/shipping/ms_ship/outgoing/sh_o_repl_bos
    ton_hub_16-Aug-00.09.49.36_14075_1
    Dumping database...
    ...
    Dumper done.
    Attempting to forward/deliver generated packets...
    -- Forwarded/delivered packet 
    /opt/rational/clearcase/shipping/ms_ship/outgoing/repl_boston_hub_1
    6-Aug-00.09.49.36_14075_1
  3. Back up the original VOB.
  4. 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.)

  5. (optional) Verify the replica-related changes.
  6. 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 command 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 "original" to "boston_hub"."
    15-Aug.14:19   susan     make attribute "FeatureLevel" on replica 
    "boston_hub"
    "Added attribute "FeatureLevel" with value 2."
    ...

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 replica.

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, 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% /opt/rational/clearcase/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 running lspacket on the receiving host.
  2. 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: 
    /opt/rational/clearcase/shipping/ms_ship/incoming/repl_boston_hub_1
    6-Aug-00.09.49.36_14075_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
  3. Enter the import form of the replica-creation command.
  4. Notes on the import phase of replica creation:

    • This replica is permissions 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 Should I create this replica? prompt during replica creation by specifying the –vreplica option with the new replica’s name. This example does not specify that option.
    • If you create a permissions-preserving replica, you can bypass the prompt during replica creation by specifying the –nprompt option with the –perms_preserve option. 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 –perms_preserve –work /tmp/wk 
      –tag /vobs/dev  –public –password 1234xyz –vob /vobstg/dev.vbs 
      /opt/rational/clearcase/shipping/ms_ship/incoming/repl_boston_hub_16-Aug-00
      .09.49.36_14075_1 
      multitool: Warning: In a permissions-preserving replica, cleartool 
      protect operations will fail on client machines running ClearCase 
      versions associated with feature level 3 or lower.
      Should I create a permissions-preserving replica? [no] yes 
      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 
      /opt/rational/clearcase/shipping/ms_ship/incoming/repl_boston_hub_1
      6-Aug-00.09.49.36_14075_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
  5. Delete the replica-creation packet. (Update packets are deleted automatically.)
  6. (If new replica preserves identities and permissions) Make sure that the owner, group, and group list of the new VOB are the same as the owner, group, and group list of the other identities- and permissions-preserving replicas in the VOB family. To change these values, run the cleartool protectvob command on the new VOB replica.
  7. (If new replica preserves identities and permissions or permissions only) Send an update packet to all other replicas in the VOB family.
  8. If you create a preserving replica, inform other replicas in the VOB family of this property. For example, sanfran_hub preserves permissions, so the San Francisco administrator enters this command:

    GOLDENGATE% multitool syncreplica –export –c "permissions preserving" –fship 
    boston_hub 
    ...
  9. Make the new replica self-mastering. See Transferring Mastership of a Replica Object for the procedure.
  10. You must complete this step before you can set the new replica’s feature level or enable requests for branch mastership at the replica.

  11. Set the feature level of the new replica to the feature level of the version of Rational ClearCase running on the replica host.
  12. 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 4 sanfran_hub@/vobs/dev 
    Replica feature level raised to 4.
  13. Send an update packet to all other replicas in the VOB family, to inform them of the new replica’s feature level. For example:
  14. GOLDENGATE% multitool syncreplica –export –c "new feature level" –fship 
    boston_hub 
    ...
  15. Create a branch type for work in the new replica.
  16. The San Francisco developers use branches of type sanfran_main.

    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), which is mastered by replica sanfran_hub, and label types (SANFRAN_BASE and V1.0), which are mastered by replica boston_hub. The San Francisco developers cannot create instances of the SANFRAN_BASE label type or move any existing SANFRAN_BASE labels, but there is no reason for them to do so.

  17. Verify the mastership of the new branch type.
  18. 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
    ...
  19. (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 for a VOB Replica.
  20. 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".
  21. Begin development.
  22. Developers in San Francisco can access the new replica in the same way they access an unreplicated VOB.