mkreplica

Creates a replica

Applicability

Product Command type
MultiSite multitool subcommand
Platform
UNIX
Linux
Windows

Synopsis

  • Duplicate a VOB, generating a new replica object and a replica-creation packet:
    mkrep/lica
    –exp/ort –wor/kdir temp-dir-pname [ –max/size size ] [ –c/omment comment | –cfi/le comment-file-pname | –cq/uery | –cqe/ach | –nc/omment ] { { –sh/ip | –fshi/p } [ –scl/ass storage-class ] [ –pex/pire date-time ] [ –not/ify e-mail-addr] | –out packet-file-pname } hostname:replica-selector ...
  • Import a replica-creation packet to create a new VOB replica:
    mkrep/lica
    –imp/ort –wor/kdir temp-dir-pname –tag vob-tag { –vob vob-stg-pname [ –hos/t hostname –hpa/th host-stg-pname –gpa/th global-stg-pname ] | –stgloc { stgloc-name | –auto } } { –pre/serve | –per/ms_preserve [–nprompt ] | –npr/eserve } [ –c/omment comment | –cfi/le comment-file-pname | –cq/uery | –cqe/ach | –nc/omment ] [ –tco/mment tag-comment ] [ –nca/exported ] [–nrem/ote_admin ] [ –reg/ion region-name ] [ –opt/ions mount-options ] [ –pub/lic [ –pas/sword tag-registry-password ] ] [ –ign/oreprot ] [ –poo/ltalk ] [ –vre/plica replica-name ] { packet-file-pname [ search-dir-pname ... ] }

Description

The creation of a new VOB replica is a three-phase process:

  1. The mkreplica–export command duplicates the contents of the current VOB (the originating replica). This generates a single logical replica-creation packet for transmission to one or more other sites. As described in Replica-creation packets, it may be divided into multiple physical packets. (If you use –fship or –ship, mkreplica also generates a shipping order file for each physical packet.)

    This command also creates a new replica object in the VOB database.

    The VOB is locked for the entire length of time the mkreplica –export command runs.

    Note: Creating multiple replicas in one mkreplica–export command is more efficient than using multiple mkreplica–export commands.
    Note: See important information about space considerations under the command options –workdir and –ship.
  2. The packet is sent to one or more other sites.
  3. At each receiving site, a mkreplica–import command uses the replica-creation packet to create a new VOB replica.

When a VOB is replicated for the first time, creating a second replica, the VOB's operation log (oplog) is enabled. All operations to be replicated are recorded in the oplog. Logging of operations continues until all but one of the replicas are deleted. Note that creation of additional replicas is recorded in oplog entries. Existing replicas learn about a new replica through the standard synchronization mechanism. (See the syncreplica reference page.)

Note: Before entering a mkreplica–export command, verify that MultiSite licenses are installed at the original site. After you enable replication in the original VOB, developers cannot access the VOB without a MultiSite license (in addition to a ClearCase® license).

Preservation mode

When you enter a mkreplica–import command, you must choose the preservation mode. In any case, the user who enters the mkreplica–import command becomes the owner of the new replica. That user's group is the primary group of the VOB, and the user's group list becomes the VOB's group list. Preservation affects only element ownership and permissions. For more information about preservation modes, see "Planning a MultiSite implementation" in ClearCase MultiSite Administrator's Guidethis guide.

Restrictions:

  • You can create a replica that preserves identities and permissions only if its site supports the same user and group accounts as the originating site. On Windows, if all replicas in a family are not in the same Windows domain, the entire family cannot preserve identities and permissions. However, you can maintain identities and permissions preservation on the subset of replicas in the same domain.
    Note: There are no restrictions on creating permissions-preserving replicas.
  • On Windows, the primary group of the user who enters the mkreplica–import command must be the same as the originating replica's group assignment.
  • On Linux and the UNIX system, the user who enters the mkreplica–import command must belong to all the groups on the originating replica's group list.

