mkreplica

Creates a VOB replica

APPLICABILITY

SYNOPSIS

• Duplicate an existing VOB replica, generating 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]
| -tape raw-device-pname
| -out packet-file-pname
}
hostname:replica-selector ...

NOTE: The -tape option is valid only on UNIX.

• Use 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 | -npr·eserve }
[ -c·omment comment | -cfi·le comment-file-pname | -cq·uery | -cqe·ach | -nc·omment ]
[ -tco·mment tag-comment ] [ -nca·exported ]
[ -reg·ion region-name ] [ -opt·ions mount-options ]
[ -pub·lic [ -pas·sword tag-registry-password ] ] [ -ign·oreprot ]
[ -poo·ltalk ] [ -vre·plica replica-name ]
{ -tap·e raw-device-pname | packet-file-pname [ search-dir-pname ... ] }

NOTE: The -ncaexported and -tape options are valid only on UNIX.

DESCRIPTION

The creation of a new VOB replica is a two-phase process. Both phases require you to enter a mkreplica command:

1. The mkreplica -export command duplicates the contents of the current VOB replica (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.

2. At another site, a mkreplica -import command uses the replica-creation packet to create a new VOB replica. The user who enters this command becomes the VOB owner of the new replica.

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

NOTE: Before entering a mkreplica -export command, make sure 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).

OWNERSHIP PRESERVATION

When you enter a mkreplica -import command, you must choose whether to make the new replica ownership-preserving or non-ownership-preserving. In either case, the user who enters the mkreplica -import command becomes the owner of the new VOB replica. Ownership preservation affects only element ownership and permissions. For more information on ownership preservation, see Element Ownership and Ownership Preservation.

Restrictions:

• Creating an ownership-preserving replica is appropriate only if its site supports the same user and group accounts as the originating site. On Windows, therefore, if replicas in a VOB family are not all in the same Windows domain, the entire set of replicas cannot be ownership-preserving. However, you can maintain ownership preservation on the subset of replicas in the same domain.

• Windows: The primary group of the user who enters the mkreplica -import command must be the same as the originating replica's group assignment.

• UNIX: The user who enters the mkreplica -import command must belong to all the groups on the originating replica's group list.

NOTE: We recommend that you run syncreplica -export immediately after creating a new replica with mkreplica -import -preserve, to inform other replicas in the VOB family that the new replica is ownership-preserving.

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 carries one or more replica specifications, each of which indicates the host on which a new replica is to be created, along with the new replica's name.

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

Cleaning Up Used Packets

Replica-creation packets are not deleted after import. The VOB owner at the new replica site must delete replica-creation packets after importing them with mkreplica -import.

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 (UNIX)

• Member of the ClearCase administrators group (Windows)

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

Mastership: No mastership restrictions.

Other:

• You must execute mkreplica -export on the host where the VOB storage directory resides.

• You cannot replicate a VOB to a host running an earlier major version of MultiSite. (However, you can replicate a VOB to a host running a later major version of MultiSite.)

OPTIONS AND ARGUMENTS - EXPORT PHASE

The following sections describe the options and arguments for use with mkreplica -export.

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. 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 (UNIX) or the MultiSite Control Panel (Windows).

• Packets created with -out are no larger than 2 GB.

• Packets created with -tape have no default size limit.

The mkreplica command fails if it tries to create a packet larger than the size supported by your system or by the tape.

-max·size size

The maximum size for a physical packet, expressed as a number followed by a single letter; for example:

500k 20m 1.5g

500 kilobytes 20 megabytes 1.5 gigabytes

EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by the standard ClearCase user profile (default: -cqe). 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 and/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 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 store-and-forward configuration settings (on Windows, in the MultiSite Control Panel; on UNIX, in the file ccase-home-dir/config/services/shipping.conf) 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.

-tap·e raw-device-pname (UNIX)

