syncreplica

Generates or applies update packets

APPLICABILITY

SYNOPSIS

• Export an update packet:

sync·replica -exp·ort [ -max·size max-packet-size [ -lim·it num-packets ] ]

[ -c·omment comment | -cfi·le comment-file-pname | -cq·uery | -cqe·ach | -nc·omment ]
{
{ -sh·ip | -fsh·ip } [ -scl·ass storage-class ]
[ -pex·pire date ] [ -not·ify e-mail-addr ]
| -tape raw-device-pname
| -out packet-file-pname
}
replica-selector ...

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

• Import an update packet:

sync·replica -imp·ort [ -invob VOB-selector ]

[ -c·omment comment | -cfi·le comment-file-pname | -cq·uery | -cqe·ach | -nc·omment ]
{ -rec·eive [ -scl·ass storage-class ]
| -tape raw-device-pname
| { packet-file-pname | staging-area-pname } ...
}

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

DESCRIPTION

Synchronization of an existing VOB replica with one or more replicas at other sites is a two-phase process:

1. At one site, a syncreplica -export command creates an update packet that contains changes that have occurred in the VOB replica at that site (and perhaps other replicas, as well).

2. At another site, a syncreplica -import command applies the changes in the update packet to its replica of the same VOB.

Step #2 occurs at all sites that receive the packet.

Contents of an update packet:

• All changes that have occurred in the current VOB replica since the last update generated for the destination replicas. (Changes already sent to the destination replicas are excluded from the packet).

• Changes that have occurred in other replicas, which the current replica has received in previous update packets from those replicas, but has not already passed on to the destination replicas.

In all cases, syncreplica -export creates a single logical update packet for use at all the specified destinations; the packet can be used to update only those particular replicas.

NOTES ON THE EXPORT PHASE

MultiSite is designed for efficient updating of replicas. syncreplica -export attempts to exclude from an update packet operations that have been sent previously. (However, there is no harm in sending an operation multiple times to the same replica; the first operation is imported and subsequent identical operations are ignored.)

The VOB replica is not locked during the export phase; in fact, the syncreplica -export command fails if the VOB is locked. Therefore, you must not schedule synchronizations during VOB backups (when the VOB must be locked). See also RETRYING SYNCHRONIZATION WHEN THE VOB IS LOCKED.

Specifying a Directory for Temporary Files

syncreplica -export stores temporary files in the directory specified by the TMPDIR environment variable on UNIX and the TMP environment variable on Windows. If you use the sync_export_list script to export update packets, you can use the -workdir option to specify the directory.

NOTES ON THE IMPORT PHASE

An update packet is applied to the appropriate replica on the host on which you import it, unless you restrict processing with the -invob argument. syncreplica consults the VOB registry in the current region to determine the locations of these replicas' storage directories. Thus, you do not have to specify particular replicas or storage locations.

The import process applies update packets in the correct order. Therefore, you can specify packets in any order on the command line.

The VOB replica is not locked during the import phase. Synchronization fails if the VOB is locked. See also RETRYING SYNCHRONIZATION WHEN THE VOB IS LOCKED.

Specifying a Directory for Temporary Files

syncreplica -import stores temporary files in the directory specified by the TMPDIR environment variable on UNIX and the TMP environment variable on Windows. If you use the sync_receive script to import update packets, you can use the -workdir option to specify the directory.

Skipping Packets

syncreplica -import refuses to process an update packet in the following situations:

• The update packet contains changes that depend on other changes that have not yet been applied to this replica. This usually means that an update packet destined for this replica has not been sent or was lost during transport.

• Problems were encountered processing an earlier physical packet in a multiple-part logical packet.

In any of these cases, syncreplica -import displays an explanatory message.

Update Failures / Replaying Packets

In some cases, syncreplica -import begins to apply operations to a replica, but fails with an error message. For example, another process may have locked the VOB, causing the import to fail. After the VOB is unlocked, you can run syncreplica -import to process the entire update packet again.

There is no harm in importing update packets that have already been processed successfully; the same change will not be made twice. Thus, even importing an entire update packet multiple times causes no error and does no harm.

For more information about update failures, see Chapter 10, Troubleshooting MultiSite Operations.

Deletion of Update Packets

If a single invocation of syncreplica -import applies a packet successfully to all target replicas on the host, the update packet is deleted when the command completes its work. If the packet is processed with multiple syncreplica -import -invob commands, it is not deleted.