To create a replica that preserves identities and permissions, you should run mkreplica–export at an identities- and permissions-preserving replica. To create a replica that preserves permissions, you should run mkreplica–export at an identities- and permissions-preserving replica or a permissions-preserving replica.

Note: After you create a new replica with mkreplica –import –preserve or mkreplica –import –perms_preserve, run syncreplica –export to inform other replicas in the VOB family about the preservation mode of the new replica.

Replica-creation packets

Each invocation of mkreplica–export creates a single logical replica-creation packet. (This is true even if you create several new replicas with one mkreplica command.) Each packet includes one or more replica specifications, each of which indicates the new replica's name and the host on which a new replica is to be created.

The –maxsize option divides the single logical packet into multiple physical packets to conform to the limitations of the transfer medium.

Cleaning up used packets

Replica-creation packets are not deleted after import. After you import a replica-creation packet with mkreplica –import, you must delete the packet.

Replication of VOBs linked to administrative VOBs

If the VOB you are replicating is linked to an administrative VOB, mkreplica–export prints a reminder that you must replicate all administrative VOBs in the hierarchy above the VOB you are replicating. The output lists the administrative VOBs. The command does not check whether these administrative VOBs are replicated, so you can ignore the message if you have already replicated them.

Restrictions

Identities: For mkreplica–export, you must have one of the following identities:

  • VOB owner
  • root (Linux and the UNIX system)
  • Member of the ClearCaseadministrators group (Windows)

Locks: An error occurs if one or more of these objects are locked: VOB.

Mastership: No mastership restrictions.

Other:

  • You must run mkreplica–export on the host where the VOB storage directory resides.
  • You can replicate a VOB replica to a host running an earlier major version of DevOps Code ClearCase only if the feature level of the exporting replica's VOB family is the same as the feature level of the DevOps Code ClearCase release on the target host. (You can always replicate a VOB to a host running a later major version of DevOps Code ClearCase.)
  • To use the -nremote_admin option, you must be logged on to the replica host as a privileged user.

Options and arguments - Export phase

Specifying temporary workspace

Default
None.
–wor/kdir temp-dir-pname
Directory used as a temporary workspace; it is deleted when mkreplica finishes. This directory must not already exist. You must specify a location in a disk partition that has enough free space (at least the size of the VOB database directory plus its source pools; use cleartool space to display VOB disk space use).

Specifying the replica-creation packet size

Default
When you do not specify –maxsize, the default packet size depends on the shipping method you use:
  • Packets created with –ship or –fship are no larger than the maximum packet size specified in the shipping.conf file (Linux and the UNIX system) or the MultiSite Control Panel (Windows).
  • Packets created with –out are no larger than 2097151 KB (2 GB-1KB).
–max/size size
The maximum size for a physical packet, expressed as a number followed by a single letter; for example:
500k
500 kilobytes
20m
20 megabytes
1.5g
1.5 gigabytes

Event records and comments

Default
Creates one or more event records, with commenting controlled by the standard ClearCase user profile (default: –cq). See Event records and comments in the multitool reference page. To edit a comment, use cleartool chevent.
–c/omment comment-string | –cfi/le comment-file-pname | –cq/uery | –cqe/ach | –nc/omment
Overrides the default with the specified comment option.

Disposition of the replica-creation packet

Default
None. You must specify how the replica-creation packet created by mkreplica–export is to be stored or transmitted to other sites.
–shi/p –fsh/ip
Stores the replica-creation packet in one or more files in a store-and-forward storage bay. A separate shipping order file accompanies each physical packet, indicating how and where it is to be delivered.

–fship (force ship) invokes shipping_server to send the replica-creation packet. –ship places the packet in a storage bay. To send the packet, invoke shipping_server or set up invocations of sync_export_list –poll with the schedule command. (See the schedule reference page in the DevOps Code ClearCase Command Reference.)

Note: The disk partition where the storage bay is located (on the sending host and the receiving host) must have available space equal to or greater than the size of the VOB database and source pools.
–scl/ass class-name
Specifies the storage class of the packet and shipping order. mkreplica looks up the storage class in the MultiSite Control Panel (Windows) or the file ccase-home-dir/config/services/shipping.conf (Linux and the UNIX system) to determine the location of the storage bay to use.