Writes the replica-creation packets to the specified tape device, which must be local to the VOB server host. You are prompted to load a separate tape for each physical packet. Use the -maxsize option to ensure that syncreplica does not exceed the capacity of the tapes you are using. Only one physical packet can be placed on each tape, regardless of packet size.

-out packet-file-pname

Places the first physical replica-creation packet in file packet-file-pname. 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 mechanism (for example, electronic mail, ftp, or postal service) 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 for details.

HANDLING PACKET-DELIVERY FAILURES. Default: If a packet cannot be delivered, it is sent through the store-and-forward facility back 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 and the e-mail address of the administrator).

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

UNIX: This option overrides the storage class's EXPIRATION specification in the store-and-forward configuration file. See the shipping.conf reference page for a discussion of this specification and of delivery retries in general.

Windows: This option overrides the storage class's Packet Expiration specification in the MultiSite Control Panel. See the MultiSite Control Panel reference page for a discussion of this specification and of delivery retries in general.

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 invalid.)

Examples:

22-November-1998
sunday
yesterday.16:00
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

Names 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 ClearCase 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 UNIX, use the uname -n command to display the computer name. On Windows NT, the computer name is displayed in the Network Settings dialog box, which is accessible from the Network icon in the Control Panel. On Windows 2000, the computer name is displayed on the Network Identification tab in the System Properties dialog box, which is accessible from the System icon in the 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

The following sections describe the options and arguments for use with mkreplica -import.

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. See the mkvob reference page in the Command Reference for detailed descriptions of these options.

-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 (UNIX)

Marks the new VOB replica for NFS export.

-reg·ion region-name

Specifies an alternate registry region for the new replica's VOB-tag.

-opt·ions mount-options

Mount options for the new VOB 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.

OWNERSHIP PRESERVATION. Default: None.

-pre·serve

Creates a replica that is ownership-preserving. The user who enters the mkreplica -import command becomes the owner of the new VOB, and ownership and permissions are preserved for all the elements in the new VOB.

-npr·eserve

Creates a replica that is not ownership-preserving. 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.

-tap·e raw-device-pname (UNIX)

Reads a replica-creation packet from the specified tape device, which must be local to the host on which you enter the mkreplica -import command. Before entering the command, place the tape in the tape drive. If a logical packet spans multiple tapes, you can start with any of them in the drive. You are prompted to switch tapes.

packet-file-pname [ search-dir-pname ... ]

Specifies a pathname of a replica-creation packet created by mkreplica -export. 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.

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 directory /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 /var/adm/atria/shipping/ms_ship/outgoing/repl_boston_hub_18-May-99.15:50:00_1
- shipping order file is /var/adm/atria/shipping/ms_ship/outgoing/sh_o_repl_boston_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 /usr/atria/shipping/ms_ship/outgoing/repl_boston_hub_15-Aug-00.14.26.17_6011_1
- shipping order file is /usr/atria/shipping/ms_ship/outgoing/sh_o_repl_boston_hub_15-Aug-00.14.26.17_6 011_1
Dumping database...
...
Dumper done.
Attempting to forward/deliver generated packets...
-- Forwarded/delivered packet /usr/atria/shipping/ms_ship/outgoing/repl_boston_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 ownership-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 "ownership-preserving" -fship boston_hub bangalore buenosaires
...

• Similar to preceding example, but create the replica as a public VOB and non-ownership-preserving. 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 boston_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\Rational\ClearCase\var\shipping\ms_ship\incoming\repl_boston_hub_15-Aug -00.14.26.17_6011_1
Processing packet c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\incoming\repl_boston_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] 12
Command 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>
. . . (accept defaults for cleartext pool, cdft)

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

SEE ALSO

chmaster, chreplica, lspacket, lsreplica, mkorder, MultiSite Control Panel, shipping.conf, syncreplica, mkvob (in the Command Reference)
Chapter 10, Troubleshooting MultiSite Operations