Ownership Preservation

If a VOB replica is ownership-preserving, syncreplica -import maintains the consistency of ownership and permissions information for elements mastered by the VOB family's ownership-preserving replicas. For each such element, an error occurs if the element's group is not on the group list of the importing replica (on UNIX) or is not the same as the group of the importing replica (on Windows).

If a VOB replica is not ownership-preserving, changes to ownership and permissions of existing elements are ignored during import. New elements are assigned to the owner of the VOB at the current site, and the group of all new elements is the primary group of the owner of the VOB. (This is true even if the root user or a member of the ClearCase administrators group imports the packet.) Permissions set when the element is created are preserved, but subsequent permissions changes are ignored. Ownership and permissions changes made at non-ownership-preserving replicas are not propagated to other replicas.

Storage Pools

Data containers from the update packets are placed in storage pools according to the standard element assignments. If the pool assignment for a new element cannot be determined, the element is assigned to the VOB's default source pool.

Trigger Firing

ClearCase triggers do not fire in response to changes made during packet import.

Handling Naming Conflicts

syncreplica resolves naming conflicts among type objects created at different replicas. For more information, see Conflict Resolution.

Delayed View Updates

syncreplica does not inform any views (not even the view from which you enter the command) of the updates to replicas. All active views see updates within a few seconds, through their normal VOB-polling routines. You can force a view to recognize VOB updates by entering a cleartool setcs -current command.

RETRYING SYNCHRONIZATION WHEN THE VOB IS LOCKED

By default, synchronization exports and imports fail if the VOB is locked. To allow syncreplica to retry a synchronization when it encounters a lock, set the CLEARCASE_VOBLOCKWAIT environment variable to the amount of time (in minutes) for syncreplica to keep trying to write to the VOB. During that time, syncreplica retries the write operation every minute. If the time elapses and the VOB is still locked, syncreplica exits with an error.

NOTE: The syncreplica command waits only if it detects the lock before it starts processing oplogs. If an administrator locks the VOB during oplog processing, syncreplica exits with an error.

RESTRICTIONS

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

OPTIONS AND ARGUMENTS - EXPORT PHASE

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

SPECIFYING THE UPDATE 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.

-max·size max-packet-size [ -lim·it num-packets ]

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

The -limit option limits the number of packets syncreplica generates; each packet is no larger than max-packet-size. Use this option when the disk space for your shipping bay or staging area is limited.

EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by the standard ClearCase user profile (default: -nc). See EVENT RECORDS AND COMMENTS in the multitool reference page. To edit a comment, use cleartool chevent.

-c·omment comment | -cfi·le comment-file-pname | -cq·uery | -cqe·ach | -nc·omment

Overrides the default with the specified comment option.

DISPOSITION OF THE UPDATE PACKET. Default: None. You must specify how the update packets created by syncreplica -export are to be stored and/or transmitted to other sites.

-shi·p

-fsh·ip

Stores the update packet in one or more files in a store-and-forward storage bay; syncreplica creates a separate shipping order for each physical packet, indicating how and where it is to be delivered. The destinations are the host names associated in the VOB database with the replica-name arguments. (Replica-name/host-name associations are created with mkreplica -export and can be changed with chreplica.)

Using -fship (force ship) invokes the shipping_server to send the update packet immediately. Using -ship does not invoke this server. To run shipping_server to send packets in storage bays, schedule sync_export_list -poll with the schedule command. (See the schedule reference page in the Command Reference.)

-scl·ass class-name

Specifies the storage class of the packet and shipping order. syncreplica looks up the storage class in the shipping.conf file on UNIX or the MultiSite Control Panel on Windows to determine the location of the storage bay to use.

If you omit this option, syncreplica places the packet in the storage bay location specified for the -default class in the shipping.conf file or MultiSite Control Panel. By default, this location is /var/adm/atria/shipping/ms_ship on UNIX and ccase-home-dir\var\shipping\ms_ship on Windows.

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

Writes the update packets to the specified tape device, which must be local to the host on which you enter the syncreplica command. 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.

CAUTION: Be sure to deliver a packet created with -out or -tape to its specified destinations promptly. If a replica has not yet received and applied this packet, it may not accept any subsequently generated packets from your site until the first packet is received and processed.

-out packet-file-pname

