Chapter 5 Installing and Configuring Sun Cluster HA for Apache

This chapter describes the steps for installing and configuring Sun Cluster HA for Apache on your Sun Cluster servers.

This chapter contains the following procedures:

• "How to Install and Configure the Apache Application Software"

• "How to Install Sun Cluster HA for Apache Packages"

• "How to Register and Configure Sun Cluster HA for Apache"

• "How to Configure SUNW.HAStorage Resource Type"

• "How to Verify Data Service Installation and Configuration"

• "How to Configure Sun Cluster HA for Apache Extension Properties"

You can configure Sun Cluster HA for Apache as either a failover service or a scalable service. For an overview of failover and scalable data services, see Chapter 1, Planning for Sun Cluster Data Services and the Sun Cluster 3.0 Concepts document.

Planning the Installation and Configuration

Prior to installation of Sun Cluster HA for Apache, update the following information in the Apache configuration file, httpd.conf:

• The ServerName directive that contains the host name. For Sun Cluster HA for Apache to be highly available, you must set this directive to the name of the network address (logical host name or shared address) that is used to access the server. The logical host name or shared address should have been set up when the cluster was installed; if not, refer to the Sun Cluster 3.0 Installation Guide for information on how to set up logical host names and shared addresses and set one up now.

• The BindAddress directive, which you must set to the logical host or shared address. Since you can configure Apache to bind to INADDR_ANY, if you plan on running multiple instances of the Apache data service or multiple data services on the same node, each instance must bind to a unique network resource and port number.

• The ServerType directive, which must be set to standalone, the default.

• The ServerRoot directive that specifies the top of the directory tree under which the server's conf and log subdirectories are typically located. This directive has no default.

  If you use a cluster file system as the location for the server root, you need only install the Apache software on that single file system to make it accessible to all the nodes that can run the data service. See the discussion on placement of the binary files in "Determining the Location of the Application Binaries".

  You might have multiple instances that use a single Apache binary. The location of the configuration file is specified according to the Confdir_list resource property. For example:

  (Location of the Apache binaries - also the value of the Bin_dir property) /global/apache/bin (Location of configuration directories - Confdir_list property) /global/websites/dev/conf /global/websites/sqa/conf (Location of httpd.conf files) /global/websites/dev/conf/httpd.conf /global/websites/sqa/conf/httpd.conf

  To start up the instances by hand, as you might if you are verifying your setup, use the following commands. Also, when instructed by the Resource Group Manager (RGM), the data service in effect issues the following commands to start up the instances:

  # /global/apache/bin/httpd \ -f /global/websites/dev/conf/httpd.conf # /global/apache/bin/httpd \ -f /global/websites/sqa/conf/httpd.conf

• The DocumentRoot directive that specifies the location of the documentation root directory. This is a pointer to a location on the cluster file system, where the HTML documents are installed.

• The ScriptAlias directive that contains the location on a cluster file system of the cgi-bin directory, This is a pointer to a location on the cluster file system, where the cgi-bin files are installed.

  ---

  Note -

  You must follow certain conventions when you configure URL mappings for the Web server. For example, when setting the CGI directory, preserve availability by locating the CGI directory on the cluster file system. For example, you might map your CGI directory to /global/disk-device-group/ServerRoot/cgi-bin, where disk-device-group is the disk device group that contains the Apache software. In situations where the CGI programs access "back-end" servers, such as an RDBMS, ensure that the "back-end" server is also controlled by Sun Cluster. If the server is an RDBMS supported by Sun Cluster, use one of the highly available RDBMS packages. Alternatively, you can put the server under Sun Cluster control by using the APIs documented in the Sun Cluster 3.0 Data Services Developers' Guide.

  ---

• If you are using a lock file, set the value of the LockFile directive in your httpd.conf file to a local file.

• Use a PidFile directive to point to a local file. For example:

  PidFile /usr/local/apache/log/httpd.pid

