Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
Managing Serviceguard Fifteenth Edition > Chapter 7 Cluster and Package Maintenance

Configuring a Legacy Package


Technical documentation

Complete book in PDF
» Feedback
Content starts here

 » Table of Contents

 » Index

IMPORTANT: You can still create a new legacy package. If you are using a Serviceguard Toolkit such as Serviceguard NFS Toolkit, consult the documentation for that product.

Otherwise, use this section to maintain and re-work existing legacy packages rather than to create new ones. The method described in , is simpler and more efficient for creating new packages, allowing packages to be built from smaller modules, and eliminating the separate package control script and the need to distribute it manually.

If you decide to convert a legacy package to a modular package, see “Migrating a Legacy Package to a Modular Package”. Do not attempt to convert Serviceguard Toolkit packages.

Creating or modifying a legacy package requires the following broad steps:

  1. Generate the package configuration file

  2. Edit the package configuration file

  3. Generate the package control script

  4. Edit the package control script

  5. Distribute the control script to the cluster nodes

  6. Apply the package configuration file

Each of these tasks is described in the sub-sections that follow.

Creating the Legacy Package Configuration

The package configuration process defines a set of application services that are run by the package manager when a package starts up on a node in the cluster. The configuration also includes a prioritized list of cluster nodes on which the package can run together with definitions of the acceptable types of failover allowed for the package.

You can create a legacy package and its control script in Serviceguard Manager; use the Help for detailed instructions. Otherwise, use the following procedure to create a legacy package.

NOTE: For instructions on creating Veritas special-purpose system multi-node and multi-node packages, see “Configuring Veritas System Multi-node Packages” and “Configuring Veritas Multi-node Packages”.
  1. Create a subdirectory for each package you are configuring in the /etc/cmcluster directory:

    mkdir /etc/cmcluster/pkg1 

    You can use any directory names you like.

  2. Generate a package configuration file for each package, for example:

    cmmakepkg -p /etc/cmcluster/pkg1/pkg1.config 

    You can use any file name you like for the configuration file.

  3. Edit each configuration file to specify package name, prioritized list of nodes (with 39 bytes or less in the name), the location of the control script, and failover parameters for each package. Include the data you recorded on the Package Configuration Worksheet.

Configuring a Package in Stages

It is a good idea to configure failover packages in stages, as follows:

  1. Configure volume groups and mount points only.

  2. Distribute the control script to all nodes.

  3. Apply the configuration.

  4. Run the package and ensure that it can be moved from node to node.

  5. Halt the package.

  6. Configure package IP addresses and application services in the control script.

  7. Distribute the control script to all nodes.

  8. Run the package and ensure that applications run as expected and that the package fails over correctly when services are disrupted.

Editing the Package Configuration File

Edit the file you generated with cmmakepkg. Use the bullet points that follow as a checklist.

