Store-and-forward configuration file
/var/adm/rational/clearcase/config/shipping.conf
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.
Note: If you do not install MultiSite or the Rational Shipping Server in the default installation directory (/opt/rational/clearcase), you must edit the shipping.conf file and change /opt/rational/clearcase to the pathname of your installation directory.
MAX-DATA-SIZE size [ k | m | g ]
Default: 2097151 KB
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. To specify no limit, use 0 (zero).
This value is used by the following commands (unless you also specify –maxsize):
When you invoke mkreplica or syncreplica with –out or –tape, 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:
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: The –default storage class is used for packets that are not assigned to any storage class, and for packets whose storage class is not configured. This class is created when MultiSite is installed.
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.
Note: Storage class names are case sensitive.
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.
You must create directory-pathname with a standard UNIX 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.
Note: The incoming and outgoing directories must be on the same file system.
EXPIRATION storage-class number-of-days
EXPIRATION –default number-of-days
Default: 14 days.
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 –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.
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 sync_export_list –poll 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 shipping bay. We recommend that you specify the sync_receive script as the RECEIPT-HANDLER entry. For example:
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
Note: If a packet is destined for both the local host and another host, both the –data and –actual parameters are used. The packet is imported at the replica on the host and then forwarded to its next destination.
CLEARCASE_MIN_PORT port-number
CLEARCASE_MAX_PORT port-number
Default: None.
Caution: Set these entries only on hosts that can communicate through the firewall and have been installed with the MultiSite shipping-server-only option. To use the shipping server on a firewall system, you must also set the CLEARCASE_MIN_PORT and CLEARCASE_MAX_PORT environment variables in the clearcase script. For more information, see Specifying Port Values.
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: None.
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 one of the following parameters is set, the shipping server checks the directory for target hosts during future shipping operations:
If both parameters are set, 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 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 neither this setting nor the environment variable SHP_DOWNHOST_TIMEOUT_RETRY is 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.)