• The Port directive setting accessed by the server port or ports. The defaults are set in each node's httpd.conf file. The Port_list resource property must include all the ports specified in the httpd.conf files.

  Port_list assumes that the Web server serves all combinations of ports and IP addresses from the network resources as defined in Network_resources_used. For example:

  Port_list="80/tcp,443/tcp,8080/tcp"

  probes the following IP-port combinations:

  Host	Port	Protocol
  host-1	80	tcp
  host-1	443	tcp
  host-2	8080	tcp
  host-2	80	tcp
  host-2	443	tcp
  host-2	8080	tcp

  However, if host-1 serves 80 and 443 only and host-2 serves ports 80 and 8080 only, you can configure Port_list for Apache as follows:

  Port_list=host-1/80/tcp,host-1/443/tcp,host-2/80/tcp,host-2/8080/tcp

  Bear in mind the following rules:

  • You must specify host names or IP addresses (not network resource names) for host-1 and host-2.

  • If Apache serves host-n/port for every host-n in Network_resources_used, you can use a short form to replace the combination of host-1/port-1, host-2/port-2, and so on. See the following examples.

    Example One:

    Port_list="80/tcp,host-1/443/tcp,host-2/8080/tcp" Network_resources_used=host-1,host-2

    probes the following IP-port combinations:

    Host	Port	Protocol
    host-1	80	tcp
    host-1	443	tcp
    host-2	80	tcp
    host-2	8080	tcp

    Example Two:

    Port_list="host-1/80/tcp,host-2/80/tcp" Network_resources_used=net-1,net-2 #net-1 contains host-1. #net-2 contains host-2 and host-3.

    probes the following IP-port combinations:

    Host	Port	Protocol
    host-1	80	tcp
    host-2	80	tcp

  • All host names (IP addresses) that are specified in Port_list must not belong to a network resource that is specified in any other scalable resource's Network_resources_used property. Otherwise, as soon as a scalable service detects that an IP address is already in use by another scalable resource, creation of the Apache resource fails.

If you are running the Sun Cluster HA for Apache data service and another HTTP server, configure the HTTP servers to listen on different ports. Otherwise, a port conflict can occur between the two servers.

To register and configure Sun Cluster HA for Apache, you must consider or provide information on the following:

• Decide whether to run Sun Cluster HA for Apache as a failover or a scalable service.

• Decide which fault monitoring resource properties (such as Thorough_probe_interval or Probe_timeout) to set. In most cases, the default values suffice. For information on these properties, refer to "Configuring Sun Cluster HA for Apache Extension Properties".

• Provide the name of the resource type for Sun Cluster HA for Apache. This name is SUNW.apache.

• Provide the names of the cluster nodes that will master the data service.

• Provide the logical host name (failover services) or shared address (scalable services) to be used by clients to access the data service. This IP address is normally set up when the cluster is installed. For details on how to set up network addresses, see the Sun Cluster 3.0 Installation Guide.

• Provide the path to the application binaries. You can install the binaries on the local disks or on the cluster file system. For a discussion of the advantages and disadvantages of each location, see "Determining the Location of the Application Binaries".

• Provide the path to the conf directory.

• Exercise caution when changing Load_balancing_weights for an online scalable service that has Load_balancing_policy set to LB_STICKY or LB_STICKY_WILD. Changing those properties while the service is online can cause existing client affinities to be reset, hence a different node might service a subsequent client request even if the client had been previously serviced by another node in the cluster.

  Similarly, when a new instance of the service is started on a cluster, existing client affinities might be reset.

  ---

  Note -

  If a scalable proxy is serving a scalable Web resource with the LB_STICKY policy, you must also set up an LB_STICKY policy for the proxy.

  ---

• Determine the entries for the Confdir_list and Port_list properties. For failover services, Confdir_list can have only one entry; Port_list can have multiple entries. For scalable services, both properties can have multiple entries. For details, see "How to Register and Configure Sun Cluster HA for Apache".