NOTE: HP strongly recommends that you never edit the package configuration file of a CVM/CFS multi-node or system multi-node package, although Serviceguard does not prohibit it. Create VxVM-CVM-pkg and SG-CFS-pkg by issuing the cmapplyconf command. Create and modify SG-CFS-DG-id# and SG-CFS-MP-id# using the cfs commands listed in Appendix A “Serviceguard Commands”.
  • PACKAGE_TYPE. Enter the package type; see “Types of Package: Failover, Multi-Node, System Multi-Node” and package_type.

    NOTE: For modular packages, the default form for parameter names in the package configuration file is lower case; for legacy packages the default is upper case. There are no compatibility issues; Serviceguard is case-insensitive as far as the parameter names are concerned.

    Because this section is intended to be used primarily when you reconfiguring an existing legacy package, we are using the legacy parameter names (in upper case) for sake of continuity. But if you generate the configuration file using cmmakepkg or cmgetconf, you will see the parameter names as they appear in modular packages; see the notes below and the “Package Parameter Explanations” for details of the name changes.

  • FAILOVER_POLICY. For failover packages, enter the failover_policy.

  • FAILBACK_POLICY. For failover packages, enter the failback_policy.

  • NODE_NAME. Enter the node or nodes on which the package can run; see node_name.

  • AUTO_RUN. Configure the package to start up automatically or manually; see auto_run.

  • LOCAL_LAN_FAILOVER_ALLOWED. Enter the policy for local_lan_failover_allowed.

  • NODE_FAIL_FAST_ENABLED. Enter the policy for node_fail_fast_enabled.

  • RUN_SCRIPT and HALT_SCRIPT. Specify the pathname of the package control script (described in the next section). No default is provided. Permissions on the file and directory should be set to rwxr-xr-x or r-xr-xr-x (755 or 555).

    (Script timeouts): Enter the run_script_timeout and halt_script_timeout.

    SCRIPT_LOG_FILE. (optional). Specify the full pathname of the file where the RUN_SCRIPT and HALT_SCRIPT will log messages. If you do not specify a path, Serviceguard will create a file with “.log” appended to each script path, and put the messages in that file.

  • STORAGE_GROUP. Specify the names of any CVM storage groups that will be used by this package. Enter each storage group (CVM disk group) on a separate line. Note that CVM storage groups are not entered in the cluster configuration file.

    NOTE: You should not enter LVM volume groups or VxVM disk groups in this file.

  • If your package has relocatable IP addresses, enter the SUBNET if you want it to be monitored (this means the package will stop if the subnet fails).

    This must be a subnet that is already specified in the cluster configuration, and it can be either an IPv4 or an IPv6 subnet. Must not be a link-local subnet (link-local package IPs are not allowed). See monitored_subnet.

    IMPORTANT: For cross-subnet configurations, see “Configuring Cross-Subnet Failover”.
  • If your package runs services, enter the SERVICE_NAME (see service_name) and values for SERVICE_FAIL_FAST_ENABLED (see service_fail_fast_enabled) and SERVICE_HALT_TIMEOUT (see service_halt_timeout). Enter a group of these three for each service.

    IMPORTANT: Note that the rules for valid SERVICE_NAMEs are more restrictive as of A.11.18.
  • To configure monitoring for a registered resource, enter values for the following parameters.





    For more information, see “Parameters for Configuring EMS Resources”, and the resource_ parameter descriptions starting on resource_name.

    NOTE: For legacy packages, DEFERRED resources must be specified in the package control script.
  • ACCESS_CONTROL_POLICY. You can grant a non-root user PACKAGE_ADMIN privileges for this package.

    See the entries for user_name, user_host, and user_role on user_name, and “Controlling Access to the Cluster”, for more information.

  • If the package will depend on another package, enter values for DEPENDENCY_NAME, DEPENDENCY_CONDITION, and DEPENDENCY_LOCATION.

    For more information, see the corresponding parameter descriptions starting on dependency_name, and “About Package Dependencies”.

Creating the Package Control Script

For legacy packages, the package control script contains all the information necessary to run all the services in the package, monitor them during operation, react to a failure, and halt the package when necessary. You can use Serviceguard Manager, HP-UX commands, or a combination of both, to create or modify the package control script.

Each package must have a separate control script, which must be executable.

For security reasons, the control script must reside in a directory with the string cmcluster in the path. The control script is placed in the package directory and is given the same name as specified in the RUN_SCRIPT and HALT_SCRIPT parameters in the package configuration file. The package control script template contains both the run instructions and the halt instructions for the package. You can use a single script for both run and halt operations, or, if you wish, you can create separate scripts.

IMPORTANT: Serviceguard automatically creates the necessary control scripts when you create the CFS/CVM (4.1 and later) multi-node or system multi-node package. HP strongly recommends that you never edit the configuration or control script files for these packages, although Serviceguard does not forbid it. Create and modify the information using cfs admin commands only.

Use cmmakepkg to create the control script, then edit the control script. Use the following procedure to create the template for the sample failover package pkg1.

First, generate a control script template, for example:

cmmakepkg -s /etc/cmcluster/pkg1/pkg1.sh 

Next, customize the script; see “Customizing the Package Control Script ”.

Customizing the Package Control Script

