The MultiSite store-and-forward facility (the shipping server) is a file-transfer service that automates the transport phase of replica creation and synchronization. It can handle packets of any size, can route files through a series of MultiSite hosts (one hop at a time), and includes support for handling data-communications failures. This is how the store-and-forward process works:
If the packet is associated with a storage class, the packet is stored in the storage bay specified by the storage class. You can define storage classes in the shipping.conf file on UNIX and the MultiSite Control Panel on Windows.
Each storage class has storage bays and return bays, which are directories that hold packets. Storage bays are used for normal shipping operations, and return bays are used for packets that could not be delivered successfully.
Each storage bay and return bay directory contains two subdirectories, incoming and outgoing, which hold the packets and their corresponding shipping order files. Shipping operations look in these directories for packets.
Note: On Windows, the amount of available space on the disk partition where the bays are located must be at least twice the size of the largest packet that will be stored in the bays. There may be two copies of the same packet in the bay at one time: one on its way to another destination and another waiting to be applied to the replica on the host.
When you install the Rational Shipping Server on a host, the –default storage class is created, along with its storage and return bays. The storage bay is named ms_ship and the return bay is named ms_rtn. The incoming and outgoing directories in each bay are also created. When you use the MultiSite Control Panel (Windows) to create a new storage or return bay, the bay and its subdirectories are created. On UNIX, you must create the bays and their incoming and outgoing subdirectories and then specify the bays in the shipping.conf file.
An explicit command, manual or automated, invokes the shipping server on the sending host. The shipping server process contacts the albd_server process on the receiving host, which in turn invokes the shipping server on the receiving host in receive mode. After a TCP/IP connection has been established between the sending and receiving invocations of the shipping server, the file is transferred.
The following sections describe issues to consider when you use the store-and-forward method.
The hosts must be able to communicate with each other. If your network uses host names, the sending host must be able to resolve the receiving host’s name to an IP address. To accomplish this, you may have to update the hosts file, hosts NIS map, or Domain Name Service. To verify TCP/IP access, use rcp on each sending host to copy a file to the receiving hosts or use store-and-forward to send a packet (see Submitting Packets to Store-and-Forward).
Note: If hosts in your network are known only by their IP addresses, you can use the IP addresses instead of host names, and no resolution is necessary.
The mkreplica and syncreplica commands fail if they try to create a packet larger than the size supported by your system. To prevent this problem and improve reliability, use the –maxsize option to divide the packet into multiple packets:
You can also specify maximum packet sizes in the shipping.conf file (UNIX) or MultiSite Control Panel (Windows).
For information about default packet size limits, see the mkreplica reference page.
The settings for the store-and-forward facility are host specific. You can specify locations of storage and return bays, routing information to support multihop packet delivery, specifications to handle failure-to-deliver situations, receipt handlers, and so on.
Before you use store-and-forward, verify that you have the appropriate disk space, and configure the shipping.conf file or the MultiSite Control Panel and create storage classes for packets.
For more information about specifying settings, see the shipping.conf reference page on UNIX or the MultiSite Control Panel reference page on Windows.
When you generate a replica-creation or update packet, you can specify that the store-and-forward facility must deliver it. Both mkreplica and syncreplica support the following options:
You can configure the store-and-forward facility to handle packets in different ways. Each packet can be assigned to a storage class, and each storage class can have its own storage bay, return bay, and expiration period.
Note: On UNIX, a storage class can be assigned several storage and return bays; in this case, the shipping server uses the size of the packet to select one of the bays. Conversely, several storage classes can share one or more bays.
The default storage class for packets from schema repository and user database replicas depends on the command you’re using. The mkorder and shipping_server commands use the –default storage class, which is created when the Rational Shipping Server is installed. All multiutil commands that use the –sclass argument use the cq_default storage class, which is not created during installation.
You can use multiple storage classes to segregate the packets for replicas that belong to different clans. By adjusting the operating system permissions on the storage bay directories, you can protect the packets from unauthorized use. You can also use a separate storage class when you use the store-and-forward facility to transfer non-MultiSite files between sites.
If you are using the store-and-forward facility to transport packets from VOB replicas and from ClearQuest database replicas, you must use different storage classes. Because the mkorder and shipping_server commands are used for both ClearCase MultiSite and ClearQuest MultiSite, you must specify the storage class when you use these commands on a packet from a ClearQuest replica. Also, if you do not create the cq_default storage class, you must use the –sclass option in multiutil commands and specify a ClearQuest MultiSite storage class.
Follow these guidelines when you create a storage class:
The shipping order for a packet includes the host name of the packet’s final destination or several such host names. By default, the store-and-forward facility sends the packet directly to its destination host. You can specify that the packet must be sent to an intermediate host by associating it with a routing hop in the shipping.conf file (UNIX) or in the MultiSite Control Panel (Windows).
For example:
ROUTE sydney_fw sanfran_hub boston_hub tokyo
Any packet whose final destination is host sanfran_hub, boston_hub, or tokyo is forwarded to host sydney_fw. At this point, the local host has completed its task, and responsibility for delivering the packet now belongs to sydney_fw. Host sydney_fw can transmit the packet to its final destination directly, or send it to yet another intermediate host, depending on the settings in its shipping.conf file or in the MultiSite Control Panel.
Note: In a multihop transmission, using the –fship option on the original host causes the first hop to occur immediately. Subsequent hops occur when the shipping server is invoked on the intermediate hosts, which may not be immediately after the packets are received.
The shipping server makes one attempt to transmit a packet to another host. If the packet cannot be transmitted (for example, because the receiving host is unavailable), the shipping server generates an error message and log file entry and exits. You can set up a retry scheme to control its frequency:
Attempts to transmit an undelivered packet can continue indefinitely, through repeated invocations of the shipping_server command. However, you usually want to fix problems with failed transmissions instead of letting the attempts continue. Accordingly, each shipping order can include an expiration date-time, specified with one of the following:
By default, shipping orders expire 14 days after they are created.
When the shipping server encounters a shipping order that has expired, it does not attempt to transmit the corresponding packet to its destination. Instead, it does the following:
The return trip may involve multiple hops, as described in Setting Up an Indirect Shipping Route. During such a trip, a packet is placed in the return bay of each intermediate host. Each hop is handled by shipping_server –poll, which processes a host’s return bay in addition to its storage bays. The expiration time for a packet’s return trip is 14 days; a packet that cannot be returned in that interval is deleted.
If the shipping server tries to send a packet to a target host and determines that the host is unreachable, it creates a file in the /var/adm/rational/clearcase/shipping/ms_downhost directory (UNIX) or the ccase-home-dir\var\shipping\ms_downhost directory (Windows). The name of the file is the name of the unreachable host.
If one of the following parameters is set, the shipping server checks the directory for target hosts during future shipping operations:
If the target host is found in the ms_downhost directory, and the difference between the current time and the last modification time of the file is less than the timeout setting on the shipping server host, the shipping server does not try to send packets to the target host. If the difference is equal to or greater than the timeout setting, the shipping server tries to send packets to the target host. If the timeout setting is not set, the shipping server attempts to send the packet to the target host. (Each attempt to send a packet to an unreachable host takes about 30 seconds.)
If a packet is delivered through a Windows host on which e-mail notification is not enabled, a failure on that Windows host means that no notification message is sent by electronic mail. Instead, a message is written to the event log; this message contains a request that the appropriate users be informed of the failure. For information about enabling e-mail notification, see the MultiSite Control Panel reference page.
You can use the store-and-forward facility to send any file if you create a shipping order for the file with the mkorder utility. You can send the file immediately or wait for the shipping server to send it.
/opt/rational/clearcase/etc/mkorder –data /usr/rptgen/brdcst.0702 –fship –copy boston_hub tokyo
/opt/rational/clearcase/etc/mkorder –data /usr/rptgen/brdcst.0702 –ship –copy boston_hub tokyo
Note: The shipping order must be located in the same directory as the file.
After you invoke the mkorder command, you can delete the original file.
If a file with the same name already exists on the receiving host, the file you send is renamed to filename_1. If you transmit another file with the same name, it is renamed to filename_2, and so on.