Installing and Configuring Sun Cluster HA for Apache

Table 5-1 lists the sections that describe the installation and configuration tasks.

Installing and Configuring Apache

This section describes the steps for installing the Apache server and enable it to run as the Sun Cluster HA for Apache data service.

Sun Cluster HA for Apache works with Apache configured as either a Web server or a proxy server.

For standard installation instructions, refer to Apache documentation at http://www.apache.org. For a list of Apache releases supported for use with Sun Cluster, see the Sun Cluster 3.0 Release Notes.

How to Install and Configure the Apache Application Software

1. Become superuser on a node in the cluster.

2. Install Apache by using the steps described in Apache documentation.

   Refer to the documentation you received with your Apache software or to the Apache Web site: http://www.apache.org.

3. Update the httpd.conf configuration file.

   • Set the ServerName directive.

   • Set the BindAddress directive (optional).

   • Set the ServerType, ServerRoot, DocumentRoot, ScriptAlias, and LockFile directives.

   • Set the Port directive to the same number as the Port_list standard resource property. See the next step for more information.

   • Make changes to run as a proxy server if you choose to run Apache as a proxy server. See the Apache documentation. If you will be running Apache as a proxy server, the CacheRoot setting must point to a location on the cluster file system.

4. Verify that the port number or numbers in httpd.conf match those of the Port_list standard resource property.

   You can edit the httpd.conf configuration file to change its port number or numbers to match the standard Sun Cluster resource property default (port 80); or, while configuring Sun Cluster HA for Apache, you can set the Port_list standard property to match the setting in httpd.conf.

5. (Optional) If you will be using the Apache start/stop script Bin_dir/apachectl, update the paths in the script file.

   You must change the paths from the Apache defaults to match your Apache directory structure.

6. Verify your configuration changes.

   Check the Apache httpd.conf file for correct syntax by running apachectl configtest.

   Ensure that any logical host names or shared addresses in use by Apache are configured and online.

   Start up your Apache server by hand by issuing apachectl start. If Apache does not start up correctly, correct the problem.

   After Apache has started, stop it before moving to the next procedure.

Where to Go from Here

If the data service packages for Apache have not been installed from the Sun Cluster data service CD, go to "Installing Sun Cluster HA for Apache Packages". Otherwise, go to "Registering and Configuring Sun Cluster HA for Apache".

Installing Sun Cluster HA for Apache Packages

The scinstall(1M) utility installs SUNWscapc, the Sun Cluster HA for Apache data service package, on a cluster. You can install specific data service packages from the Sun Cluster data service CD with interactive scinstall, or you can install all data service packages on the CD with the -s option to noninteractive scinstall. The preferred method is to use interactive scinstall, as described in the following procedure.

The data service packages might have been installed as part of your initial Sun Cluster installation. If not, use the following procedure to install them now.

How to Install Sun Cluster HA for Apache Packages

You need the Sun Cluster data service CD to complete this procedure. Run this procedure on all cluster members that can master Sun Cluster HA for Apache.

1. Load the data service CD into the CD-ROM drive.

2. Run scinstall with no options.

   This step starts scinstall in interactive mode.

3. Select the menu option: "Add support for new data service to this cluster node."

   You can then load software for any data services that exist on the CD.

4. Exit scinstall and unload the CD from the drive.

Where to Go from Here

See "How to Register and Configure Sun Cluster HA for Apache" to register Sun Cluster HA for Apache and configure the cluster for the data service.

Registering and Configuring Sun Cluster HA for Apache

To register and configure Sun Cluster HA for Apache, you can use the Cluster Module of Sun Management Center or the following command-line procedure.

Apache can be configured as a failover service or as a scalable service, as follows:

• When Apache is configured as a failover service, you place the Apache application resources and the network resources in a single resource group.

• When Apache is configured as a scalable service, you create a scalable resource group for the Apache application resources and a failover resource group for the network resources.