If you omit this option, mkreplica places the packet in the storage bay location specified for the –default class.

–out packet-file-pname
The name of the first physical replica-creation packet. Additional packets are placed in files named packet-file-pname_2, packet-file-pname_3, and so on.

The replica-creation packets are not delivered automatically; use an appropriate method to deliver them. You can create a packet using –out, and subsequently deliver it using the store-and-forward facility. See the mkorder reference page.

Handling packet-delivery failures

Default
If a packet cannot be delivered, it is sent through the store-and-forward facility to the administrator at the site of the originating replica. A mail message is sent to the store-and-forward administrator. This occurs after repeated attempts to deliver the packet have all failed and the allotted time has expired; it can also occur when the destination host is unknown or a data file does not exist. The store-and-forward configuration settings specify the expiration period, the e-mail address of the administrator, and the notification program.
–pex/pire date-time
Specifies the time at which the store-and-forward facility stops trying to deliver the packet and generates a failure mail message instead. This option overrides the expiration period specified for the storage class in the shipping.conf file (Linux and the UNIX system) or MultiSite Control Panel (Windows).

The date-time argument can have any of the following formats:

date.time | date | time | now
where:
date:
= day-of-week | long-date
time:
= h[h]:m[m][:s[s]] [UTC [ [ + | - ]h[h][:m[m] ] ] ]
day-of-week:
= today |yesterday |Sunday | ... |Saturday |Sun | ... |Sat
long-date:
= d[d]–month[–[yy]yy]
month:
= January |... |December |Jan |... |Dec

Specify the time in 24-hour format, relative to the local time zone. If you omit the time, the default value is 00:00:00. If you omit the date, the default value is today. If you omit the century, year, or a specific date, the most recent one is used. Specify UTC if you want the time to be resolved to the same moment in time regardless of time zone. Use the plus (+) or minus (-) operator to specify a positive or negative offset to the UTC time. If you specify UTC without hour or minute offsets, the default setting is Greenwich Mean Time (GMT). (Dates before January 1, 1970 Universal Coordinated Time (UTC) are not valid.)

Examples:
  • 22-November-2002
  • sunday
  • yesterday.16:00
  • 0
  • 8-jun
  • 13:00
  • today
  • 9-Aug.10:00UTC
–not/ify e-mail-address
The delivery-failure message is sent to the specified e-mail address.

If a failure occurs on a Windows host that does not have e-mail notification enabled, a message appears in the Windows Event Viewer. The message includes the e-mail-address value specified with this option and a note requesting that this user be informed of the status of the operation. For information about enabling e-mail notification, see the MultiSite Control Panel reference page.

Replica specifications

Default
None.
hostname:replica-selector...
One or more arguments, each of which indicates one new replica to be created from this packet at another site.
hostname
The machine where the new replica's storage directory will be created. hostname must be usable by hosts in different domains. It is used by the store-and-forward mechanism to determine how to route update packets to the replica. However, keep this information accurate even if your site does not use store-and-forward. (See the chreplica reference page.)

hostname can be either the IP address of the host or the computer name, for example, minuteman. You may have to append an IP domain name, for example, minuteman.purpledoc.com.

On Linux and the UNIX system, use the uname –n command to display the computer name. On Windows 2000, the computer name is displayed on the Network Identification tab in the System Properties window, which is accessible from the System icon in Control Panel. On Windows XP, the computer name is displayed on the Computer Name tab in the System Properties window, which is accessible from the System icon in Control Panel.

Specify replica-selector in the form [replica:]replica-name[@vob-selector]

replica-name
Name of the replica

You must compose the name according to these rules:

  • It must contain only letters, digits, and the special characters underscore (_), period (.), and hyphen (-). A hyphen cannot be used as the first character of a name.
  • It must not be a valid integer or real number. (Be careful with names that begin with "0x", "0X", or "0", the standard prefixes for hexadecimal and octal integers.)
  • It must not be one of the special names " . ", " .. ", or " ... ".
