shipping.conf

Store-and-forward configuration file

APPLICABILITY

SYNOPSIS

/var/adm/atria/config/shipping.conf

DESCRIPTION

This file controls the operation of the MultiSite store-and-forward facility on each host. The file consists of comment lines (starting with #) and one or more configuration entries.

The shipping.conf file 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/atria/config/shipping.conf does not exist, the installation creates it by copying the template file. If /var/adm/atria/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 ClearCase and MultiSite in the default installation directory (/usr/atria), you must edit the shipping.conf file and change /usr/atria to the pathname of your installation directory.

PACKET SIZE

MAX-DATA-SIZE size [ k | m | g ]

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

• mkreplica -fship

• mkreplica -ship

• syncreplica -fship

• syncreplica -ship

• sync_export_list

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.

Default: 2097151k

NOTIFICATION

NOTIFICATION-PROGRAM e-mail-program-pathname

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

Default: /usr/atria/bin/notify. This program is also used if no NOTIFICATION-PROGRAM entry exists.

ADMINISTRATOR ADDRESS

ADMINISTRATOR e-mail-address

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.

Default: root

STORAGE BAY AND RETURN BAY

STORAGE-BAY storage-class directory-pathname

RETURN-BAY storage-class directory-pathname

These lines define storage bay and return bay directories. A storage bay holds the outgoing and incoming update packets and shipping orders of a particular 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 particular 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 storage bays does not matter.

MultiSite installation establishes a default storage bay and return bay on the local host in the /var/adm/atria/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 within 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.

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.

STORAGE-BAY -default /usr/atria/shipping/ms_ship

RETURN-BAY -default /usr/atria/shipping/ms_rtn

EXPIRATION PERIOD

EXPIRATION storage-class number-of-days

EXPIRATION -default number-of-days

Specifies the expiration period (in days) for shipping orders generated in 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 specified destinations, 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 zero EXPIRATION value 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.

Default: 14 days.

PACKET ROUTING

ROUTE next-hop host ...

ROUTE next-hop -default

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.

Default: None.

RECEIPT HANDLER

RECEIPT-HANDLER storage-class script-pathname

Specifies a script for the shipping_server to run for each packet received in a shipping bay. By default, no script is specified. We recommend that you specify the sync_receive script as the RECEIPT-HANDLER entry. For example:

RECEIPT-HANDLER -default /usr/atria/config/scheduler/tasks/sync_receive

For each packet that is received, shipping_server handles it 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 the packet is not associated with a storage class and there is a RECEIPT-HANDLER value for the -default storage class, shipping_server uses the script specified for -default.

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 parameter is used only when the packet is destined for this host.
-a·ctual shipping-order-pname	Location of the shipping order. This parameter is used only when the packet is destined for another host.
-s·class storage-class	Storage class associated with the packet. This parameter is used only if the packet was associated with a storage class when it was created.
-o·rigin hostname	Host name of the machine 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.

Default: None.

PORT NUMBERS

CLEARCASE_MIN_PORT port-number
CLEARCASE_MAX_PORT port-number

CAUTION: Set these entries only on hosts that can communicate through the firewall and have been installed with the MultiSite shipping_server-only option.

These entries specify the range of ports for 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.

• We recommend that you use the range 49152 through 65535, which is the Dynamic/Private Port Range. If you use a value within the Registered Ports range (1024 through 49151), the shipping.conf parser prints an informational message.

NOTE: To use shipping_server on a firewall system, you must also set the CLEARCASE_MIN_PORT and CLEARCASE_MAX_PORT environment variables in the atria_start script. For more information, see Specifying Port Values.

Default: None.