MultiSite Control Panel

Configures store-and-forward facility

Applicability

Product Command type
MultiSite Administrative tool
Platform
Windows

Synopsis

%SystemRoot%\System32\ms.cpl

To open the MultiSite Control Panel, double-click the MultiSite icon in Control Panel.

Description

The MultiSite Control Panel controls operation of the store-and-forward facility on each host. It provides controls for setting the configuration parameters described in the following sections. In some cases, the corresponding operation fails if a parameter is not defined, and in other cases there is a hard-coded default.

Maximum packet size

Default: 2097151 KB (2GB-1KB)

Controls the splitting of logical packets into multiple physical packets. This value specifies the maximum size for a physical packet file. Limiting the size of physical packets can improve the reliability of packet delivery in some networks. 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, this value is not used, and you must use –maxsize to limit the packet size.

Administrator e-mail

Default: None.

Specifies the electronic mail address of the user to be notified when any of these events occur:
  • A packet (on the local host) that has expired is returned to its sending host.
  • A packet that was not delivered to its next hop is returned to its sending host.
  • syncreplica –import finds a replica-creation packet.
To enable e-mail notification:
  1. Verify that the SMTP Host field in the ClearCase® Control Panel specifies a valid host. (This field is located on the Options page.)
  2. Enter an e-mail address in the Administrator Email field in the MultiSite Control Panel. You can specify multiple addresses separated by white space.
  3. (optional) Enter a different value in the Email Notification Program Path field.
Specifies the electronic mail address of the user to be notified when any of these events occur:
  • A packet (on the local host) that has expired is returned to its sending host.
  • A packet that was not delivered to its next hop is returned to its sending host.
  • syncreplica –import finds a replica-creation packet.
Note: If you use Rational® ClearQuest® MultiSite and you do not use DevOps Code ClearCase MultiSite, use the control_panel command to specify the SMTP host and the administrator e-mail.
To enable e-mail notification:
  1. Specify the SMTP host to use:
    • If you use DevOps Code ClearCase MultiSite, verify that the SMTP Host field in the ClearCase Control Panel specifies a valid host. (This field is located on the Options page.)
    • If you do not use DevOps Code ClearCase MultiSite, use the control_panel command to specify the SMTP host.
  2. Enter an e-mail address in the Administrator Email field in the MultiSite Control Panel. You can specify only one address.
  3. (Optional) Enter a different value in the Email Notification Program Path field.

Email notification program path

Default: ccase-home-dir\bin\notify.exe

Specifies the electronic mail program to be invoked in the circumstances listed in Administrator e-mail.

Timeout for unreachable host (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 ccase-home-dir\var\shipping\ms_downhost directory. The name of the file is the name of the unreachable host. If the value of the Timeout for Unreachable Host field is non-zero, 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 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 the Timeout for Unreachable Host setting is zero, 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.)

Storage classes

Storage class name

Default: MultiSite installation sets up a default storage class (–default) with predefined values. The –default class is used when you invoke the mkorder, mkreplica, syncreplica, or sync_export_list command with the –fship or –ship option and do not specify a storage class. You can change the values associated with the –default class.

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

Specifies the name of a storage class. For each storage class, you can specify values for packet expiration, the storage bay, the return bay, and the receipt handler.

Note: At most, 64 storage classes can be created and their names are case sensitive.

Packet expiration

Default: When the Use Default Expiration check box is ckecked, the storage class uses the packet expiration value associated with the –default class. (This value is not shown in the Packet Expiration field; you must display the –default class to determine the value.) When MultiSite is installed for the first time, the Packet Expiration value for the –default class is set to 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 its destinations in the specified number of days, the packet is returned to the original sending host and a message is sent to the address specified in the Administrator Email field. If e-mail notification is not enabled, a message is written to the Windows Event Viewer.

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 packets. The Packet Expiration specification is useful only if you set up a host to periodically attempt delivery of any undelivered packets. To set up redelivery attempts, use the schedule command to invoke sync_export_list –poll, which invokes shipping_server –poll. For more information, see the schedule reference page in the DevOps Code ClearCase Command Reference.

