Installing and Configuring Sun Cluster HA for Sun ONE Directory Server

This chapter describes the procedures to install and configure Sun Cluster HA for Sun ONE Directory Server. This data service was formerly known as Sun Cluster HA for Netscape^TM LDAP and Sun Cluster HA for iPlanet Directory Server. Some error messages from the application might use the name Netscape LDAP, but they refer to Sun ONE Directory Server. The application name on the Sun Cluster Agents CD-ROM might still be iPlanet Directory Server.

The procedures in this chapter apply to Netscape HTTP, version 4.1.6 and iPlanet Directory Server, versions 5.0 and 5.1. For later versions of iPlanet Directory Server (now known as Sun ONE Directory Server), see the Sun ONE documentation included with the data service.

This chapter contains the following procedures.

• How to Configure and Activate Network Resources

• How to Install Sun ONE Directory Server for Solaris 8

• How to Install Sun ONE Directory Server for Solaris 9

• How to Configure Sun ONE Directory Server

• How to Install the Sun Cluster HA for Sun ONE Directory Server Packages by Using the Web Start Program

• How to Install Sun Cluster HA for Sun ONE Directory Server Packages by Using the scinstall Utility

• How to Complete the Sun Cluster HA for Sun ONE Directory Server Configuration

• How to Configure SUNW.HAStoragePlus Resource Type

You must configure Sun Cluster HA for Sun ONE Directory Server as a failover data service. See “Planning for Sun Cluster Data Services” in Sun Cluster 3.1 Data Service Planning and Administration Guide and the Sun Cluster 3.1 Concepts Guide document for general information about data services, resource groups, resources, and other related topics.

You can use SunPlex Manager to install and configure this data service. See the SunPlex Manager online help for details.

Planning the Installation and Configuration

Use this section in conjunction with the worksheets in the Sun Cluster 3.1 Release Notes as a checklist before installation and configuration.

Consider the following points before you start your installation.

• Where will the server root reside?

  You can store files and data that do not change on the local file system of each cluster node. However, place dynamic data on the cluster file system so that you can view or update the data from any cluster node.

• If you plan to use multiple Sun ONE Directory Server instances on a node, you must set the nsslapd-listenhost directive with the appropriate network resource as the IP address. This setting is necessary because the default Sun ONE Directory Server behavior is for the instance to bind to all IP addresses on the node.

  For example, to set up a particular instance to use the network resource nds-1, use the following entry.

  nsslapd-listenhost: nds-1.

  This setting causes the instance to bind to the network resource nds-1 only, rather than to all of the IP addresses on the node.

• The Sun ONE Directory Server administrative server is case-sensitive in its consideration of hostnames. Therefore, all hostnames specified in the Sun ONE Directory Server configuration for the administrative server must match their case with the Sun ONE Directory Server specification in the name service in use on the cluster node. This case-matching is particularly important because the DNS domain name must also match the host-name specification in the Sun ONE Directory Server configuration.

  Be sure that the case of the fully qualified domain name of the machine for Sun ONE Directory Server matches the case of the domain name that the resolver returns. For example, if the DNS resolver returns Eng.Sun.COM as the domain name (note the mixed case), you must identically spell that name when you configure the Sun ONE Directory Server administrative server.

Installing and Configuring Sun Cluster HA for Sun ONE Directory Server

The following table lists the sections that describe the installation and configuration tasks.

If you run multiple data services in your Sun Cluster configuration, you can set up the data services in any order, with the following exception. You must set up Sun Cluster HA for DNS before you set up Sun ONE Directory Server. See Sun Cluster 3.1 Data Service for Domain Name Service (DNS) for details. DNS software is included in the Solaris operating environment. If the cluster is to obtain the DNS service from another server, configure the cluster to be a DNS client first.

After installation, use only the cluster administration command scswitch(1M) to manually start and stop Sun ONE Directory Server. See the man page for details. After you start Sun ONE Directory Server, the Sun Cluster software controls it.

Configuring and Activating Network Resources

Before you install and configure Sun ONE Directory Server, set up the network resources that the server will attempt to use after the server has been installed and configured. To configure and activate the network resources, use the following command-line procedure.

How to Configure and Activate Network Resources

To perform this procedure, you need the following information about your configuration.

• The names of the cluster nodes that can master the data service.

