This file controls the operation of the store-and-forward facility on each host. The file consists of comment lines (starting with #) and one or more configuration entries, and it can contain the configuration entries described below. In some cases, the corresponding store-and-forward operation fails if an entry is missing; in other cases, there is a hard-coded default.
MultiSite installation creates the file ccase-home-dir/config/services/shipping.conf.template, in which all these entries are defined. If /var/adm/rational/clearcase/config/shipping.conf does not exist, the installation creates it by copying the template file. If /var/adm/rational/clearcase/config/shipping.conf exists, the installation advises you to compare the existing file to the template and make any necessary changes.
MAX-DATA-SIZE size [ k | m | g ]
Default (and maximum): 2097151 KB (2GB-1KB)
Controls the splitting of individual logical packets into multiple physical packets. Limiting the size of physical packets can improve the reliability of packet delivery in some networks. The size integer (with the optional k, m, or g suffix) specifies the maximum size for a physical packet file. k specifies KB (kilobytes); m specifies MB (megabytes); g specifies GB (gigabytes). Omitting the suffix specifies KB. Specifying 0 (zero) also uses the default value.
This value is used by the following commands (unless you also specify –maxsize):
When you invoke mkreplica or syncreplica with –out, this value is not used and you must use –maxsize to limit the packet size.
NOTIFICATION-PROGRAM e-mail-program-pathname
Default: /opt/rational/clearcase/bin/notify. This program is also used if no NOTIFICATION-PROGRAM entry exists.
The electronic mail program to be invoked in these circumstances:
The mail program is invoked as follows:
e-mail-program-pathname–s subject –f message-file addr ...
ADMINISTRATOR e-mail-address
Default: root
The electronic mail address of the administrator who administers the store-and-forward facility on the local host.
A mail message is sent to the specified address in the circumstances listed in Notification. The configuration file can contain multiple ADMINISTRATOR entries; messages are sent to all the specified mail addresses.
STORAGE-BAY storage-class directory-pathname
RETURN-BAY storage-class directory-pathname
Default: multiutil commands that use the –sclass option use the cq_default storage class for packets that are not assigned to any storage class, and for packets whose storage class is not configured. The mkorder and shipping_server commands use the –default storage class for packets that are not assigned to any storage class, and for packets whose storage class is not configured.
These lines define storage bay and return bay directories. A storage bay holds the outgoing and incoming update packets and shipping orders for a storage class. A return bay holds incoming or outgoing packets in the process of being returned to their origin because they could not be delivered to all specified destinations.
You can use multiple STORAGE-BAY and RETURN-BAY entries to define multiple bays for a storage class. shipping_server selects one of the bays for each packet based on the available disk space in the bays' disk partitions. The order in which you specify bays does not matter.
MultiSite installation creates a default storage class named –default. The storage bay and return bay for this class are created on the local host in the /var/adm/rational/clearcase/shipping directory. Each bay contains subdirectories named incoming and outgoing, which hold incoming and outgoing packets. Shipping operations look for packets in these subdirectories. Before using the store-and-forward facility, make sure that the disk partition where the shipping directory is created has sufficient free space for anticipated replica-creation and update packets. To avoid the possibility of VOB database corruption, which can be caused by filling up the disk partition containing your VOB database, place the storage bay on a disk partition that does not contain VOB storage directories.
multiutil commands that use the –sclass option use the cq_default storage class for packets that are not assigned to any storage class, and for packets whose storage class is not configured. The cq_default storage class is not created when MultiSite is installed. The mkorder and shipping_server commands use the –default storage class for packets that are not assigned to any storage class and for packets whose storage class is not configured. You can create additional storage classes for Rational ClearQuest® MultiSite packets, but you must use different storage classes for Rational ClearQuest MultiSite packets and Rational ClearCase® MultiSite packets.
You must create directory-pathname with a standard Linux® and the UNIX system mkdir command. You must also create the incoming and outgoing directories in the new bay. Packets placed in a bay are assigned the same owner, groups, and read-write permissions as the bay itself. (Execute permission and any special permissions on the bay are ignored.) Be sure to adjust these permissions (if necessary) to enable successful execution of MultiSite commands to process the packets and to guard against unauthorized access.
EXPIRATION storage-class number-of-days
EXPIRATION–default number-of-days
Default: 14 days for –default; none for cq_default (you must specify an expiration period).
Specifies the expiration period (in days) for shipping orders associated with the specified storage class. This period begins at the time the shipping order is generated. If a packet cannot be delivered to all of its destinations in the specified number of days, the packet is returned to the original sending host and one or more electronic mail messages are sent (see the descriptions in the sections Administrator address and Notification).
Specifying cq_default as the storage class sets the expiration period for shipping orders that are not assigned to any storage class and for shipping orders whose storage class is not configured. Exception: When you generate a shipping order with the mkorder command and do not specify a storage class, the shipping order has the expiration period associated with the –default storage class.
A value of 0 (zero) specifies no expiration and delivery is reattempted indefinitely.
This setting is overridden by the –pexpire option to syncreplica or mkreplica.
The shipping_server program does not retry delivery of a packet. The EXPIRATION specification is useful only if you schedule periodic invocations of the shipping server to attempt delivery of any undelivered packets.
ROUTE next-hop host ...
ROUTE next-hop –default
Default: None.
Controls the network routing of packets. Packets whose final destination is any of the host arguments are sent to the host named next-hop. This host is responsible for final delivery of the packet to its destinations (or additional forwarding). next-hop and host can be host names (which must be usable by hosts in different domains) or numeric IP addresses.
You can include multiple ROUTE entries in the configuration file. The special keyword –default accommodates all hosts that are not specified in another ROUTE entry.
RECEIPT-HANDLER storage-class script-pathname
Default: None.
Specifies a script for the shipping server to run for each packet received in a storage bay.
shipping_server handles each packet that is received as follows:
script-pname [ –d/ata packet-file-pname ] [ –a/ctual shipping-order-pname ] [ –s/class storage-class ] –o/rigin hostname
where
script-pname | Script specified in the RECEIPT-HANDLER entry. |
–d/ata packet-file-pname | Location of the packet. This option is used only when the packet is destined for this host. |
–a/ctual shipping-order-pname | Location of the shipping order. This option is used only when the packet is destined for another host. |
–s/class storage-class | Storage class associated with the packet. This option is used only if the packet was associated with a storage class when it was created. |
–o/rigin hostname | Name of the host from which the packet was first sent. |
CLEARCASE_MIN_PORT port-number CLEARCASE_MAX_PORT port-number
Default: None.
These entries specify the range of ports for the shipping server to use on a firewall system, and they are set as environment variables in the shipping server environment.
Guidelines for setting the values:
DOWNHOST-TIMEOUT minutes
Default: Zero.
Specifies the number of minutes for the shipping server to wait before trying to contact a target host that was previously identified as unreachable.
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. The name of the file is the name of the unreachable host. If the value of one of the following parameters is non-zero, the shipping server checks the directory for target hosts during future shipping operations:
If both parameters have a non-zero value, the shipping server uses DOWNHOST-TIMEOUT.
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 value 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 value, the shipping server tries to send packets to the target host. If neither DOWNHOST-TIMEOUT nor the environment variable SHP_DOWNHOST_TIMEOUT_RETRY has a non-zero value, 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.)