shipping.conf

/var/adm/devops/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/devops/clearcase/config/shipping.conf does not exist, the installation creates it by copying the template file. If /var/adm/devops/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):

• mkreplica –fship
• mkreplica –ship
• syncreplica –fship
• syncreplica –ship
• sync_export_list

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/devops/clearcase/bin/notify. This program is also used if no NOTIFICATION-PROGRAM entry exists.

The electronic mail program to be invoked in these circumstances:

• When shipping_server finds that a shipping order it is about to process has expired
• When an undeliverable packet is returned to the original sending host by another host's shipping_server (see the description of EXPIRATION)
• When syncreplica –import finds a replica-creation packet, which must be processed with a mkreplica command

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

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/devops/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 DevOps Code 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.

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

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 sync_export_list–pollthe 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. It is good practice to specify the sync_receive script as the RECEIPT-HANDLER entry. For example:

RECEIPT-HANDLER  -default
/opt/devops/clearcase/config/scheduler/tasks/sync_receive

shipping_server handles each packet that is received as follows:

1. Reads the shipping.conf file to find the appropriate RECEIPT-HANDLER entry for the packet.
   • If the packet is associated with a storage class and there is a RECEIPT-HANDLER entry for that storage class, shipping_server uses the script-pathname specified in that entry. If no receipt handler is defined for the storage class, but a default receipt handler is defined, the default receipt handler is invoked for that packet.
   • If the packet is not associated with a storage class and there is a RECEIPT-HANDLER value for the –default storage class, shipping_server uses that value.
2. Invokes the receipt handler 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.

   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.

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:

• The value range for CLEARCASE_MIN_PORT is 1024 through 65534.
• The value range for CLEARCASE_MAX_PORT is 1025 through 65535.
• The value of CLEARCASE_MAX_PORT must be greater than the value of CLEARCASE_MIN_PORT.
• It is good practice to use the range 49152 through 65535, which is the Dynamic/Private Port Range.

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/devops/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:

• DOWNHOST-TIMEOUT in the shipping.conf file
• SHP_DOWNHOST_TIMEOUT_RETRY environment variable

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