• The network resource that clients use to access Sun Cluster HA for Sun ONE Directory Server. Normally, you set up this hostname when you install the cluster. See the Sun Cluster 3.1 Concepts Guide document for details on network resources.

Perform this procedure on any cluster member.

1. Become superuser on a cluster member.

2. Verify that all of the network addresses that you use have been added to your name service database.

   You should have performed this verification during the Sun Cluster installation. See the planning chapter in the Sun Cluster 3.1 Software Installation Guide for details.

   ---

   Note –

   To avoid any failures because of name service lookup, ensure that all of the logical hostnames and shared addresses are present in the /etc/inet/hosts file on all of the cluster nodes. Configure name service mapping in the /etc/nsswitch.conf file on the servers to first check the local files before trying to access NIS, NIS+, or DNS.

   ---

3. Create a failover resource group to hold the network and application resources.

   # scrgadm -a -g resource-group [-h nodelist]

   -g resource-group

   Specifies the name of the resource group. This name can be your choice.

   [-h nodelist]

   Specifies an optional comma-separated list of physical node names or Sun ONE Directory Server that identify potential masters. The order here determines the order in which the nodes are considered as primary during failover.

   ---

   Note –

   Use the -h option to specify the order of the node list. If all of the nodes in the cluster are potential masters, you do not need to use the -h option.

   ---

4. Add network resources to the resource group.

   For example, run the following command to add a logical hostname to a resource group.

   # scrgadm -a -L -g resource-group -l hostname, …[-n netiflist]

   -L

   Specifies that a network resource is being added.

   -g resource-group

   Specifies the name of the resource group.

   -l hostname, …

   Specifies a comma-separated list of network resources.

   -n netiflist

   Specifies an optional, comma-separated list that identifies the IP Networking Multipathing groups that are on each node. Each element in netiflist must be in the form of netif@node. netif can be given as an IP Networking Multipathing group name, such as sc_ipmp0. The node can be identified by the node name or node ID, such as sc_ipmp0@1 or sc_ipmp@phys-schost-1.

   ---

   Note –

   Sun Cluster does not currently support using the adapter name for netif.

   ---

5. Verify that all of the network resources that you use have been added to your name service database.

   You should have performed this verification during the Sun Cluster installation. See the planning chapter in the Sun Cluster 3.1 Software Installation Guide for details.

6. Run the scswitch command to enable the resource group and bring the resource group online.

   # scswitch -Z -g resource-group

   -Z

   Moves the resource group to the MANAGED state, and brings the resource group online.

   -g resource-group

   Specifies the name of the resource group.

Where to Go From Here

After you configure and activate the network resources, go to Installing and Configuring Sun ONE Directory Server.

Installing and Configuring Sun ONE Directory Server

Sun Cluster HA for Sun ONE Directory Server is the Sun ONE Directory Server that uses Netscape Lightweight Directory Access Protocol (LDAP) and runs under the control of the Sun Cluster software. This section describes the steps to install Sun ONE Directory Server and enable Sun ONE Directory Server to run as Sun Cluster HA for Sun ONE Directory Server.

The Sun ONE Directory Server software requires some variation from the default installation parameters. When you install and configure Sun ONE Directory Server, consider the following points.

• For the service to fail over correctly, when prompted for the computer name, instead of specifying a physical machine, you must specify a network resource (IP address) that can fail over between nodes. This requirement means that before you begin the installation, you must set up the network resource in your name services. You normally perform this step as part of the Sun Cluster installation. See the Sun Cluster 3.1 Concepts Guide document for details on network resources.

• Do not use the default server root disk path when prompted. Place your files on the cluster file system.

Do not remove or relocate any of the installed files or directories that the Sun ONE Directory Server installation places on the cluster file system. For example, do not relocate any of the client binaries, such as ldapsearch, that are installed with the rest of the Sun ONE Directory Server software.

To install Sun ONE Directory Server, see one of the following sections.

• How to Install Sun ONE Directory Server for Solaris 8

• How to Install Sun ONE Directory Server for Solaris 9

How to Install Sun ONE Directory Server for Solaris 8

This procedure describes the interaction with the Sun ONE or iPlanetsetup command. Only the sections that are specific to Sun Cluster HA for Sun ONE Directory Server are included here. For the other sections, choose or change the default values as appropriate. This procedure includes only basic steps. See the Sun ONE Directory Server documentation for details.