Places the first update packet in file packet-file-pname. Additional physical packets, if any, are placed in files named packet-file-pname_2, packet-file-pname_3, and so on.

The update packets are not delivered automatically; use an appropriate mechanism (electronic mail, ftp, postal service, and so on) to deliver them.

You can create a packet using -out, and 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 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 attempting 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 description 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 description 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.

SPECIFYING THE DESTINATION REPLICAS. Default: None.

replica-selector ...

Prepares an update packet to be sent to the specified replicas, which must be in the same VOB family. Specify replica-selector in the form [replica:]replica-name[@vob-selector]

replica-name	Name of the replica (displayed with lsreplica)
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 syncreplica -import.

RESTRICTING THE UPDATE TO A PARTICULAR VOB. Default: Updates all replicas that are on the current host and are specified in the update packets. With -tape, you must specify a VOB replica to be updated.

-invob vob-selector

Updates the replica in the VOB family specified by vob-selector; all other replicas specified in the update packets are ignored. 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)

EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by the standard ClearCase user profile (default: -nc). See EVENT RECORDS AND COMMENTS in the multitool reference page. To edit a comment, use cleartool chevent.

-c·omment comment | -cfi·le comment-file-pname | -cq·uery | -cqe·ach | -nc·omment

Overrides the default with the specified comment option.

SPECIFYING THE LOCATION OF THE UPDATE PACKETS. Default: None.

-rec·eive [ -scl·ass storage-class ]

Scans one or more of the current host's storage bays. Any unprocessed update packets intended for this host are applied to the appropriate replicas on the host. Using the -sclass option restricts processing to the storage bays of the specified storage class.

If syncreplica finds any replica-creation packets, it sends mail to the store-and-forward administrator. (If the current host is a Windows host and there is no valid host specified in the SMTP Host box in the ClearCase Control Panel, a message appears in the Windows Event Viewer.) Use mkreplica to import these replica-creation packets.

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

Reads a single packet from the tape device, and applies it to the replica of the VOB specified with -invob. The tape device must be local to the importing host.

packet-file-pname | staging-area-pname ...

Processes each packet-file-pname as an update packet. For each staging-area-pname specified, locates all previously unprocessed update packets in the directory and applies them to the appropriate replicas.

EXAMPLES

Exports

• Generate an update packet to be sent to replica boston_hub. Store the packet in a file in directory c:\tmp.

multitool syncreplica -export -out c:\tmp\boston_hub_packet1 boston_hub@\dev
Generating synchronization packet c:\tmp\boston_hub_packet1

• Similar to preceding example, but place the packet file in a storage bay, for shipping at some later time by the store-and-forward facility.

multitool syncreplica -export -ship boston_hub@\dev
Generating synchronization packet c:\Program Files\Rational\ClearCase\var
\shipping\ms_ship\outgoing\sync_bangalore_19-May-99.09.33.02_3447_1
- shipping order file is c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\outgoing\sh_o_sync_bangalore _19-May-99.09.33.02_3447_1

• Similar to preceding example, but ship the packet immediately.

multitool syncreplica -export -fship boston_hub@\vob2
Generating synchronization packet c:\Program Files\Rational\ClearCase\var
\shipping\ms_ship\outgoing\sync_bangalore_19-May-99.09.33.02_3447_1
- shipping order file is c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\outgoing\sh_o_sync_bangalore _19-May-99.09.33.02_3447_1
Attempting to forward/deliver generated packets...
-- Forwarded/delivered packet c:\Program Files\Rational\ClearCase\var
\shipping\ms_ship\sync_bangalore_19-May-99.09.33.02_3447_1

Imports

• Process an incoming update packet in directory /usr/tmp.

multitool syncreplica -import /usr/tmp/boston_hub_packet1
Applied sync. packet /usr/tmp/boston_hub_packet1 to VOB /net/minuteman/vobstg/dev.vbs

• Process all incoming update packets in the current host's storage bays.

multitool syncreplica -import -receive
Applied sync. packet c:\Program Files\Rational\ClearCase\var
\shipping\ms_ship\incoming\sync_boston_hub_19-May-99.09.45.01_7634_1
to VOB \\ramohalli\vobs\dev.vbs

SEE ALSO

mkorder, mkreplica, MultiSite Control Panel, shipping.conf, sync_export_list
Chapter 10, Troubleshooting MultiSite Operations