vob-selector
VOB family of the replica; can be omitted if the current working directory is within the VOB.

Specify vob-selector in the form [vob:]pname-in-vob

pname-in-vob
Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted)

Options and arguments - Import phase

Note: If ACLs are enabled, mkreplica –import displays a warning if the file system on which the pool resides does not support ACLs.
Note: See important information about space considerations under the command option –workdir.

Specifying temporary workspace

Default
None.
–wor/kdir temp-dir-pname
A directory for use by mkreplica as a temporary workspace; it is deleted when mkreplica finishes. This directory must not already exist. Make sure to specify a location in a disk partition that has enough free space. (See the description of –workdir in Options and arguments - Export phase.)

Specifying VOB-creation parameters

Default
Because mkreplica –import executes a cleartool mkvob command, you can use many of the options used with mkvob. The –tag option is required, and one of –vob or –stgloc is required. For more information, see the mkvob reference page in the DevOps Code ClearCase Command Reference.
–tag vob-tag
The VOB tag (mount point) of the new VOB replica.
–vob vob-stg-pname
Location for the storage directory of the new VOB replica. On Windows, vob-stg-pname must be a UNC name.
–hos/t hostname | –hpa/th host-stg-pname | –gpa/th global-stg-pname
Sets the new VOB replica's registry information. In most cases, mkreplica derives this information from the vob-storage-pname argument, but if your network topology is unusual or the network interface is not standard, you may have to use these options. If you have to use these options when creating a new VOB at the site, you have to use them when importing a replica-creation packet.
–stgloc { stgloc-name | –auto }
Specifies the name of a storage location for the new replica's VOB storage directory. stgloc-name must be located on the same host on which you invoke mkreplica, and it must be one of the registered storage locations. To list registered locations, use cleartool lsstgloc. With –auto, mkreplica selects a location automatically.
–c/omment comment | –cfi/le comment-file-pname | –cq/uery | –cqe/ach | –nc/omment
Standard comment options.
–tco/mment tag-comment
A comment string to be included in the VOB tag registry entry for the new replica.
–nca/exported
Marks the new VOB replica for NFS export. (Linux and the UNIX system only)
–reg/ion region-name
Specifies a registry region for the new replica's VOB tag.
–opt/ions mount-options
Mount options for the new replica.
–pub/lic [ –pas/sword tag-registry-password ]
Creates a public VOB tag for the new replica.

Protection failures on containers

Default
During import, if any data containers have a group that is not the primary group of the VOB, a failure occurs when mkreplica tries to set the protection of those containers. The import fails if protection failures occur.
–ign/oreprot
Completes the import even if protection failures occur. mkreplica prints a warning that the protection problems may make the replica unusable. You must run checkvob to find and fix any problems after creating a replica with this option.
Note: Instead of using this option, you can add the nonprimary groups to the group list of the user importing the packet.

Preservation mode

Default
None.
–pre/serve
Creates a replica that preserves identities and permissions. The user who enters the mkreplica–import command becomes the owner of the new VOB, and identities and permissions are preserved for all the elements in the new VOB.
–per/ms_preserve [ –nprompt ]
Creates a replica that preserves permissions. The user who enters the mkreplica–import command becomes the owner of the new VOB, and permissions are preserved for all the elements in the new VOB. The –nprompt option suppresses the prompt.
–npr/eserve
Creates a replica that is nonpreserving. The user who enters the mkreplica–import command becomes the owner of the new VOB and of all the elements in the new VOB.

Pool creation for the new replica

Default
The new replica is created with the same set of storage pools as the originating replica, and the assignments of elements to pools are preserved. The new replica's storage pools are created within its storage directory, even if some of the originating replica's pools are remote; the new pools have the default scrubbing parameters.
–poo/ltalk
Prompts you to specify locations and scrubbing specifications for the new replica's storage pools.

Name of VOB replica