1. Become superuser on a cluster member.

2. Run the setup command from the install directory on the Sun ONE or iPlanet CD.

3. From setup, choose the menu items to install Sun ONE Directory Server with a custom installation.

   Custom installation allows you to specify the physical hostname for the administrative server. This enables you to access the administrative server whether the logical host is up or down.

4. For the install location, select a location on the cluster file system, for example, /global/nsldap.

   ---

   Note –

   The logical host that you specify must be online on the node from which you run the Sun ONE Directory Server installation. This state is necessary because at the end of the Sun ONE Directory Server installation, Sun ONE Directory Server automatically starts and will fail if the logical host is offline on that node.

   ---

5. Select the network resource along with your domain for the computer name, for example, phys-schost-1.eng.sun.com.

   Supply the hostname that is associated with a network resource when the setup command prompts you for the full server name.

6. When prompted for the IP address to be used as the Sun ONE Directory Server Administrative Server, specify an IP address for one of the cluster nodes.

As part of the installation, you set up an Sun ONE Directory Server Administrative Server. The IP address that you specify for this server must be that of a physical cluster node, not the name of the logical host that will fail over.

Where to Go From Here

After you configure and activate the network resources, go to How to Configure Sun ONE Directory Server.

How to Install Sun ONE Directory Server for Solaris 9

The Sun ONE Directory Server is bundled with the Solaris 9.0 operating system. If you are using Solaris 9.0, use the Solaris 9.0 CDs to install the Sun ONE Directory Server.

1. Install the Sun ONE Directory Server packages (these packages might be called iPlanet Directory Server) on all the nodes of the cluster, if they are not already installed.

2. Identify a location on a global file system where you intend to keep all your directory servers (for example, /global/nsldap).

   If you want to, you may create a separate directory for this file system.

3. On all nodes, create a link to this directory from /var/ds5. If /var/ds5 already exists on a node, remove it and create the link.

   # rmdir /var/ds5 # ln -s /global/nsldap /var/ds5

4. On any one node, set up the directory server(s) in the usual way.

   # directoryserver setup

   On this node, a link, /usr/iplanet/ds5/slapd-<instance-name>, will be created automatically. On all other nodes, create the link manually

   In the following example, dixon-1 is the name of the Directory Server.

   # ln -s /var/ds5/slapd-dixon-1 /usr/iplanet/ds5/slapd-dixon-1

5. Supply the logical hostname when the setup command prompts you for the server name.

   This step is required for failover to work correctly.

   ---

   Note –

   The logical host that you specify must be online on the node from which you run the directoryserver setup command. This state is necessary because at the end of the Sun ONE Directory Server installation, Sun ONE Directory Server automatically starts and will fail if the logical host is offline on that node.

   ---

6. If prompted for the logical hostname, select the logical hostname along with your domain for the computer name, for example, phys-schost-1.eng.sun.com.

   Supply the hostname that is associated with a network resource if the setup command prompts you for the full server name.

7. If prompted for the IP address to be used as the Sun ONE Directory Server Administrative Server, specify the IP address of the cluster node on which you are running directoryserver setup.

As part of the installation, you set up an Sun ONE Directory Server Administrative Server. The IP address that you specify for this server must be that of a physical cluster node, not the name of the logical host that will fail over.

Where to Go From Here

After you configure and activate the network resources, go to How to Configure Sun ONE Directory Server.

How to Configure Sun ONE Directory Server

• Use the Sun ONE Administration Server to configure and test Sun ONE Directory Server.

  See your Sun ONE or iPlanet documentation for details.

  After completing the configuration, Sun ONE Directory Server starts automatically. Before you proceed to the next part of the installation and configuration process, you must use stop-slapd to stop the server.

Where to Go From Here

If you have not installed the data service packages for Sun ONE Directory Server from the Sun Cluster Agents CD-ROM, go to Installing Sun Cluster HA for Sun ONE Directory Server Packages. If you have installed the packages, go to Completing the Sun Cluster HA for Sun ONE Directory Server Configuration.

Installing Sun Cluster HA for Sun ONE Directory Server Packages