Storage bay path

Default: When MultiSite is installed for the first time, the storage bay associated with the –default storage class is ccase-home-dir\var\shipping\ms_ship. This bay contains subdirectories named incoming and outgoing, which hold incoming and outgoing packets. Shipping operations look for packets in these subdirectories.

Default: multiutil commands that use the –sclass option use the cq_default storage class. The mkorder and shipping_server commands use the –default storage class. You must create the cq_default storage class. If you use both DevOps Code ClearCase MultiSite and Rational ClearQuest MultiSite, you must use different storage bays for VOB replica packets and database packets.

Defines the location of the directory that holds the outgoing and incoming update packets and shipping orders of a particular storage class.

Packets placed in a storage bay on an NTFS file system inherit the Windows ACL on the bay. Define ACLs on the storage bays to enable successful execution of MultiSite commands to process the packets and to guard against unauthorized access. (If you use the schedule command to invoke sync_export_list –poll on shipping_server, the group ClearCase must have read and write permissions on all storage directories.) Packets stored on FAT file systems have no protections.

Before using the store-and-forward facility, verify that the disk partition where the ccase-home-dir\var\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. For more information about disk space requirements, see "Planning a MultiSite implementation" in ClearCase MultiSite Administrator's Guide.

Note: When you create a new storage class, the storage bay and return bay that you specify are created. The incoming and outgoing directories in the bays are also created.

Return bay path

Default: When MultiSite is installed, the return bay associated with the –default storage class is ccase-home-dir\var\shipping\ms_rtn. This bay contains subdirectories named incoming and outgoing, which hold incoming and outgoing packets. Shipping operations look for packets in these subdirectories.

Default: multiutil commands that use the –sclass option use the cq_default storage class. The mkorder and shipping_server commands use the –default storage class. You must create the cq_default storage class. If you use both DevOps Code ClearCase MultiSite and Rational ClearQuest MultiSite, you must use different return bays for VOB replica packets and database packets.

Defines the location of the directory that holds the incoming and outgoing packets in the process of being returned to their origin because they could not be delivered to all specified destinations.

Packets placed in a return bay on an NTFS file system inherit the Windows ACL on the bay. Define ACLs on the return bays to enable successful execution of MultiSite commands to process the packets and to guard against unauthorized access. (If you use the schedule command to invoke sync_export_list –poll on shipping_server, the group ClearCase must have read and write permissions on all storage directories.) Packets stored on FAT file systems have no protections.

Receipt handler path

Default: None.

Specifies a batch file or program for the shipping server to run when a packet is received for the storage class. You can use this instead of scheduling executions of sync_receive. By default, no file is specified. It is good practice to use ccase-home-dir\config\scheduler\tasks\sync_receive in the Receipt Handler Path field.

For each packet that is received, shipping_server does the following:

  1. Reads the entries in the MultiSite Control Panel to find the appropriate Receipt Handler value for the packet.
    • If the packet is associated with a storage class and there is a Receipt Handler value for that storage class, shipping_server uses the specified batch file or program. 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 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
    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 forwarded to its next destination.

Routing information

The Routing Information fields control the network routing of packets.

Next routing hop

Default: None.

Specifies the next destination for packets whose final destination is any of the host names specified in the Destination Hostnames list. This host is responsible for delivery of the packet to its destinations. You can specify a host using either its host name (which must be usable by hosts in different domains) or its numeric IP address.

Destination host names

Default: None.

Packets destined for any host listed in this field are sent to the host specified in the Next Routing Hop field. You can specify a host using either its host name (which must be usable by hosts in different domains) or its numeric IP address. The value –default as the Destination Hostname accommodates all hosts that are not associated with a routing hop.