The scalable resource group depends on the failover resource group. Additional steps are required to configure Apache as a scalable service. These steps are identified by the leading text "Scalable services only:" in the following procedure. If you are not configuring Apache as a scalable service, skip those steps.

How to Register and Configure Sun Cluster HA for Apache

Run this procedure on any cluster member.

1. Become superuser on a node in the cluster.

2. Register the resource type for the data service.

   # scrgadm -a -t SUNW.apache

   -a

   Adds the data service resource type.

   -t SUNW.apache

   Specifies the predefined resource type name for your data service.

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

   This resource group is required for both failover and scalable services. For failover services, it contains both network and failover application resources. For scalable services, it contains network resources only. A dependency is created between this group and the resource group that contains the application resources.

   Optionally, you can select the set of nodes on which the data service can run with the -h option.

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

   -a

   Adds a new configuration.

   -g fo-resource-group-name

   Specifies the name of the failover resource group to add. This name can be your choice but must be unique for the resource groups within the cluster.

   -h nodelist

   An optional comma-separated list of physical node names or IDs that identify potential masters. The order specified here determines the order in which the nodes are considered as primary during failover.

   ---

   Note -

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

   ---

4. Verify that all network addresses that you are using have been added to your name service database.

   This verification should have been done as part of the Sun Cluster installation. For details, see the planning chapter in the Sun Cluster 3.0 Installation Guide.

   ---

   Note -

   To avoid failures because of name service lookup, verify that all network addresses are present in the /etc/hosts file on all cluster nodes. Configure name service mapping in /etc/nsswitch.conf on the servers to first check the local files prior to accessing NIS, NIS+, or DNS.

   ---

5. Add a network resource (logical host name or shared address) to the failover resource group created in Step 3.

   # scrgadm -a {-S | -L} -g fo-resource-group-name \ -l hostname, ... [-j resource-name] \ [-X auxnodelist=nodeid, ...] [-n network-interface-id-list]

   -S | -L

   -S specifies shared address resources; -L specifies logical host name resources.

   -l hostname, ...

   Specifies a comma-separated list of network resources to add. You can use the -j option to specify a name for the resources. If you do not do so, the network resources have the name of the first entry on the list.

   -g fo-resource-group-name

   Specifies the name of the failover resource group created in Step 3.

   -j resource-name

   Specifies a resource name. If you do not supply your choice for a resource name, the name of the network resource defaults to the first name specified after the -l option.

   -X auxnodelist=nodeid, ...

   Specifies a comma-separated list of physical node IDs that identify cluster nodes that can host the shared address but never serve as primary in the case of failover. These nodes are mutually exclusive with the nodes identified in nodelist for the resource group, if specified.

   -n network-interface-id-list

   Specifies an optional comma-separated list that identifies the NAFO groups on each node. All nodes in nodelist of the resource group must be represented in network-interface-list. If you do not specify this option, scrgadm attempts to discover a net adapter on the subnet identified by the hostname list for each node in nodelist.

6. Scalable services only: Create a scalable resource group to run on all desired nodes of the cluster.

   If you are running Sun Cluster HA for Apache as a failover data service, skip to Step 8.

   Create a resource group to hold a data service application resource. You must specify the maximum and desired number of primary nodes as well as a dependency between this resource group and the failover resource group you created in Step 3. This dependency ensures that in the event of failover, if the two resource groups are being brought online on the same node, the Resource Group Manager (RGM) starts up the network resource before any data services that depend on it.

   # scrgadm -a -g ss-resource-group-name \ -y Maximum_primaries=m -y Desired_primaries=n \ -y RG_dependencies=resource-group-name

   -g ss-resource-group-name

   Specifies the name of the scalable service resource group to add.

   -y Maximum_primaries=m

   Specifies the maximum number of active primary nodes allowed for this resource group. If you do not assign a value to this property, the default is 1.

   -y Desired_primaries=n

   Specifies the desired number of active primary nodes allowed for this resource group. If you do not assign a value to this property, the default is 1.

   -y RG_dependencies= resource-group-name

   Identifies the resource group that contains the shared address resource on which the resource group being created depends, that is, the name of the failover resource group created in Step 3.