If you did not install the Sun Cluster HA for Sun ONE Directory Server packages during your initial Sun Cluster installation, perform this procedure to install the packages. Perform this procedure on each cluster node where you are installing the Sun Cluster HA for Sun ONE Directory Server packages. To complete this procedure, you need the Sun Cluster Agents CD-ROM.

If you are installing more than one data service simultaneously, perform the procedure in “Installing the Software” in Sun Cluster 3.1 10/03 Software Installation Guide.

Install the Sun Cluster HA for Sun ONE Directory Server packages by using one of the following installation tools:

• The Web Start program

• The scinstall utility

The Web Start program is not available in releases earlier than Sun Cluster 3.1 Data Services 10/03.

How to Install the Sun Cluster HA for Sun ONE Directory Server Packages by Using the Web Start Program

You can run the Web Start program with a command-line interface (CLI) or with a graphical user interface (GUI). The content and sequence of instructions in the CLI and the GUI are similar. For more information about the Web Start program, see the installer(1M) man page.

1. On the cluster node where you are installing the Sun Cluster HA for Sun ONE Directory Server packages, become superuser.

2. (Optional) If you intend to run the Web Start program with a GUI, ensure that your DISPLAY environment variable is set.

3. Load the Sun Cluster Agents CD-ROM into the CD-ROM drive.

   If the Volume Management daemon vold(1M) is running and configured to manage CD-ROM devices, it automatically mounts the CD-ROM on the /cdrom/scdataservices_3_1_vb directory.

4. Change to the Sun Cluster HA for Sun ONE Directory Server component directory of the CD-ROM.

   The Web Start program for the Sun Cluster HA for Sun ONE Directory Server data service resides in this directory.

   # cd /cdrom/scdataservices_3_1_vb/\ components/SunCluster_HA_SunONE_Directory_Server_3.1

5. Start the Web Start program.

   # ./installer

6. When you are prompted, select the type of installation.

   • To install only the C locale, select Typical.

   • To install other locales, select Custom.

7. Follow instructions on the screen to install the Sun Cluster HA for Sun ONE Directory Server packages on the node.

   After the installation is finished, the Web Start program provides an installation summary. This summary enables you to view logs that the Web Start program created during the installation. These logs are located in the /var/sadm/install/logs directory.

8. Exit the Web Start program.

9. Unload the Sun Cluster Agents CD-ROM from the CD-ROM drive.

   1. To ensure that the CD-ROM is not being used, change to a directory that does not reside on the CD-ROM.

   2. Eject the CD-ROM.

      # eject cdrom

Where to Go From Here

See Completing the Sun Cluster HA for Sun ONE Directory Server Configuration to register Sun Cluster HA for Sun ONE Directory Server and to configure the cluster for the data service.

How to Install Sun Cluster HA for Sun ONE Directory Server Packages by Using the scinstall Utility

1. Load the Sun Cluster Agents CD-ROM into the CD-ROM drive.

2. Run the scinstall utility with no options.

   This step starts the scinstall utility in interactive mode.

3. Choose the menu option, Add Support for New Data Service to This Cluster Node.

   The scinstall utility prompts you for additional information.

4. Provide the path to the Sun Cluster Agents CD-ROM.

   The utility refers to the CD as the “data services cd.”

5. Specify the data service to install.

   The scinstall utility lists the data service that you selected and asks you to confirm your choice.

   ---

   Note –

   The application name on the CD-ROM might be iPlanet Directory Server.

   ---

6. Exit the scinstall utility.

7. Unload the CD from the drive.

Where to Go From Here

See Completing the Sun Cluster HA for Sun ONE Directory Server Configuration to register Sun Cluster HA for Sun ONE Directory Server and to configure the cluster for the data service.

Completing the Sun Cluster HA for Sun ONE Directory Server Configuration

This procedure describes how to use the scrgadm command to register and configure Sun Cluster HA for Sun ONE Directory Server.

Other options also enable you to register and configure the data service. See “Tools for Data Service Resource Administration” in Sun Cluster 3.1 Data Service Planning and Administration Guide for details about these options.

To perform this procedure, you need the following information about your configuration.

• The name of the resource type for Sun Cluster HA for Sun ONE Directory Server. This name is SUNW.nsldap.

• The names of the cluster nodes that can master the data service.

• The network resource that clients use to access Sun Cluster HA for Sun ONE Directory Server. Normally, you set up this network resource when you install the cluster. See the Sun Cluster 3.1 Concepts Guide document for details on network resources.

