IBM Support

How to move a VOB using ClearCase MultiSite

Question & Answer


Question

How do you move an IBM Rational ClearCase VOB using ClearCase MultiSite commands where the move may involve a combination of Microsoft Windows, UNIX or Linux VOB servers?

Answer

INTRODUCTION:

This technote outlines the general procedures for moving a VOB that is not currently MultiSited to a new host using MultiSite commands and provides information about some Pros and Cons of using this method. The following procedures are meant to provide the basic steps involved in moving a VOB using MultiSite. However, the ClearCase and ClearCase MultiSite documentation should be consulted for full details regarding any command usage, restrictions and syntax suggested throughout this document.


Using MultiSite replication to move a VOB from one host to another can be a time saver that will allow you to avoid manually dumping the VOB database, moving the VOB storage, loading the VOB database on the target host, and re-protecting all the VOB objects and underlying containers.

The MultiSite approach has little risk, and involves 2 primary steps: mkreplica -export and mkreplica -import. You will need a minimum of 1 MultiSite license per server to accomplish this task.

Note: If the VOB remains replicated at the end of these procedures, MultiSite licenses will be required for all users who will be accessing the VOB. The steps assume that this is a 1 way move, and that you wish to de-replicate all VOBs after having "moved" them to the new host. The resulting VOBs will not draw MultiSite licenses once complete.


These instructions can assist you if you're planning to move a VOB :
  • From one host to another (same operating system)
  • From one Windows Domain (DOM1) to another Windows domain (DOM2) (this includes moves from NT to Active Directory domains)
  • From one UNIX/Linux NIS to a different UNIX/Linux NIS
  • From a Windows host to UNIX/Linux machine or vice versa
  • From one UNIX OS (Solaris) to a different UNIX OS (HP)
  • From a host with an OLD version of ClearCase (2003.06.00) to a host with a newer version (7.0).


PROS:

  1. Less error prone: The steps to move a VOB without MultiSite require a copy utility to be used and in some cases (especially on Windows) the permissions of the VOB storage may need to be repaired. Not so with MultiSite.
  2. Performs database integrity check. MultiSite performs a dump and load of the database as part of the replica creation process. This process in essences tests the health of the database verifying its integrity, for an unhealthy database will often fail during the dump or load phases.
  3. Schema Upgrades: If you require a database schema upgrade, using MultiSite can facilitate the change while moving the VOB so that additional reformatvob commands can be avoided.
  4. Continued work in the original VOB: Users can continue to work in the original VOB while the replica is copied to the new host and set up. Once the setup is complete the user's work can be checked in and a final synchronization packet can be sent to the new host before taking the original VOB replica off line. Note that MultiSite licenses will be required for users to continue working in this VOB during the procedure.
  5. Spring Cleaning: If you want to change the ownership or groups of all the objects in the VOB, this is the time to do it. If you want to regain all the space in the database from the removed metadata over the months and years, this is your opportunity.



CONS:

  1. There are objects (including the following) that MultiSite will not copy or migrate to the new VOB:
  • Locked objects (cleartool lock) will not replicate
    Note: Obsolete locks [cleartool lock -obsolete] will replicate.
  • Trigger types and instances do not replicate and will need to be recreated in the new VOB when the operation is complete.
  • Trigger scripts
  • Non-versioned DOs (derived objects)
  • Custom element types and type managers
  • per-vob vob_scrubber_params file (vob_scrubber)
  • Refer to the Information propagated among VOB replicas section of the ClearCase MultiSite Administrator's Guide for further details regarding what information is and is not propagated among replicas.
  • 1. User and Group protections are not propagated if replicating between two different Windows domains, between Windows and UNIX or Between two UNIX servers with different users and groups. See the vob_sidwalk command in the ClearCase information center.

    2. You will require at least one MultiSite license will need to be available at each replica until the operation has been completed and the VOB has been dereplicated by removing the last replica in the family.

    Note:
    If you require a temporary MultiSite license, contact your designated sales representative for assistance.

    3. You need to consider disk space requirements for the new VOB and temporary workspace which could be an issue if you are replicating a large VOB. Refer to the IBM Rational ClearCase MultiSite Administrators Guide on the topic of mkreplica for further information.





VOB MOVE PROCEDURES:

Things to consider before the VOB move:

  • If you plan on moving the VOB in one pass where the source VOB will no longer be updated, you should resolve all checkouts from the source VOB prior to the move by checking in all work since view private objects in the views will not be moved.
  • Lock the VOB and back it up
  • The VOB will have a soft lock on it when the mkreplica -export command performs a dump of the database, however, it is not a sufficient lock for making a backup. You should always lock and backup your VOB prior to any major administrative task.

    Refer to the Backing up critical Rational ClearCase data section of the ClearCase Administrator's Guide for further information about VOB backups.
  • Use cleartool lock vob:<vob-tag> to lock the VOB for the backup using the -nuser option to identify the user who will be running the MultiSite commands. If no further work is to be done in this VOB, then it should remain locked to ensure that no changes are made that won't be incorporated into the new VOB being created.
  • The objective for following these procedures is to move a VOB(s) to a new host. It is important that the source VOB is removed and no longer updated following it's successful move to the new host.
  • If you use UCM (PVOB/CVOB) or AdminVOB/ClientVOB model, then you must "move"/replicate all the associated VOBs.

    Refer to the Backing up related databases together section of the ClearCase Administrator's Guide for further information about related databases.
  • It is recommended to use the latest version of ClearCase on your target server. The target server must be running the same or a newer version of ClearCase than the source server.

  • Ensure MultiSite has been installed on both source and destination VOB servers. multitool -ver should display the Multisite version information. Note that MultiSite is not an optional component when using the ClearCase LT version of the product.