7. Scalable services only: Create an application resource in the scalable resource group.

   If you are running Sun Cluster HA for Apache as a failover data service, skip to Step 8.

   # scrgadm -a -j resource-name -g ss-resource-group-name \ -t resource-type-name -y Network_resources_used=network-resource, ... \ -y Port_list=port-number/protocol[, ...] -y Scalable=True \ -x Confdir_list=config-directory -x Bin_dir=bin-directory

   -j resource-name

   Specifies your choice for the name of the resource to add.

   -g ss-resource-group-name

   Specifies the name of the scalable resource group into which the resources are to be placed.

   -t resource-type-name

   Specifies the type of the resource to add.

   -y Network_resources_used= network-resource, ...

   Specifies a comma-separated list of network resource names that identify the shared addresses used by the data service.

   -y Port_list=port-number/protocol, ...

   Specifies a comma-separated list of port numbers and protocol to be used, for example, 80/tcp,81/tcp.

   -y Scalable=

   Specifies a required parameter for scalable services. Must be set to True.

   -x Confdir_list=config-directory, ...

   Specifies a comma-separated list of the locations of the Apache configuration files. This is a required extension property.

   -x Bin_dir=bin-directory

   Specifies the location where the Apache binaries are installed. This is a required extension property.

   ---

   Note -

   Optionally, you can set additional extension properties that belong to the Apache data service to override the default value. See Table 5-2 for a list of extension properties.

   ---

8. Failover services only: Create an application resource in the failover resource group.

   Perform this step only if you are running Sun Cluster HA for Apache as a failover data service. If you are running Sun Cluster HA for Apache as a scalable service, you should have performed Step 6 and Step 7 and should now go to Step 10.

   # scrgadm -a -j resource-name -g resource-group-name \ -t resource-type-name -y Network_resources_used=network-resource, ... \ -y Port_list=port-number/protocol[, ...] -y Scalable=False \ -x Confdir_list=config-directory -x Bin_dir=bin-directory

   -j resource-name

   Specifies your choice for the name of the resource to add.

   -g resource-group-name

   Specifies the name of the resource group into which the resources are to be placed, created in Step 3.

   -t resource-type-name

   Specifies the type of the resource to add.

   -y Network_resources_used= network-resource, ...

   Specifies a comma-separated list of network resources that identify the shared addresses used by the data service.

   -y Port_list=port-number/protocol, ...

   Specifies a comma-separated list of port numbers and protocol to be used, for example, 80/tcp,81/tcp.

   -y Scalable=

   This property is required for scalable services only. Here it is set to False or can be omitted.

   -x Confdir_list=config-directory

   Specifies the location of the Apache configuration file. This is a required extension property and must have exactly one entry only.

   -x Bin_dir=bin-directory

   Specifies the location where the Apache binaries are installed. This is a required extension property.

9. Bring the failover resource group online.

   # scswitch -Z -g fo-resource-group-name

   -Z

   Enables the shared address resource and fault monitoring, switches the resource group into a managed state, and brings it online.

   -g fo-resource-group-name

   Specifies the name of the failover resource group.

10. Scalable services only: Bring the scalable resource group online.

    # scswitch -Z -g ss-resource-group-name

    -Z

    Enables the resource and monitor, moves the resource group to the managed state, and brings it online.

    -g ss-resource-group-name

    Specifies the name of the scalable resource group.

Example-Registering Scalable Sun Cluster HA for Apache

For scalable services, you create two resource groups: a failover resource group that contains the network resources and a scalable resource group that contains the application resources. The following example shows how to register a scalable Apache service on a two-node cluster.

Cluster Information
Node names: phys-schost-1, phys-schost-2
Shared address: schost-1
Resource groups: sa-schost-1 (for shared addresses), 	ap-schost-1 (for scalable Apache application resources)
Resources: schost-1 (shared address),	apache-1 (Apache application resource) 
 