• The path to the Sun ONE Directory Server application binaries that are the resources for Sun Cluster HA for Sun ONE Directory Server. You can install the binaries on the local disks or the cluster file system. See “Planning for Sun Cluster Data Services” in Sun Cluster 3.1 Data Service Planning and Administration Guide for a discussion of the advantages and disadvantages of each location.

• The port where Sun ONE Directory Server listens. For non-secure instances, the Port_list standard resource property for the Sun ONE Directory Server resource defaults to 389/tcp, and the value for the secure port is 636/tcp. If you set the port to a number other than 389, you must specify that value when you configure the Port_list property. See “Administering Data Service Resources” in Sun Cluster 3.1 Data Service Planning and Administration Guide for instructions on how to set resource properties.

Perform this procedure on any cluster member.

How to Complete the Sun Cluster HA for Sun ONE Directory Server Configuration

The fault monitor determines whether the Sun Cluster HA for Sun ONE Directory Server instance is secure or non-secure. The monitor probes secure and non-secure directory servers differently. If you have created a password file, the instance is determined to be secure. If you have not created a password file, the instance is determined to be non-secure. The password file is named keypass and is in a different format than iPlanet's password file. The keypass file contains only the password for which a secure instance of directory server prompts when started manually. This password file is located in the same directory as the start-slapd program that is used to start this instance of the directory server.

If Sun ONE Directory Server is in secure mode, then the path name must also contain a file named keypass, which contains the secure key password that is needed to start this instance. If a keypass file exists, then Sun Cluster HA for Sun ONE Directory Server assumes that the keypass instance is secure.

Perform the following steps to complete your configuration.

1. Become superuser on a cluster member.

2. Register the resource type for the data service.

   # scrgadm -a -t SUNW.nsldap

   -a

   Adds the data service resource type.

   -t SUNW.nsldap

   Specifies the predefined resource type name.

3. Add the Sun ONE Directory Server application resource to the failover resource group that you created for your network resources.

   The resource group that contains the application resources is the same resource group that you created for your network resources in How to Configure and Activate Network Resources.

   # scrgadm -a -j resource -g resource-group \ -t SUNW.nsldap [-y Network_resources_used=network-resource, …] \ -y Port_list=port-number/protocol -x Confdir_list=pathname

   -j resource

   Specifies the Sun ONE Directory Server application resource name.

   -y Network_resources_used=network-resource

   Specifies a comma-separated list of network resources (logical hostnames or shared addresses) in resource-group, which the Sun ONE Directory Server application resource must use.

   -t SUNW.nsldap

   Specifies the type of resource to add.

   -y Port_list=port-number/protocol

   Specifies a port number and the protocol to be used, for example, 389/tcp. The Port_list property must have one or two entries.

   -x Confdir_list=pathname

   Specifies a path for your Sun ONE Directory Server configuration directory. The Confdir_list extension property is required. The Confdir_list property must have exactly one entry.

4. Enable the resource and its monitor.

   # scswitch -e -j resource

   -e

   Enables the resource and its monitor.

   -g resource

   Specifies the name of the application resource that is being enabled.

Example–Registering and Configuring Sun Cluster HA for Sun ONE Directory Server

This example shows how to register Sun Cluster HA for Sun ONE Directory Server.

Cluster Information
Node names: phys-schost-1, phys-schost-2
Logical hostname: schost-1
Resource group: resource-group-1 (for all resources)
Resources: schost-1 (logical hostname),
	nsldap-1 (Sun ONE Directory Server application resource) 
 
(Create a failover resource group.)
# scrgadm -a -g resource-group-1 -h phys-schost-1,phys-schost-2
 
(Add a logical hostname resource to the resource group.)
# scrgadm -a -L -g resource-group-1 -l schost-1
 
(Bring the resource group online.)
# scswitch -Z -g resource-group-1
 
(Install and configure Sun ONE Directory Server.)