You need to customize as follows; see the relevant entries under “Editing the Configuration File” for more discussion.

  • Update the PATH statement to reflect any required paths needed to start your services.

  • If you are using LVM, enter the names of volume groups to be activated using the VG[] array parameters, and select the appropriate options for the storage activation command, including options for mounting and unmounting filesystems, if desired. Do not use the VXVM_DG[] or CVM_DG[] parameters for LVM volume groups.

  • If you are using CVM, enter the names of disk groups to be activated using the CVM_DG[] array parameters, and select the appropriate storage activation command, CVM_ACTIVATION_CMD. Do not use the VG[] or VXVM_DG[] parameters for CVM disk groups.

  • If you are using VxVM disk groups without CVM, enter the names of VxVM disk groups that will be imported using the VXVM_DG[] array parameters. Enter one disk group per array element. Do not use the CVM_DG[] or VG[] parameters for VxVM disk groups without CVM, and do not specify an activation command.

    Do not include CFS-based disk groups in the package control script; on systems that support CFS and CVM, they are activated by the CFS multi-node packages before standard packages are started.

  • If you are using mirrored VxVM disks, specify the mirror recovery option VXVOL.

  • Add the names of logical volumes and the file system that will be mounted on them.

  • Select the appropriate options for the storage activation command (not applicable for basic VxVM disk groups), and also include options for mounting filesystems, if desired.

  • Specify the filesystem mount and unmount retry options.

  • If your package uses a large number of volume groups or disk groups or mounts a large number of file systems, consider increasing the number of concurrent vgchange, mount/umount, and fsck operations;

  • Define IP subnet and IP address pairs for your package. IPv4 or IPv6 addresses are allowed.

  • Add service name(s).

  • Add service command(s)

  • Add a service restart parameter, if you so decide.

    For more information about services, see the discussion of the service_ parameters that starts on service_name.

  • Specify whether or not to kill processes accessing raw devices; see the comments in the file under RAW DEVICES for more information.

Adding Customer Defined Functions to the Package Control Script

You can add additional shell commands to the package control script to be executed whenever the package starts or stops. Enter these commands in the CUSTOMER DEFINED FUNCTIONS area of the script.

If your package needs to run short-lived processes, such as commands to initialize or halt a packaged application, you can also run these from the CUSTOMER DEFINED FUNCTIONS.

You can also use the CUSTOMER DEFINED FUNCTIONS to determine why a package has shut down; see “Determining Why a Package Has Shut Down”.

An example of this portion of the script follows, showing the date and echo commands logging starts and halts of the package to a file.


# This function is a place holder for customer defined functions.
# You should define all actions you want to happen here, before the service is
# started. You can create as many functions as you need.

function customer_defined_run_cmds
# ADD customer defined run commands.
: # do nothing instruction, because a function must contain some command.
date >> /tmp/pkg1.datelog
echo 'Starting pkg1' >> /tmp/pkg1.datelog
test_return 51

# This function is a place holder for customer defined functions.
# You should define all actions you want to happen here, before the service is
# halted.

function customer_defined_halt_cmds
# ADD customer defined halt commands.
: # do nothing instruction, because a function must contain some command.
date >> /tmp/pkg1.datelog
echo 'Halting pkg1' >> /tmp/pkg1.datelog
test_return 52

Adding Serviceguard Commands in Customer Defined Functions

You can add Serviceguard commands (such as cmmodpkg) in the Customer Defined Functions section of a package control script. These commands must not interact with the package itself.

If a Serviceguard command interacts with another package, be careful to avoid command loops. For instance, a command loop might occur under the following circumstances. Suppose pkg1 does a cmmodpkg -d of pkg2, and pkg2 does a cmmodpkg -d of pkg1. If both pkg1 and pkg2 start at the same time, pkg1 tries to cmmodpkg pkg2. However, that cmmodpkg command has to wait for pkg2 startup to complete. pkg2 tries to cmmodpkg pkg1, but pkg2 has to wait for pkg1 startup to complete, thereby causing a command loop.

To avoid this situation, it is a good idea to always specify a RUN_SCRIPT_TIMEOUT and a HALT_SCRIPT_TIMEOUT for all packages, especially packages that use Serviceguard commands in their control scripts. If a timeout is not specified and your configuration has a command loop as described above, inconsistent results can occur, including a hung cluster.

Support for Additional Products

The package control script template provides exits for use with additional products, including Metrocluster with Continuous Access/XP and EVA, Metrocluster with EMC SRDF, and the HA NFS toolkit. Refer to the additional product’s documentation for details about how to create a package using the hooks that are provided in the control script.

Verifying the Package Configuration

Serviceguard checks the configuration you create and reports any errors.

For legacy packages, you can do this in Serviceguard Manager: click Check to verify the package configuration you have done under any package configuration tab, or to check changes you have made to the control script. Click Apply to verify the package as a whole. See the local Help for more details.

If you are using the command line, use the following command to verify the content of the package configuration you have created:

cmcheckconf -v -P /etc/cmcluster/pkg1/pkg1.config

Errors are displayed on the standard output. If necessary, edit the file to correct any errors, then run the command again until it completes without errors.