(Add a failover resource group to contain shared addresses.)
# scrgadm -a -g sa-schost-1
 
(Add the shared address resource to the failover resource group.)
# scrgadm -a -S -g sa-schost-1 -l schost-1 
 
(Register the Apache resource type.)
# scrgadm -a -t SUNW.apache
 
(Add a scalable resource group.)
# scrgadm -a -g ap-schost-1 -y Maximum_primaries=2 \
-y Desired_primaries=2 -y RG_dependencies=sa-schost-1
 
(Add Apache application resources to the scalable resource group.)
# scrgadm -a -j apache-1 -g ap-schost-1 \
-t SUNW.apache -y Network_resources_used=schost-1 \
-y Scalable=True -y Port_list=80/tcp \
-x Bin_dir=/opt/apache/bin -x Confdir_list=/opt/apache/conf
 
(Bring the failover resource group online.)
# scswitch -Z -g sa-schost-1
 
(Bring the scalable resource group online on both nodes.)
# scswitch -Z -g ap-schost-1

Example-Registering Failover Sun Cluster HA for Apache

The following example shows how to register a failover Apache service on a two- node cluster.

Cluster Information
Node names: phys-schost-1, phys-schost-2
Logical hostname: schost-1
Resource group: lh-schost-1 (for all resources)
Resources: schost-1 (logical hostname),	apache-1 (Apache application resource)
 
(Add a failover resource group to contain all resources.)
# scrgadm -a -g lh-schost-1
 
(Add the logical host name resource to the failover resource group.)
# scrgadm -a -L -g lh-schost-1 -l schost-1 
 
(Register the Apache resource type.)
# scrgadm -a -t SUNW.apache
 
(Add Apache application resources to the failover resource group.)
# scrgadm -a -j apache-1 -g lh-schost-1 \
-t SUNW.apache -y Network_resources_used=schost-1 \
-y Scalable=False -y Port_list=80/tcp \
-x Bin_dir=/opt/apache/bin -x Confdir_list=/opt/apache/conf
 
(Bring the failover resource group online.)
# scswitch -Z -g lh-schost-1

Where to Go from Here

Verify the installation by using the information in the section "How to Verify Data Service Installation and Configuration". To set or modify resource extension properties, see "Configuring Sun Cluster HA for Apache Extension Properties".

How to Configure SUNW.HAStorage Resource Type

The SUNW.HAStorage resource type synchronizes actions between HA storage and data service. Because Sun Cluster HA for Apache is scalable, we strongly recommend that you set up SUNW.HAStorage.

For details on the background, see the SUNW.HAStorage(5) man page and "Relationship Between Resource Groups and Disk Device Groups". For the procedure, see "How to Set Up SUNW.HAStorage Resource Type for New Resources".

How to Verify Data Service Installation and Configuration

After you have configured Sun Cluster HA for Apache, verify that you can open a Web page with the network resources (logical host names or shared addresses) and port number from a Web browser. Perform a switchover with the scswitch(1M) command to verify that the service continues to run on a secondary node and can be switched back to the original primary.

Configuring Sun Cluster HA for Apache Extension Properties

The only required extension properties for creating an Apache server resource are Confdir_list and Bin_dir. Confdir_list specifies a directory that contains a subdirectory named conf, in which the Apache configuration properties (httpd.conf) reside.

For details on all Sun Cluster properties, see Appendix A, Standard Properties.

How to Configure Sun Cluster HA for Apache Extension Properties

Typically, you configure these properties by using the Cluster Module of Sun Management Center or the command-line scrgadm -x parameter=value at the time you create the Apache server resource. You can also configure them later by following the procedures described in Chapter 9, Administering Data Service Resources.

Some extension properties can be updated dynamically, others only when the resource is created. Table 5-2 describes extension properties your can configure for the Apache server. The Tunable column indicates when the property can be updated.