Performing the move:

The following steps assume that the original replica in on Windows and the target server is on a UNIX host and that the VOB is not currently replicated
  1. On the source VOB server:
  2. Perform the mkreplica -export command to create and export a copy of the source VOB.
    This will accomplish a VOB database dump and take along all necessary container data in the VOB storage.

    Example:
    multitool mkreplica -export -workdir c:\<some-temp-directory>\
    [-maxsize 100m] -fship <remotehostname>:<new-replica-name>
    @<existing-vob-tag-to-replicate>


    This also enables replication and is when MultiSite licenses will be drawn.
    Use of a manual transport (-ship or -copy) instead of -fship is also an option.
  3. On the target VOB server:
  4. If you used shipping_server to send the data, by default the packet(s) should have arrived in:
    UNIX or Linux: /var/adm/rational/clearcase/shipping/ms_ship/incoming
    Windows: c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\incoming

  5. Find the packet beginning with "repl_" this specifies a mkreplica packet.
    You can use the multitool lspacket command to find the name and location of the replica packet.

    Notes regarding the importing:
  • You want to log in with the appropriate user identity of the user who will own the VOB, and ensure that user's primary group, and all additional groups are correct prior to importing. The new VOB will take on this identity. cleartool protectvob can be used later to add or remove groups. Also, ensure your umask is set correctly, perhaps 002 would be appropriate. You will need to use -npreserve to avoid complication with identity preserving replicas when replicating between OS's with different user and group designations.

  • 1. Perform the mkreplica -import command to create the new VOB.

    Example:

    multitool mkreplica -import -workdir /var/tmp/doesntexist/ -tag
    /your/new/vobtag/ -stgloc -auto -npreserve -public /var/adm/atria/
    shipping/ms_ship/incoming/<repl_your_new_replica_packet>


    2. Ensure that the VOB has been created successfully and can be accessed by the user that performed the import. You should see the VOB listed in a cleartool lsvob output.


    3. If work had continued in the source VOB after the initial mkreplica -export, it will need to be sent in an update packet and imported into the new VOB. You need to check in all checked out files, then create and send a final synchronization packet from the source replica to the target replica where it should be imported.

    Example;

    At the source replica:
    multitool syncreplica -export -fship <target-replica>@<local-vobtag>

    At the target replica:
    multitool syncreplica -import /var/adm/rational/clearcase/shipping/ms_ship/incoming/sync_packet-name

    This will update the target replica with all the changes that were made at the source replica since the target VOB's creation.

    4. Transfer mastership of all objects to the new replica.

    This can be done over a period of time by transferring objects individually.
    See the chmaster page in the multitool section of the information center for more information.

    If you have a limited number of MultiSite licenses you can change mastership of everything to the new replica at once by adding the all switch to chmaster

    Example:
    multitool chmaster -all <new replica>

    Synchronize the change to the new replica.

    It is also possible to forcibly pull mastership at the new replicated by using the all and obsolete_replica switches.

    The following command will forcibly take mastership of all objects from the source replica. Once it is run no further changes should be sent to or from this replica.

    Example:

    multitool chmaster -all -obsolete_replica <source-site's-replica>
    @<local-vob-tag> <new-site's-replica>@<local-vob-tag>

    5. Remove the original replica from the new replica family.

    Example:

    multitool rmreplica replica:<source-site's-replica>@<local-vobtag>

    This is now a de-replicated VOB and will no longer require a MultiSite license.


    6. At the source site you'll also want to remove the target site's replica object from the family.

    multitool rmreplica replica:<target-site's-replica>@<vob-tag>


    7. Now verify that everything is working (try to checkout/checkin etc) in a view/VOB context at the target site.

    Note you may now want to upgrade the VOB to the most current feature level

    Example
    cleartool chflevel -replica 5 replica:<local-replica-name>@
    <local-vob-tag>
    cleartool chflevel -family 5 vob:<local-vob-tag>


    H. Once the operation has been completed verify that the target VOB contains everything needed (taking into consideration the list of objects that are not replicated and will need to be manually copied or recreated). Then remove the original replica using cleartool rmvob.
    Note if you used the obsolete_replica option the original replica will still see itself as replicated in which case rmvob may fail. If this is the case simply use cleartool rmtag and unregister commands and remove the vob storage directory with the appropriate operation system commands.



DOCUMENTATION

Refer to the IBM Rational ClearCase Administrators Guide on the topic of Moving VOBs for information about moving VOBs without the use of MultiSite.


[{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Documentation","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF015","label":"IRIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"7.0;7.0.1;7.1;7.1.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Documentation","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
29 September 2018

UID

swg21266219