Default
If the replica-creation packet includes one replica specification, you are prompted to confirm the replica name. If the packet includes multiple replica specifications, you are prompted to select one of the replica names.
–vre/plica replica-name
Specifies the replica name, bypassing the prompt step.

Specifying the location of the replica-creation packet

Default
None.
packet-file-pname [ search-dir-pname ... ]
Specifies a pathname of a replica-creation packet. For a logical packet that spans multiple disk files, mkreplica scans the directory containing packet-file-pname for related physical packets.

If you also specify one or more search-dir-pname arguments, mkreplica searches for additional packets in these directories.

Preventing privileged access by remote users

Default
Specified by the site property deny_remote_privileged_users. (See the setsite reference page in DevOps Code ClearCase Command Reference.)
-nrem/ote_admin
Disables privileged access by remote users. When a replica is created with this option, all privileged operations require the user to be logged on to the replica host with a privileged identity. Any request from a privileged user logged on to a remote host is treated as though it had been made by an ordinary user (it fails if a privileged identity is required). Use cleartool protectvob -remote_admin to enable privileged access by remote users to a replica created with the -nremote_admin option. For more information, see the protectvob reference page in DevOps Code ClearCase Command Reference.

This option is effective only when you are logged on the replica host as a privileged user.

Examples

In these examples, the lines are broken for readability. You must enter each command on a single physical line.

Exports

  • Generate a replica-creation packet, which will be used at remote host goldengate to create a new replica named sanfran_hub. Place the packet in a file in /tmp.



    multitool mkreplica –export –workdir /tmp/ms_workdir –c "make a new
    replica for sanfran_hub" –out /tmp/sanfran_hub_packet
    goldengate:sanfran_hub


    Generating replica creation packet /tmp/sanfran_hub_packet
    Dumping database...
    ...
    Dumper done.

  • Generate a replica-creation packet and place it in a storage bay.



    multitool mkreplica –export –c "make a new replica for sanfran_hub"
    –workdir /tmp/ms_workdir –ship goldengate:sanfran_hub

    Generating replica creation packet /opt/devops/code/clearcase/shipping/
    ms_ship/outgoing/repl_nyc_hub_18-May-99.15:50:00_1
    - shipping order file is
    /opt/devops/code/clearcase/shipping/ms_ship/
    outgoing/sh_o_repl_nyc_hub_18-May-99.15:50:00_1
    Dumping database...
    ...
    Dumper done.

  • Generate a replica-creation packet that can be used to create two new replicas, bangalore and buenosaires. Ship the packet to its destinations immediately, using store-and-forward.



    multitool mkreplica –export –workdir /tmp/ms_workdir –nc –fship
    ramohalli:bangalore mardelplata:buenosaires
    Generating replica creation packet /opt/devops/code/clearcase
    /shipping/ms_ship/outgoing
    /repl_nyc_hub_15-Aug-00.14.26.17_6011_1
    - shipping order file is /opt/devops/code/clearcase/shipping
    /ms_ship/outgoing/sh_o_repl_nyc_hub_15-Aug-00.14.26.17_6011_1
    Dumping database...
    ...
    Dumper done.
    Attempting to forward/deliver generated packets...
    -- Forwarded/delivered packet /opt/devops/code/clearcase/shipping
    /ms_ship/outgoing/repl_nyc_hub_15-Aug-00.14.26.17_6011_1


