This chapter describes the steps to install and configure Sun Cluster HA for Apache on your Sun Cluster servers. You can also use the same steps to install and configure the Sun Cluster HA for Apache Proxy Server.
This chapter contains the following sections.
You can configure Sun Cluster HA for Apache as a failover or a scalable data service. See Chapter 1, Planning for Sun Cluster Data Services, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS and the Sun Cluster Concepts Guide for Solaris OS document for an overview of failover and scalable data services.
Before you install Sun Cluster HA for Apache, update the following information in the Apache configuration file httpd.conf.
The location of the httpd.conf file varies according to installation. System administrators typically install the httpd.conf file on the cluster file system. The default installation places the httpd.conf file in the /usr/local/apache/conf directory. When installing Apache packages bundled with Solaris, the file is located in the /etc/apache directory.
The ServerName directive that contains the hostname – For Sun Cluster HA for Apache to be highly available, you must set this directive to the name of the network address (logical hostname or shared address) that is used to access the server. You should have set up the logical hostname or shared address when you installed the cluster. See the Sun Cluster Concepts Guide for Solaris OS document for details on network resources.
The BindAddress directive, which you must set to the logical host or shared address – You can configure Apache to bind to INADDR_ANY. However, each resource must bind to a unique combination of network resource and port number. For example, if you run multiple resources, you can use INADDR_ANY provided that the port number for each resource is different.
The ServerType directive – This directive must be set to standalone, the default.
Multiple instances of Apache – If you have multiple instances of Apache, you must manage each instance with a separate resource. Furthermore, each separate resource must have a unique Bin_dir setting. Under the specified Bin_dir property that starts the particular instance of Apache, an apachectl script must exist.
Different Apache resources can share the same httpd binary, that is, the apachectl scripts for different resources can specify the path to the same httpd binary. However, you must modify each apachectl script to use a different configuration file for specific Apache resources. To do so, use the -f option of the httpd command to specify a specific httpd.conf file.
The DocumentRoot directive that specifies the location of the documentation root directory – This directive 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 directive is a pointer to a location on the cluster file system, where the cgi-bin files are installed.
You must follow certain conventions when you configure URL mappings for the web server. For example, when setting the CGI directory, locate the CGI directory on the cluster file system to preserve availability. For example, you might map your CGI directory to /global/diskgroup/ServerRoot/cgi-bin, where diskgroup 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 Sun Cluster software controls the “back-end” server. If the server is an RDBMS that the Sun Cluster software supports, use one of the highly available RDBMS packages. Alternatively, you can use the APIs that the Sun Cluster Data Services Developer's Guide for Solaris OS documents to put the server under Sun Cluster control.
The lock file – If you use a lock file, set the value of the LockFile directive in your httpd.conf file to a local file.
The PidFile directive – Point this directive to a local file, as in the following example.
PidFile /usr/local/apache/log/httpd.pid |
While using Apache 2.0 with Sun Cluster HA for Apache, ensure that the directory to which the PidFile directive in the configuration file references exists and proper permissions are assigned. Before you install the Sun Cluster HA for Apache package, verify that the Apache software is properly installed and configured to run on a cluster.
In Apache 1.x, the PidFile directive points to /var/run/httpd.pid, which is created by default when Solaris is installed. But, in Apache 2.0, the PidFile directive has been modified to point to /var/run/apache2/httpd.pid. Since this directory does not exist by default, you are required to create it manually, else the resource will not start.
The Port directive setting that the server port or ports access – The defaults are set in each node's httpd.conf file. The Port_list resource property must include all of the ports that the httpd.conf files specify.
The Port_list property assumes that the web server serves all combinations of ports and IP addresses from the network resources as defined in the Network_resources_used property.
Port_list=”80/tcp,443/tcp,8080/tcp” |
The preceding Port_list configuration, for example, probes the following IP-port combinations.
Host |
Port |
Protocol |
node1 |
80 |
tcp |
node1 |
443 |
tcp |
node1 |
8080 |
tcp |
node2 |
80 |
tcp |
node2 |
443 |
tcp |
node2 |
8080 |
tcp |
However, if node1 serves ports 80 and 443 only and node2 serves ports 80 and 8080 only, you can configure the Port_list property for Apache as follows.
Port_list=node1/80/tcp,node1/443/tcp,node2/80/tcp,node2/8080/tcp |
Consider the following rules.
You must specify hostnames or IP addresses (not network resource names) for node1 and node2.
If Apache serves nodeN/port for every nodeN in the Network_resources_used property, you can use a short form to replace the combination of, for example, node1/port1, node2/port2, and so on. See the following examples.
Example One
Port_list=”80/tcp,node1/443/tcp,node2/8080/tcp” Network_resources_used=node1,node2 |
This example probes the following IP-port combinations.
Host |
Port |
Protocol |
node1 |
80 |
tcp |
node1 |
443 |
tcp |
node2 |
80 |
tcp |
node2 |
8080 |
tcp |
Example Two
Port_list=”node1/80/tcp,node2/80/tcp” Network_resources_used=net-1,net-2 #net-1 contains node1. #net-2 contains node2 and node3. |
This example probes the following IP-port combinations.
Host |
Port |
Protocol |
node1 |
80 |
tcp |
node2 |
80 |
tcp |
All of the hostnames (IP addresses) that the Port_list property specifies 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 another scalable resource already uses an IP address, creation of the Apache resource fails.
The Apache resource can use an already created shared address resource provided they listen to a port or port list that is not being used on that shared address.
Apache Proxy Server – Add the following lines of code to the httpd.conf file if you choose to configure the Apache software as a proxy server.
# Proxy Server Directives. <IfModule mod_proxy.c> ProxyRequests On <Directory proxy:*> Order deny,allow Deny from all Allow from IP_ADDRESS </Directory> ProxyVia On </IfModule> # End of Proxy Server Direcives. |
If you run Sun Cluster HA for Apache 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 points.
Decide whether to run Sun Cluster HA for Apache as a failover or scalable data service.
Decide whether to install a secure or non secure version of the Apache webserver.
Decide which fault monitoring resource properties to set. In most cases, the default values suffice. See Sun Cluster Data Services Planning and Administration Guide for Solaris OS for information about the standard properties and Sun Cluster HA for Apache Extension Properties for information about the 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 hostname (failover services) or shared address (scalable services) that clients use to access the data service. You typically set up this IP address when you install the cluster. See the Sun Cluster Concepts Guide for Solaris OS document for details on network resources.
Provide the path to the application binaries. You can install the binaries on the local disks or on the cluster file system. See Configuration Guidelines for Sun Cluster Data Services in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for a discussion of the advantages and disadvantages of each location.
Modify each copy of apachectl to use the appropriate httpd.conf configuration file.
Exercise caution when you change the Load_balancing_weights property for an online scalable service that has the Load_balancing_policy property set to LB_STICKY or LB_STICKY_WILD. Changing these 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 another cluster member previously serviced the client.
Similarly, when a new instance of the service is started on a cluster, existing client affinities might be reset.
Determine the entry for the Port_list property. The Port_list property can have multiple entries. See How to Register and Configure Sun Cluster HA for Apache by Using Sun Cluster Command Line Interface (CLI) for details.
Determine whether to utilize the Monitor_Uri_List extension property. This extension property enables you to monitor an arbitrary list of URIs. Arbitrary monitoring of URIs is beneficial if you require the Sun Cluster HA for Apache agent probe to monitor any applications (URIs) deployed on the Sun Cluster HA for Apache server. Use of the Monitor_Uri_List extension property is not supported with secure instances of Sun Cluster HA for Apache. You must install release 3.1 10/03 or 3.2 of Sun Cluster HA for Apache to use this property. If you are upgrading Sun Cluster HA for Apache from a previous version, you must perform a resource type upgrade procedure to use the new property. For instructions, see Upgrading a Resource Type in Sun Cluster Data Services Planning and Administration Guide for Solaris OS. See Monitoring Arbitrary URIs for detailed information about using the Monitor_Uri_List extension property.
The table below lists the sections that describe the installation and configuration tasks.
Table 1 Task Map: Installing and Configuring Sun Cluster HA for Apache
Task |
Instructions |
---|---|
Install the Apache software | |
Install the Sun Cluster HA for Apache packages | |
Configure and start Sun Cluster HA for Apache | |
Tune the Sun Cluster HA for Apache fault monitor |
The Apache webserver can be installed and set up as either a non secure or a secure webserver. This section provides procedures for both types of installations. To install a non secure version of the webserver, see one of the following procedures.
How to Install and Configure the Apache Software From the Solaris CD-ROM
How to Install and Configure the Apache Software from the Apache Web Site
To install a secure version of the webserver, see one of the following procedures.
How to Install and Configure the Apache Software Using mod_ssl
How to Install and Configure the Apache Software Using apache-ssl
Sun Cluster HA for Apache works with the Apache software configured as either a web server or a proxy server.
See Apache documentation at http://www.apache.org for standard installation instructions. Contact your Sun sales representative for a complete list of Apache versions that are supported with the Sun Cluster software.
The Sun Cluster HA for Apache can be configured to run in a whole root or a sparse root non-global zone, if required.
This section provides procedures for installing a non-secure Apache webserver. For procedures for installing a secure Apache webserver, see Installing a Secure Apache Webserver.
This procedure installs a non secure version of the Apache webserver. For procedures for installing a secure Apache webserver, see Installing a Secure Apache Webserver.
The Apache binaries are included in three packages—SUNWapchr, SUNWapchu, and SUNWapchd—that form the SUNWCapache package metacluster. You must install the SUNWapchr package before you install the SUNWapchu package.
Place the Web server binaries on the local file system on each of your cluster nodes or on a cluster file system.
If you are using the clsetup utility to configure Sun Cluster HA for Apache, skip Step 2 in this procedure. The clsetup utility automates Step 2.
Run the pkginfo(1) command to determine if the Apache packages SUNWapchr, SUNWapchu, and SUNWapchd have been installed.
If these packages have not been installed, install them as follows.
Starting with Solaris 9, run the following command.
# pkgadd -d Solaris-product-directory SUNWapchr SUNWapchu SUNWapchd |
Starting with Solaris 10, run the following command.
# pkgadd -G -d Solaris-product-directory SUNWapchr SUNWapchu SUNWapchd |
The output from the command is as follows.
... Installing Apache Web Server (root) as SUNWapchr ... [ verifying class initd ] /etc/rc0.d/K16apache linked-pathname /etc/rc1.d/K16apache linked-pathname /etc/rc2.d/K16apache linked-pathname /etc/rc3.d/S50apache linked-pathname /etc/rcS.d/K16apache linked-pathname ... |
Disable the START and STOP run control scripts that were just installed as part of the SUNWapchr package.
This step is necessary because Sun Cluster HA for Apache starts and stops the Apache application after you have configured the data service. Perform the following steps.
List the Apache run control scripts.
Rename the Apache run control scripts.
Verify that all the Apache-related scripts have been renamed.
The following example changes the first letter in the name of the run control script from uppercase to lowercase. However, you can rename the scripts to be consistent with your normal administration practices.
# ls -1 /etc/rc?.d/*apache /etc/rc0.d/K16apache /etc/rc1.d/K16apache /etc/rc2.d/K16apache /etc/rc3.d/S50apache /etc/rcS.d/K16apache # mv /etc/rc0.d/K16apache /etc/rc0.d/k16apache # mv /etc/rc1.d/K16apache /etc/rc1.d/k16apache # mv /etc/rc2.d/K16apache /etc/rc2.d/k16apache # mv /etc/rc3.d/S50apache /etc/rc3.d/s50apache # mv /etc/rcS.d/K16apache /etc/rcS.d/k16apache # ls -1 /etc/rc?.d/*apache /etc/rc0.d/k16apache /etc/rc1.d/k16apache /etc/rc2.d/k16apache /etc/rc3.d/s50apache /etc/rcS.d/k16apache |
This procedure installs a non secure version of the Apache webserver. For procedures for installing a secure Apache webserver, see Installing a Secure Apache Webserver.
Place the web server binaries on the local file system on each of your cluster nodes or on a cluster file system.
On a cluster member, become superuser or assume a role that provides solaris.cluster.admin RBAC authorization.
Install the Apache software using the installation procedures found in the Apache installation documentation.
Install the Apache software using the Apache installation documentation you received with your Apache software or see the installation instructions at http://www.apache.org.
Update the httpd.conf configuration file.
Set the ServerName directive. (In Version 2.0 of Apache, the ServerName directive specifies the hostname and the port.)
Set the BindAddress directive (optional). (The BindAddress directive only exists in versions prior to Apache 2.0. For Apache 2.0, see the following bullet for the Listen directive.)
Set the Listen directive. The Listen directive must use the address of the logical host or shared address. (The Listen directive only exists in Apache 2.0 and beyond. For Apache versions prior to Apache 2.0, see the previous bullet for the BindAddress directive.)
Set the ServerType, ServerRoot, DocumentRoot, ScriptAlias, and LockFile directives.
The ServerType directive does not exist in Apache 2.0.
Set the Port directive to the same number as the Port_list standard resource property. See Step 4 for more information.
Add the following lines of code to the httpd.conf configuration file if you choose to configure the Apache software as a proxy server.
# Proxy Server Directives. <IfModule mod_proxy.c> ProxyRequests On <Directory proxy:*> Order deny,allow Deny from all Allow from IP_ADDRESS </Directory> ProxyVia On </IfModule> # End of Proxy Server Direcives. |
If you configure the Apache software as a proxy server, the CacheRoot setting must point to a location on the cluster file system.
If you are using the clsetup utility to configure Sun Cluster HA for Apache, you do not need to update the BindAddress, ServerRoot, and Port directives. These directives are automatically updated when you run the clsetup utility.
Verify that the port number or numbers in the httpd.conf file 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). Alternatively, while you configure Sun Cluster HA for Apache, you can set the Port_list standard property to match the setting in the httpd.conf file.
Update the paths in the Apache start/stop script file (Bin_dir/apachectl).
You must change the paths from the Apache defaults to match your Apache directory structure. For example, change the line in the BIN_dir/apachectl script beginning with HTTPD=/usr/local/apache/bin/httpd to the following.
HTTPD='/usr/local/apache/bin/httpd -f /global/foo/apache/conf/httpd.conf' |
Perform the following tasks to verify your configuration changes.
Run apachectl configtest to check the Apache httpd.conf file for correct syntax.
If you are using the clsetup utility to configure Sun Cluster HA for Apache, skip this step. This step is automatically executed when you run the clsetup utility.
Ensure that any logical hostnames or shared addresses that Apache uses are configured and online.
Issue apachectl start to start up your Apache server by hand.
If Apache does not start up correctly, correct the problem.
After Apache has started, stop it before moving to the next procedure.
This section provides procedures for installing a secure Apache webserver. For procedures for installing a non-secure Apache webserver, see Installing a Non-Secure Apache Webserver.
This procedure installs a secure version of the Apache webserver. For procedures for installing a non-secure Apache webserver, see Installing a Non-Secure Apache Webserver.
On a cluster member, become superuser or assume a role that provides solaris.cluster.admin RBAC authorization.
Install the Apache software, including mod_ssl.
To install mod_ssl, see the Apache installation documentation or the installation instructions at http://www.modssl.org.
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 Step 4 for more information.
Add the following lines of code to the httpd.conf configuration file if you choose to configure the Apache software as a proxy server.
# Proxy Server Directives. <IfModule mod_proxy.c> ProxyRequests On <Directory proxy:*> Order deny,allow Deny from all Allow from IP_ADDRESS </Directory> ProxyVia On </IfModule> # End of Proxy Server Direcives. |
If you configure the Apache software as a proxy server, the CacheRoot setting must point to a location on the cluster file system.
Verify that the port number or numbers in the httpd.conf file 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). Alternatively, while you configure Sun Cluster HA for Apache, you can set the Port_list standard property to match the setting in the httpd.conf file.
Install all certificates and keys.
In Bin_dir directory, create a file called keypass. Make sure that no one other than the owner has any permissions for this file.
# cd Bin_dir # touch keypass # chmod 700 keypass |
If you are using an encrypted private key or keys, perform the following Step a and Step b.
In the httpd.conf file, look for SSLPassPhraseDialog directive and modify it as follows.
# SSLPassPhraseDialog exec:/Bin_dir/keypass |
See the mod_ssl documentation for details about the SSLPassPhraseDialog directive.
Edit the keypass file so that it prints the pass phrase for the encrypted key corresponding to a host and a port.
This file will be called with server:port algorithm as arguments. Make sure that the file can print the pass phrase for each of your encrypted keys when called with the correct parameters.
Later, when you attempt to start the web server manually, it must not prompt you for a pass phrase. For example, for a secure web server listening on ports 8080 and 8888, with private keys for both encrypted using RSA, the keypass file could be the following.
# !/bin/ksh host=`echo $1 | cut -d: -f1` port=`echo $1 | cut -d: -f2` algorithm=$2 if [ "$host" = "phys-schost-1.example.com" -a "$algorithm" = "RSA" ]; then case "$port" in 8080) echo passphrase-for-8080;; 8888) echo passphrase-for-8888;; esac fi |
The keypass file must not be readable, writable, or executable by anyone other than the owner.
In the httpd.conf file, set the SSLLogLevel to warn to avoid logging a message every time the web server is probed by Sun Cluster HA for Apache.
SSLLogLevel warn |
Update the paths in the Apache start/stop script file (Bin_dir/apachectl).
You must change the paths from the Apache defaults to match your Apache directory structure.
Perform the following tasks to verify your configuration changes.
Run apachectl configtest to check the Apache httpd.conf file for correct syntax.
Ensure that any logical hostnames or shared addresses that Apache uses are configured and online.
Issue apachectl start to start up your Apache server by hand.
Make sure that the web server does not ask you for a passphrase.
If Apache does not start up correctly, correct the problem.
After Apache has started, stop it before moving to the next procedure.
This procedure installs a secure version of the Apache webserver. For procedures for installing a non-secure Apache webserver, see Installing a Non-Secure Apache Webserver.
On a cluster member, become superuser or assume a role that provides solaris.cluster.admin RBAC authorization.
Install the Apache software, including apache-ssl, using the installation procedures found in the Apache installation documentation.
To install apache-ssl, see the Apache installation documentation or the installation instructions at http://www.apache-ssl.org.
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 Step 4 for more information.
Add the following lines of code to the httpd.conf configuration file if you choose to configure the Apache software as a proxy server.
# Proxy Server Directives. <IfModule mod_proxy.c> ProxyRequests On <Directory proxy:*> Order deny,allow Deny from all Allow from IP_ADDRESS </Directory> ProxyVia On </IfModule> # End of Proxy Server Direcives. |
If you configure the Apache software as a proxy server, the CacheRoot setting must point to a location on the cluster file system.
Verify that the port number or numbers in the httpd.conf file 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). Alternatively, while you configure Sun Cluster HA for Apache, you can set the Port_list standard property to match the setting in the httpd.conf file.
Install all certificates and keys.
Make sure that all your private keys are stored unencrypted.
Later, when you attempt to start the web server manually, it must not prompt you for a pass phrase.
Update the paths in the Apache start/stop script file (Bin_dir/httpsdct1).
You must change the paths from the Apache defaults to match your Apache directory structure.
Perform the following tasks to verify your configuration changes.
Run httpsdctl configtest to check the Apache httpd.conf file for correct syntax.
Ensure that any logical hostnames or shared addresses that Apache uses are configured and online.
Issue httpsdctl start to start up your Apache server by hand.
If Apache does not start up correctly, correct the problem.
After Apache has started, stop it before moving to the next procedure.
If you did not install the Sun Cluster HA for Apache during your initial Sun Cluster installation, go to Installing the Sun Cluster HA for Apache Packages. Otherwise, go to Registering and Configuring Sun Cluster HA for Apache.
If you did not install the Sun Cluster HA for Apache packages during your initial Sun Cluster installation, perform this procedure to install the packages. To install the packages, use the Sun Java Enterprise System Common Installer.
You need to install the Sun Cluster HA for Apache packages in the global cluster and not in the zone cluster.
Perform this procedure on each cluster node where you are installing the Sun Cluster HA for Apache packages.
You can run the Sun Java Enterprise System Common Installer 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.
Even if you plan to configure this data service to run in non-global zones, install the packages for this data service in the global zone. The packages are propagated to any existing non-global zones and to any non-global zones that are created after you install the packages.
Ensure that you have the Sun JavaTM Availability Suite DVD-ROM.
If you intend to run the Sun Java Enterprise System Common Installer with a GUI, ensure that your DISPLAY environment variable is set.
On the cluster node where you are installing the data service packages, become superuser.
Load the Sun Java Availability Suite DVD-ROM into the DVD-ROM drive.
If the Volume Management daemon vold(1M) is running and configured to manage DVD-ROM devices, the daemon automatically mounts the DVD-ROM on the /cdrom directory.
Change to the Sun Java Enterprise System Common Installer directory of the DVD-ROM.
Start the Sun Java Enterprise System Common Installer.
# ./installer |
When you are prompted, accept the license agreement.
If any Sun Java Enterprise System components are installed, you are prompted to select whether to upgrade the components or install new software.
From the list of Sun Cluster agents under Availability Services, select the data service for Apache.
If you require support for languages other than English, select the option to install multilingual packages.
English language support is always installed.
When prompted whether to configure the data service now or later, choose Configure Later.
Choose Configure Later to perform the configuration after the installation.
Follow the instructions on the screen to install the data service packages on the node.
The Sun Java Enterprise System Common Installer displays the status of the installation. When the installation is complete, the wizard displays an installation summary and the installation logs.
(GUI only) If you do not want to register the product and receive product updates, deselect the Product Registration option.
The Product Registration option is not available with the CLI. If you are running the Sun Java Enterprise System Common Installer with the CLI, omit this step.
Exit the Sun Java Enterprise System Common Installer.
Unload the Sun Java Availability Suite DVD-ROM from the DVD-ROM drive.
See Registering and Configuring Sun Cluster HA for Apache to register Sun Cluster HA for Apache and to configure the cluster for the data service.
This section describes how to register and configure Sun Cluster HA for Apache.
You can configure Apache as a failover service or as a scalable service, as follows.
When you configure Apache as a failover service, you place the Apache application resources and the network resources in a single resource group.
When you configure Apache 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. The leading text “For scalable services only” in the following procedure identifies these steps. If you are not configuring Apache as a scalable service, skip the steps marked “For scalable services only.”
The sections that follow contain instructions for registering and configuring Sun Cluster HA for Apache resources. For information about the extension properties, see Sun Cluster HA for Apache Extension Properties. The Tunable entry indicates when you can update a property.
See Appendix B, Standard Properties, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for details on all of the Sun Cluster properties.
To set an extension property of a resource, include the following option in the clresource(1CL) command that creates or modifies the resource:
-p property=value |
Identifies the extension property that you are setting.
Specifies the value to which you are setting the extension property.
You can also use the procedures in Chapter 2, Administering Data Service Resources, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS to configure resources after the resources are created.
Set the Monitor_Uri_List extension property if you want the web server fault monitor to probe an arbitrary list of applications (URIs) served by the web server. This extension property provides extended probing functionality and is useful if you are layering services in addition to your web server. The Monitor_Uri_List extension property is not supported with a secure Sun Cluster HA for Apache instance. If you do not set the Monitor_Uri_List extension property, the fault monitor will perform the basic probing. See Tuning the Sun Cluster HA for Apache Fault Monitor for details. The following examples show how to set the Monitor_Uri_List extension property when you add the Sun Cluster HA for Apache instance to your configuration.
(Add an insecure Apache instance with default load balancing.) # clresource create -g resource-group-1 \ -t SUNW.apache -p Bin_dir=/opt/apache/bin -p Network_resources_used=schost-1, ... \ -p Monitor_Uri_list=http://schost-1:8000/servlet/monitor \ -p Scalable=True \ -p Port_list=8000/tcp apache-insecure-1 |
(Add an insecure Apache application resource instance.) # clresource create -g resource-group-1 \ -t SUNW.apache -p Bin_dir=/opt/apache/bin -p Network_resources_used=schost-1 \ -p Monitor_Uri_list=http://schost-1:80/servlet/monitor \ -p Port_list=80/tcp apache-insecure-1 |
Sun Cluster provides the following tools for registering and configuring Sun Cluster HA for Apache:
The clsetup(1CL) utility. For more information, see How to Register and Configure the Sun Cluster HA for Apache by Using clsetup.
Sun Cluster Manager. For more information, see the Sun Cluster Manager online help.
Sun Cluster maintenance commands. For more information, see How to Register and Configure Sun Cluster HA for Apache by Using Sun Cluster Command Line Interface (CLI).
The clsetup utility and Sun Cluster Manager each provide a wizard for configuring Sun Cluster HA for Apache. The wizards reduce the possibility for configuration errors that might result from command syntax errors or omissions. These wizards also ensure that all required resources are created and that all required dependencies between resources are set.
Perform this procedure during your initial setup of Sun Cluster HA for Apache. Perform this procedure from one node only.
The clsetup utility can be used to configure Apache versions 1.x and Apache 2.0.
Before you start the Sun Cluster HA for Apache wizard, ensure that the following prerequisites are met:
You have decided whether to run Sun Cluster HA for Apache as a failover service or a scalable service.
Prerequisites for configuring the required type of network resource are met.
The type of network resource that is required depends on your configuration of Sun Cluster HA for Apache:
A failover service requires a logical hostname resource.
A scalable service requires a shared address resource.
The Apache software is installed and configured.
The Apache configuration files are available on the node where you will start the wizard.
The Sun Cluster HA for Apache packages are installed.
Become superuser on any cluster node.
Start the clsetup utility.
# clsetup |
The clsetup main menu is displayed.
Type the number that corresponds to the option for data services and press Return.
The Data Services menu is displayed.
Type the number that corresponds to the option for configuring Sun Cluster HA for Apache and press Return.
The clsetup utility displays information about Sun Cluster HA for Apache.
Press Return to continue.
The clsetup utility displays a list of configuration modes for Sun Cluster HA for Apache.
Type the number that corresponds to the configuration mode for Sun Cluster HA for Apache and press Return.
The clsetup utility displays a list of available nodes.
Select the nodes where you require Sun Cluster HA for Apache to run.
To accept the default selection of all listed nodes in an arbitrary order, type a and press Return.
To select a subset of the listed nodes, type a comma-separated or space-separated list of the numbers that correspond to the nodes. Then press Return.
Ensure that the nodes are listed in the order in which the nodes are to appear in the resource group's node list. The first node in the list is the primary node of this resource group.
To select all nodes in a particular order, type a comma-separated or space-separated ordered list of the numbers that correspond to the nodes. Then press Return.
Ensure that the nodes are listed in the order in which the nodes are to appear in the resource group's node list. The first node in the list is the primary node of this resource group.
To confirm your selection of nodes, type d and press Return.
The clsetup utility displays a screen where you can specify the location of the Sun Cluster HA for Apache configuration file.
Type the numbers that correspond to the location of the configuration file and press Return.
The configuration file that you select here is used as a template. A new configuration file will be created using this template configuration file.
The clsetup utility displays a screen where you can specify the Sun Cluster HA for Apache document root directory.
Type the numbers that correspond to the location of the document root directory and press Return.
The clsetup utility displays a screen where you can specify the Sun Cluster HA for Apache mount point.
To confirm your selection of the mount point, type d and press Return.
The clsetup utility displays a screen where you can specify the Sun Cluster HA for Apache network resource.
To confirm your selection of the network resource, type d and press Return.
The clsetup utility displays information about the Sun Cluster HA for Apache configuration that the utility will create.
To confirm your selection of the configuration, type d and press Return.
The clsetup utility displays information about the Sun Cluster objects that the utility will create.
The document root specified by you will be copied to the one that is mentioned in the screen. The configuration file specified by you will be edited and the edited file will be stored in the location mentioned in the screen.
To confirm your selection of the Sun Cluster objects, type d and press Return.
The clsetup utility displays information about the Sun Cluster configuration that the utility will create.
To create the configuration, type c and Press Return.
The clsetup utility displays a progress message to indicate that the utility is running commands to create the configuration. When configuration is complete, the clsetup utility displays the commands that the utility ran to create the configuration.
The clsetup utility will rollback the changes if it fails to complete the Apache configuration process.
Press Return to continue.
The clsetup utility returns you to the list of options for configuring Sun Cluster HA for Apache.
(Optional) Type q and press Return repeatedly until you quit the clsetup utility.
If you prefer, you can leave the clsetup utility running while you perform other required tasks before using the utility again. If you choose to quit clsetup, the utility recognizes your Sun Cluster HA for Apache resource group when you restart the utility.
Determine if the Sun Cluster HA for Apache resource group and its resources are online.
Use the clresourcegroup(1CL) utility for this purpose. By default, the clsetup utility assigns the name apache-server-rg to the Sun Cluster HA for Apache resource group.
# clresourcegroup status apache-server-rg |
If the Sun Cluster HA for Apache resource group and its resources are not online, bring them online.
# clresourcegroup online apache-server-rg |
Complete the registration and configuration on any cluster member.
Verify that all the network addresses that you use have been added to your name service database.
You should have performed this verification during your initial Sun Cluster installation. See the planning chapter in the Sun Cluster Software Installation Guide for Solaris OS for details.
To avoid failures because of name service lookup, verify that all the network 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 accessing NIS, NIS+, or DNS.
On a cluster member, become superuser or assume a role that provides solaris.cluster.admin RBAC authorization.
Register the SUNW.apache resource type for the data service.
# clresourcetype register SUNW.apache |
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, the resource group contains both network and failover application resources. For scalable services, the resource group 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 -n option.
# clresourcegroup create [-n node-zone-list] resource-group |
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.
Specifies a comma-separated, ordered list of zones that can master this resource group. The format of each entry in the list is node. In this format, node specifies the node name and zone specifies the name of a non-global Solaris zone. To specify the global zone, or to specify a node without non-global zones, specify only node.
This list is optional. If you omit this list, the global zone of each cluster node can master the resource group.
Add a network resource, such as logical hostname or shared address, to the failover resource group that you created in Step 3.
# clressharedaddress create -g resource-group \ -h hostname,... [-N netiflist] resource |
Specifies a comma-separated list of network resources to add.
Specifies the name of the failover resource group that you created in Step 3.
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 that is specified after the -h option.
Specifies an optional, comma-separated list that identifies the IP Networking Multipathing groups that are on each node or zone. The format of each entry in the list is netif@node. The replaceable items in this format are as follows:
Specifies an IPMP group name, such as sc_ipmp0, or a public network interface card (NIC). If you specify a public NIC, Sun Cluster attempts to create the required IPMP groups.
Specifies the name or ID of a node and, optionally, the name of a non-global Solaris zone. To specify the global zone, or to specify a node without non-global zones, specify only node.
If you require a fully qualified hostname, you must specify the fully qualified name with the -h option and you cannot use the fully qualified form in the resource name.
Sun Cluster does not currently support using the adapter name for netif.
For scalable services only – Create a scalable resource group to run on all of the desired cluster nodes.
If you run Sun Cluster HA for Apache as a failover data service, proceed to Step 7.
Create a resource group to hold a data service application resource. You must specify the maximum and desired number of primary nodes.
If only a subset of nodes can be primaries for this resource group, you must use the -n option to specify the names of these potential primaries when you create the resource group.
You must also specify any dependency between this resource group and the failover resource group that you created in Step 3. This dependency ensures that when failover occurs, 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 the network resource.
# clresourcegroup create [-n node-zone-list] \ -p Maximum_primaries=m -p Desired_primaries=n \ -p RG_dependencies=resource-group resource-group |
Specifies the name of the scalable service resource group to add.
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.
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.
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 that you created in Step 3.
Specifies a comma-separated, ordered list of zones that can master this resource group. The format of each entry in the list is node. In this format, node specifies the node name and zone specifies the name of a non-global Solaris zone. To specify the global zone, or to specify a node without non-global zones, specify only node.
This list is optional. If you omit this list, the global zone of each cluster node can master the resource group.
For scalable services only – Create an application resource in the scalable resource group.
If you run Sun Cluster HA for Apache as a failover data service, proceed to Step 7.
# clresource create -g resource-group \ -t resource-type -p Bin_dir=bin-directory,... \ -p Network_resources_used=network-resource,… \ -p Port_list=port-number/protocol[, …] \ -p Scalable=True resource |
Specifies your choice for the name of the resource to add.
Specifies the name of the scalable resource group into which the resources are to be placed.
Specifies the type of the resource to add.
Specifies a comma-separated list of network resource names that identify the shared addresses that the data service uses.
Specifies a comma-separated list of port numbers and protocol to be used, for example, 80/tcp,81/tcp.
Specifies a required parameter for scalable services. This parameter must be set to True.
Specifies the location where the Apache binaries—in particular, apachectl—are installed. Sun Cluster HA for Apache requires this extension property.
The resource is created in the enabled state.
Optionally, you can set additional extension properties that belong to the Apache data service to override their default values. See Sun Cluster HA for Apache Extension Properties for a list of extension properties.
For failover services only – Create an application resource in the failover resource group.
Perform this step only if you run Sun Cluster HA for Apache as a failover data service. If you run Sun Cluster HA for Apache as a scalable data service, you should have performed Step 5 and Step 6 and should now proceed to Step 9.
# clresource create -g resource-group \ -t resource-type -p Bin_dir=bin-directory \ -p Network_resources_used=network-resource,… \ -p Port_list=port-number/protocol[, …] resource |
Specifies your choice for the name of the resource to add.
Specifies the name of the resource group into which the resources are to be placed, created in Step 3.
Specifies the type of the resource to add.
Specifies a comma-separated list of network resources that identify the shared addresses that the data service uses.
Specifies a comma-separated list of port numbers and protocol to be used, for example, 80/tcp,81/tcp.
This property is required for scalable services only. Here the value is set to False or can be omitted.
Specifies the location where the Apache binaries—in particular, apachectl—are installed. Sun Cluster HA for Apache requires this extension property.
The resource is created in the enabled state.
Bring the failover resource group online.
# clresourcegroup online resource-group |
Specifies the name of the failover resource group.
For scalable services only – Bring the scalable resource group online.
# clresourcegroup online resource-group |
Specifies the name of the scalable resource group.
For scalable services, you create the following resource groups.
A failover resource group that contains the network resources
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: resource-group-1 (for shared addresses), resource-group-2 (for scalable Apache application resources) Resources: schost-1 (shared address), apache-1 (Apache application resource) (Add a failover resource group to contain shared addresses.) # clresourcegroup create resource-group-1 (Add the shared address resource to the failover resource group.) # clressharedaddress create -g resource-group-1 -h schost-1 (Register the Apache resource type.) # clresourcetype register SUNW.apache (Add a scalable resource group.) # clresourcegroup create -p Maximum_primaries=2 \ -p Desired_primaries=2 -p RG_dependencies=resource-group-1 resource-group-2 (Add Apache application resources to the scalable resource group.) # clresource create -g resource-group-2 \ -t SUNW.apache -p Bin_dir=/opt/apache/bin -p Network_resources_used=schost-1 \ -p Scalable=True \ -p Port_list=80/tcp apache-1 (Bring the failover resource group online.) # clresourcegroup online resource-group-1 (Bring the scalable resource group online on both nodes.) # clresourcegroup online resource-group-2 |
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: resource-group-1 (for all of the resources) Resources: schost-1 (logical hostname), apache-1 (Apache application resource) (Add a failover resource group to contain all of the resources.) # clresourcegroup create resource-group-1 (Add the logical hostname resource to the failover resource group.) # clreslogicalhostname create -g resource-group-1 -h schost-1 (Register the Apache resource type.) # clresourcetype register SUNW.apache (Add Apache application resources to the failover resource group.) # clresource create -g resource-group-1 \ -t SUNW.apache -p Bin_dir=/opt/apache/bin -p Network_resources_used=schost-1 \ -p Port_list=80/tcp apache-1 (Bring the failover resource group online.) # clresourcegroup online resource-group-1 |
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.
See the SUNW.HAStoragePlus(5) man page and Relationship Between Resource Groups and Device Groups in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for background information. See Synchronizing the Startups Between Resource Groups and Device Groups in Sun Cluster Data Services Planning and Administration Guide for Solaris OS 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 Device Groups in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for the procedure.)
After you configure Sun Cluster HA for Apache, verify that you can open a web page with the network resources (logical hostnames or shared addresses) and port number from a web browser. Perform a switchover with the clresourcegroup(1CL) command to verify that the service continues to run on a secondary node and can be switched back to the original primary.
The Sun Cluster HA for Apache fault monitor is contained in a resource whose resource type is SUNW.apache.
System properties and extension properties of the resource control the behavior of the fault monitor. The default values of these properties determine the preset behavior of the fault monitor. The preset behavior should be suitable for most Sun Cluster installations. Therefore, you should tune the Sun Cluster HA for Apache fault monitor only if you need to modify this preset behavior.
Tuning the Sun Cluster HA for Apache fault monitor involves the following tasks:
Setting the interval between fault monitor probes
Setting the timeout for fault monitor probes
Defining the criteria for persistent faults
Specifying the failover behavior of a resource
Information about the Sun Cluster HA for Apache fault monitor that you need to perform these tasks is provided in the subsections that follow.
Tune the Sun Cluster HA for Apache fault monitor when you register and configure Sun Cluster HA for Apache. For more information, see Registering and Configuring Sun Cluster HA for Apache.
For detailed information, see “Tuning Fault Monitors for Sun Cluster Data Services” in Sun Cluster Data Services Planning and Administration Guide for Solaris OS.
The Sun Cluster HA for Apache probe sends a request to the server to query the health of the Apache server.
Before querying the Apache server, the probe checks to confirm that network resources are configured for this Apache resource. If no network resources are configured, an error message (No network resources found for resource) is logged, and the probe exits with failure.
For a nonsecure web server, the probe connects to the Apache server and performs an HTTP 1.0 HEAD check by sending the HTTP request and receiving a response. In turn, the probe connects to the Apache server on each IP address/port combination.
The result of this query can be either a failure or a success. If the probe successfully receives a reply from the Apache server, the probe returns to its infinite loop and continues the next cycle of probing and sleeping.
The query can fail for various reasons, such as heavy network traffic, heavy system load, and misconfiguration. Misconfiguration can occur if you did not configure the Apache server to listen on all of the IP address/port combinations that are being probed. The Apache server should service every port for every IP address that is specified for this resource.
The following probe failures are considered as complete failures.
Failure to connect to the server, as the following error message flags, with %s indicating the hostname and %d the port number.
Failed to connect to %s port %d %s |
Running out of time (exceeding the resource property timeout Probe_timeout) after trying to connect to the server.
Failure to successfully send the probe string to the server, as the following error message flags, with the first %s indicating the hostname, %d the port number, and the second %s indicating further details about the error.
Failed to communicate with server %s port %d: %s |
When the monitor accumulates two partial failures within the resource property interval Retry_interval, it counts them as one complete failure.
The following probe failures are considered as partial failures:
Running out of time (exceeding the resource property timeout Probe_timeout) while trying to read the reply from the server to the probe's query.
Failing to read data from the server for other reasons, as the following error message flags, with the first %s indicating the hostname and %d the port number. The second %s indicates further details about the error.
Failed to communicate with server %s port %d: %s |
If you have configured URIs in the Monitor_Uri_List extension property, then the probe connects to the Sun Cluster HA for Apache server and performs an HTTP 1.1 GET check by sending a HTTP request and receiving a response to each of the URIs in Monitor_Uri_List. If the HTTP server return code is 500 (Internal Server Error) or if the connect fails, the probe will take action.
The Monitor_Uri_List extension property supports HTTP requests only. It does not support HTTPS requests.
The result of the HTTP requests is either failure or success. If all of the requests successfully receive a reply from the Sun Cluster HA for Apache server, the probe returns and continues the next cycle of probing and sleeping.
Heavy network traffic, heavy system load, and misconfiguration can cause the HTTP GET probe to fail. Misconfiguration of the Monitor_Uri_List property can cause a failure if a URI in the Monitor_Uri_List includes an incorrect port or hostname. For example, if the web server instance is listening on logical host schost-1 and the URI was specified as http://schost-2/servlet/monitor, the probe will try to contact schost-2 to request /servlet/monitor.
For a secure web server, the probe connects to each IP address and port combination. If this connection attempt succeeds, the probe disconnects and returns with a success status. No further checks are performed.
Based on the history of failures, a failure can cause either a local restart or a failover of the data service. For detailed information, see “Tuning Fault Monitors for Sun Cluster Data Services” in Sun Cluster Data Services Planning and Administration Guide for Solaris OS.
Upgrade the SUNW.apache resource type if the following conditions apply:
You are upgrading from an earlier version of the Sun Cluster HA for Apache data service.
You need to use the new features of this data service.
For general instructions that explain how to upgrade a resource type, see Upgrading a Resource Type in Sun Cluster Data Services Planning and Administration Guide for Solaris OS. The information that you require to complete the upgrade of the SUNW.apache resource type is provided in the subsections that follow.
The relationship between a resource type version and the release of Sun Cluster data services is shown in the following table. The release of Sun Cluster data services indicates the release in which the version of the resource type was introduced.
Resource Type Version |
Sun Cluster Data Services Release |
---|---|
1 |
1.0 |
3.1 |
3.1 5/03 |
4 |
3.1 10/03 |
4.1 |
3.2 |
To determine the version of the resource type that is registered, use the clresourcetype showcommand.
The resource type registration (RTR) file for this resource type is /opt/SUNWscapc/etc/SUNW.apache.
The information that you require to edit each instance of the SUNW.apache resource type is as follows:
You can perform the migration at any time.
If you need to use the new features of the Sun Cluster HA for Apache data service, the required value of the Type_version property is 4.
If you need to monitor deployed applications, set the Monitor_Uri_List extension property to a single URI or a list of URIs to specify the locations of the applications that are to be probed.
The following example shows a command for modifying an instance of the SUNW.apache resource type.
# clresource set -p Monitor_Uri_List=http://schost-1/test.html \ -p Type_version=4 apache-rs |
This command modifies the SUNW.apache resource named apache-rs as follows:
The Type_version property of this resource is set to 4.
The Fault Monitor probe will monitor the URI http://schost-1/test.html.