The following items are checked (whether you use Serviceguard Manager or cmcheckconf command):

  • Package name is valid, and at least one NODE_NAME entry is included.

  • There are no duplicate parameter entries.

  • Values for parameters are within permitted ranges.

  • Run and halt scripts exist on all nodes in the cluster and are executable.

  • Run and halt script timeouts are less than 4294 seconds.

  • Configured resources are available on cluster nodes.

  • If a dependency is configured, the dependency package must already be configured in the cluster.

Distributing the Configuration

You can use Serviceguard Manager or HP-UX commands to distribute the binary cluster configuration file among the nodes of the cluster.

DSAU (Distributed Systems Administration Utilities) can help you streamline your distribution; see “What are the Distributed Systems Administration Utilities?”.

Distributing the Configuration And Control Script with Serviceguard Manager

When you have finished creating a legacy package in Serviceguard Manager, click Apply Configuration. If the package control script has no errors, it is converted to a binary file and distributed to the cluster nodes.

Copying Package Control Scripts with HP-UX commands

IMPORTANT: In a cross-subnet configuration, you cannot use the same package control script on all nodes if the package uses relocatable IP addresses. See “Configuring Cross-Subnet Failover”.

Use HP-UX commands to copy legacy package control scripts from the node where you created the files, to the same pathname on all nodes which can possibly run the package. Use your favorite method of file transfer (e. g., rcp or ftp). For example, from ftsys9, you can issue the rcp command to copy the package control script to ftsys10:

rcp /etc/cmcluster/pkg1/control.sh \ ftsys10:/etc/cmcluster/pkg1/control.sh 

Distributing the Binary Cluster Configuration File with HP-UX Commands

Use the following steps from the node on which you created the cluster and package configuration files:

  • Verify that the configuration file is correct. Use the following command:

    cmcheckconf -C /etc/cmcluster/cmcl.config -P \ 

  • Activate the cluster lock volume group so that the lock disk can be initialized:

    vgchange -a y /dev/vg01 

  • Generate the binary configuration file and distribute it across the nodes.

    cmapplyconf -v -C /etc/cmcluster/cmcl.config -P \ 

  • If you are using a lock disk, deactivate the cluster lock volume group.

    vgchange -a n /dev/vg01 

The cmapplyconf command creates a binary version of the cluster configuration file and distributes it to all nodes in the cluster. This action ensures that the contents of the file are consistent across all nodes.

NOTE: You must use cmcheckconf and cmapplyconf again any time you make changes to the cluster and package configuration files.

Configuring Cross-Subnet Failover

To configure a legacy package to fail over across subnets (see “Cross-Subnet Configurations”), you need to do some additional configuration.

NOTE: You cannot use Serviceguard Manager to configure cross-subnet packages.

Suppose that you want to configure a package, pkg1, so that it can fail over among all the nodes in a cluster comprising NodeA, NodeB, NodeC, and NodeD.

NodeA and NodeB use subnet, which is not used by NodeC and NodeD; and NodeC and NodeD use subnet, which is not used by NodeA and NodeB. (See “Obtaining Cross-Subnet Information” for sample cmquerycl output).

Configuring node_name

First you need to make sure that pkg1 will fail over to a node on another subnet only if it has to. For example, if it is running on NodeA and needs to fail over, you want it to try NodeB, on the same subnet, before incurring the cross-subnet overhead of failing over to NodeC or NodeD.

Assuming nodeA is pkg1’s primary node (where it normally starts), create node_name entries in the package configuration file as follows:

node_name nodeA

node_name nodeB

node_name nodeC

node_name nodeD

Configuring monitored_subnet_access

In order to monitor subnet or, you would configure monitored_subnet and monitored_subnet_access in pkg1’s package configuration file as follows:


monitored_subnet_access PARTIAL


monitored_subnet_access PARTIAL

NOTE: Configuring monitored_subnet_access as FULL (or not configuring monitored_subnet_access) for either of these subnets will cause the package configuration to fail, because neither subnet is available on all the nodes.

Creating Subnet-Specific Package Control Scripts

Now you need to create control scripts to run the package on the four nodes.

IMPORTANT: In a cross-subnet configuration, you cannot share a single package control script among nodes on different subnets if you are using relocatable IP addresses. In this case you will need to create a separate control script to be used by the nodes on each subnet.

In our example, you would create two copies of pkg1’s package control script, add entries to customize it for subnet or, and copy one of the resulting scripts to each node, as follows.

Control-script entries for nodeA and nodeB

IP[0] =


IP[1] =


Control-script entries for nodeC and nodeD

IP[0] =


IP[1] =


Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© Hewlett-Packard Development Company, L.P.