Imports

  • Using a packet file in /tmp, create the storage directory for replica sanfran_hub. Make the replica identities- and permissions-preserving, and immediately after creating the new replica, run syncreplica –export to update the other replicas in the VOB family.



    multitool mkreplica –import –workdir /tmp/ms_workdir –tag /vobs/dev –vob
    /net/goldengate/vobstg/dev.vbs –preserve –c "create sanfran_hub replica"
    /tmp/sanfran_hub_packet


    The packet can only be used to create replica "sanfran_hub"
    - VOB family is c3f47cf3.71b111cd.a4f2.00:01:80:31:7a:a7
    - replica OID is 0c39c3b8.727b11cd.abb5.00:01:80:31:7a:a7
    Should I create this replica? [no]
     yes

    Processing packet /tmp/sanfran_hub_packet...
    Loading database...
    ...
    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 ...
    group ...


    multitool syncreplica –export –c "identities and permissions preserving"
    –fship nyc_hub bangalore buenosaires


    ...

  • Similar to preceding example, but create the replica as permissions preserving.

    multitool mkreplica –import –workdir /tmp/ms_workdir –tag /vobs/dev
    –vob /net/goldengate/vobstg/dev.vbs –perms_preserve –c "create
    sanfran_hub replica" /tmp/sanfran_hub_packet
    multitool: Warning: In a permissions-preserving replica,
    cleartool protect operations will fail on client machines running
    ClearCase vesions 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 c3f47cf3.71b111cd.a4f2.00:01:80:31:7a:a7
    - replica OID is 0c39c3b8.727b11cd.abb5.00:01:80:31:7a:a7
    Should I create this replica? [no]     yes
    Processing packet /tmp/sanfran_hub_packet...
    ...


    multitool syncreplica –export –c "permissions preserving" –fship nyc_hub
    bangalore buenosaires


    ...

  • Similar to preceding example, but create the replica as a public VOB and nonpreserving. Specify the VOB tag password and mount options on the command line.



    multitool mkreplica –import –workdir /tmp/ms_workdir –tag /vobs/dev –vob
    /net/goldengate/vobstg/dev.vbs –npreserve –c "create sanfran_hub replica"
    –options rw,soft –public –password xxxxxx –vreplica sanfran_hub /tmp/
    sanfran_hub_packet


    Processing packet /tmp/sanfran_hub_packet...
    ...
    Registering VOB mount tag "/vobs/dev"...
    VOB replica successfully created.
    ...

  • Create the storage directory for a new replica, using a packet that was generated by existing replica nyc_hub and sent through store-and-forward. Specify storage pool parameters for the new replica.



    multitool mkreplica –import –workdir c:\tmp\workdir –tag \dev –vob
    \\ramohalli\vobs\dev.vbs –npreserve –c "create bangalore replica"
    –pooltalk –vreplica bangalore "c:\Program Files\DevOps\Code\ClearCase
    \var\shipping\ms_ship\incoming
    \repl_nyc_hub_15-Aug-00.14.26.17_6011_1


    Processing packet c:\Program Files\DevOps\Code\ClearCase\var\shipping
    \ms_ship\incoming\repl_nyc_hub_15-Aug-00.14.26.17_6011_1
    The initial storage pools that will be used in the replica are:
    source pool sdft
    derived pool ddft
    cleartext pool cdft
    Configuration for pool "sdft" (source pool):
    Full pathname of directory to which pool "sdft"
    should be linked (none = not linked)? [none] <RETURN>
    Configuration for pool "ddft" (derived pool):
    Full pathname of directory to which pool "ddft"
    should be linked (none = not linked)? [none] <RETURN>
    Maximum size (in Kbytes) for the storage directory of pool "ddft"
    (0 = no maximum)? [0] <RETURN> Space (in Kbytes) to reclaim from pool
    "ddft" during scrubbing (0 = none)? [0] <RETURN>
    Minimum age (in hours) of objects to scrub from pool "ddft"
    (0 = none)? [0] 12Command to invoke if scrubbing does not reduce pool
    "ddft" below maximum size (none = no command)? [none] <RETURN>
    Comment for pool "ddft" (none = none)? [none] <RETURN>
    . . .

                               Max. Reclaim   Min. Link To
    Pool Name   Kind           Size   Size    Age Directory
    ---------   ----           ----   ----    --- ---------
    sdft        source pool    n/a    n/a     n/a
    ddft        derived pool   0K     0K      12
    cdft        cleartext pool 0K     0K      96

    Is this the correct configuration for the pools (yes/no/abort)? [no]
     yes


    ...
    Registering VOB mount tag "\dev"...
    ...