(To install and configure the iPlanet Directory Server, run the 
“setup” program from the node that is currently hosting the logical
hostname.”
 
(Stop the Sun ONE Directory Server server.)
 
(Register the SUNW.nsldap resource type.)
# scrgadm -a -t SUNW.nsldap
 
(Create an Sun ONE Directory Server resource and add it to the 
resource group.)
# scrgadm -a -j nsldap-1 -g resource-group-1 \
-t SUNW.nsldap -y Network_resources_used=schost-1 \
-y Port_list=389/tcp \
-x Confdir_list=/global/nsldap/slapd-schost-1
 
(Enable the application resources.)
# scswitch -e -j nsldap-1

How to Configure SUNW.HAStoragePlus Resource Type

The SUNW.HAStoragePlus resource type was introduced in Sun Cluster 3.0 5/02. This new resource type performs the same functions as SUNW.HAStorage, and synchronizes actions between HA storage and the data service.

SUNW.HAStoragePlus also has an additional feature to make a local file system highly available. Sun Cluster HA for Sun ONE Directory Server is not disk-intensive and not scalable, and therefore setting up the SUNW.HAStoragePlus resource type is optional.

See the SUNW.HAStoragePlus(5) man page and “Relationship Between Resource Groups and Disk Device Groups” in Sun Cluster 3.1 Data Service Planning and Administration Guide for background information. See “Synchronizing the Startups Between Resource Groups and Disk Device Groups” in Sun Cluster 3.1 Data Service Planning and Administration Guide for the procedure. (If you are using a Sun Cluster 3.0 version prior to 5/02, you must set up SUNW.HAStorage instead of SUNW.HAStoragePlus. See “Synchronizing the Startups Between Resource Groups and Disk Device Groups” in Sun Cluster 3.1 Data Service Planning and Administration Guide for the procedure.)

Configuring Sun Cluster HA for Sun ONE Directory Server Extension Properties

This section describes how to configure the Sun Cluster HA for Sun ONE Directory Server extension properties. Typically, you use the command line scrgadm -x parameter=value to configure extension properties when you create the Sun ONE Directory Server resource. You can also use the procedures that “Administering Data Service Resources” in Sun Cluster 3.1 Data Service Planning and Administration Guide describes to configure them later.

See “Standard Properties” in Sun Cluster 3.1 Data Service Planning and Administration Guide for details on all Sun Cluster properties.

Table 1–2 describes the extension properties that you can configure for Sun ONE Directory Server. The only required extension property for creating a Sun ONE Directory Server resource is the Confdir_list property, which specifies a directory in which the Sun ONE Directory Server configuration files reside. You can update some extension properties dynamically. You can update others, however, only when you create the resource. The Tunable entries indicate when you can update each property.

Sun Cluster HA for Sun ONE Directory Server Fault Monitor

The probe for Sun Cluster HA for Sun ONE Directory Server accesses particular IP addresses and port numbers. The IP addresses are from network resources that the Network_resources_used property lists. The Port_list resource property lists the port(s). See “Standard Properties” in Sun Cluster 3.1 Data Service Planning and Administration Guide for descriptions of these properties.

The fault monitor determines whether the Sun Cluster HA for Sun ONE Directory Server instance is secure or non-secure. The monitor probes secure and non-secure directory servers differently. If you have created a password file, the instance is determined to be secure. If you have not created a password file, the instance is determined to be non-secure. The password file is named keypass and if in a different format than iPlanet's password file. The keypass file contains only the password for which a secure instance of directory server prompts when started manually. This password file is located in the same directory as the start-slapd program used to start this instance of the directory server.

If two ports are specified and you have created a password file, the data service accepts secure requests on one and non-secure requests on the other. However the HA-agent probes both ports as secure.

The probe for a secure instance consists of a TCP connect. If the connect succeeds, the probe is successful. Connect failure or timeout is interpreted as complete failure.

The probe for an insecure instance depends on running the ldapsearch executable that is provided with Sun Cluster HA for Sun ONE Directory Server. The search filter that is used is intended to always find something. The probe detects partial and complete failures. The following conditions are considered as partial failures. All other error conditions are interpreted as complete failures.

• Probe_timeout duration is exceeded while the set of IP addresses is probed for the port. The following list identifies potential causes of this problem.

  • System load.

  • Network-traffic load.

  • Directory-server load.

  • Probe_timeout is set too low for the typical load or the number of directory-server instances (that is, IP address and port combinations) that are being monitored.

• A problem other than timeout occurs while ldapsearch is invoked. Note that this scenario does not apply to the situation where ldapsearch is invoked successfully but returns an error.