Administering UNIX-based Clusters

The ClusterCATS Explorer was originally created for the Windows platform. Consequently, administrators in a UNIX environment either must obtain a Windows machine (NT, 98, or 95) to run the Windows-based ClusterCATS Explorer, or they can install and use the cross-platform Web-based Explorer together with ClusterCATS server utilities.

This section addresses the following topics:

Using the ClusterCATS Web Explorer

ColdFusion Enterprise includes the ClusterCATS Web Explorer. It allows administrators in UNIX-only environments to use a graphical, cross-platform, Web-based utility to create, configure, and administer ClusterCATS clusters. You can only install the Web Explorer on UNIX servers.

Note The Web Explorer, like its Windows counterpart, is quite robust and lets you configure and administer clusters easily. However, it does not contain the identical functionality provided by the Windows-based ClusterCATS Explorer. The Web Explorer does not let you do the following:

This section explains how to perform the following tasks using the ClusterCATS Web Explorer:

Configuring the communications port on your Web server

Before you can open and use the ClusterCATS Web Explorer, you must ensure that a communications port is configured to listen for HTTP requests on the Netscape or Apache Web server on which you installed ClusterCATS. You can only access the ClusterCATS Web Explorer through the defined communications port on your Web server. You configure this user-defined port using the Netscape Enterprise Server Administrator -- not the ColdFusion Administrator.

By default, Netscape Enterprise Server will assign your Web server a random, six-digit communication port number. You can either use this assigned number or change it to something easier to remember, like port 81.

If you are not familiar with configuring your Web server's communications ports, see the Netscape Enterprise Server Administrator online Help for instructions.

Opening the Web Explorer

  1. Open a browser.
  2. Enter the following URL in the browser's address field and press Enter:
    http://hostname:12345/admin-serv/btweb/index.html
    

    where hostname is the name of the Web server on which you installed ClusterCATS and :12345 is the communication port number that the Web server has been configured to listen for HTTP requests.

    The Enter Network Password dialog box appears.

  3. Enter your user name and password in the appropriate fields and click OK.
    Note The default user name and password is admin.

    The ClusterCATS Web Explorer opens.

Creating clusters

  1. From within the open Web Explorer, click the Create New Cluster link.

    The Create New Cluster page appears.

  2. Enter a unique name for the cluster in the Cluster Name field.
    Tip Make your cluster names logically consistent with their purpose. For example, Sales Web, Customer Support Web, and so on.

  3. Enter the fully qualified host name (for example, doc.allaire.com) in the Web Server Name field for the first server you want to be a member of this cluster.
    Note You cannot create an empty cluster; you must specify a Web server that will be part of the cluster.

  4. Enter GoColdFusion in the License Key field and click OK.

    The cluster is created and appears in the Cluster Member List page.

Adding cluster members

  1. Open the ClusterCATS Web Explorer if it's not already opened.
  2. Click the Add Server link.

    The Add Server page appears.

  3. Enter the fully qualified host name (for example, doc.allaire.com) in the Web Server Name field.
  4. Click OK to add the cluster member to the existing cluster.

Deleting cluster members

  1. Open the ClusterCATS Web Explorer if it's not already open.
  2. Click the Delete Server link.

    The Delete Server page appears.

  3. Select the cluster member you want to delete from the Web Server Name drop-down box and click OK.

    A message appears telling you that the selected server has been deleted.

    Note If you delete the last cluster member in a cluster, the cluster is also deleted and you are returned to the default page of the ClusterCATS Web Explorer. If you want to delete a cluster, you must delete all of its members.

Configuring server load thresholds

For each cluster member, you configure a Peak load threshold and a Gradual Redirection threshold. The Peak load threshold represents the maximum load the server can handle before its performance degrades significantly or becomes unavailable. The Gradual Redirection threshold represents the point at which HTTP requests will begin to be redirected to other less loaded members in a cluster so that the server's performance does not degrade or become unavailable.

By default the Peak load threshold is 90% and the Gradual Redirection threshold is 70%. If you want to modify the threshold settings for one or more of your cluster members, perform the following procedures.

Note To configure Peak and Gradual Redirection thresholds:
  1. Open the ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of the server for which you want to configure load thresholds in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Server Attributes link.

    The Connect to Server page appears.

  5. Select the server you want to connect to from the Web Server Name drop-down box and click OK.

    The selected server's Properties page appears.

  6. Click the Administration link under Server Attributes.

    The Server Administration page appears for the selected server.

  7. Enter new values in the Standard and Gradual Load Threshold fields and click OK.

    If you want the server to be able to handle as much load as possible, set both threshold values close to one another. However, if you want redirection to occur well in advance of the server nearing its Peak threshold, set the values farther apart. To achieve the desired effect described in the latter scenario, it's best to set a differential of at least 10% between the two threshold values.

Configuring the ColdFusion probe

ClusterCATS load balances and provides failover support for your ColdFusion applications in two ways. First, it automatically interprets and reacts to the load metric that the ColdFusion Server generates. Second, ClusterCATS lets you create ColdFusion application probes that periodically test the health and operation of the sites that the ColdFusion Server processes.

The probe is a high availability feature that verifies that the ColdFusion Server is running properly on your clustered servers. It periodically tests a specific ColdFusion URL over periodic intervals and verifies its validity against a user-defined string that is contained in the returned page.

If the validation test succeeds, inbound HTTP requests will continue to be sent to the server for which a probe exists. However, if the test fails (the URL fails, times out, or does not return the user-specified string in the page accessed), ClusterCATS restricts the server and redirects requests to other available servers in the cluster. The restricted server will become available as soon as the probe returns a valid value.

Additionally, if the ColdFusion Server ever hangs or fails, ClusterCATS automatically attempts to recover the failed service. Once the ColdFusion service is recovered, the probe will automatically restart the ColdFusion Server and send HTTP traffic to the server.

Note To configure the ColdFusion probe:
  1. Open the ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of the server for which you want to configure the ColdFusion probe in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Server Attributes link.

    The Connect to Server page appears.

  5. Select the server you want to connect to from the Web Server Name drop-down box and click OK.

    The selected server's Properties page appears.

  6. Click the ColdFusion Probe link.

    The ColdFusion Application Probe page appears.

  7. Leave the Web Server, Pathname, and Working Directory fields as they are unless you installed ColdFusion to a directory other than the default installation directory.
  8. In the Startup Parameters field, enter the actual URL of the site you want the probe to access (cabernet.allaireqa.com in the screen above) followed by a text string that appears on a page within the site you are probing (cfprobe.cfm in the screen above).
  9. Also in the Startup Parameter field, do not modify the RESTART explicit parameter if you want the probe to automatically restart the ColdFusion Server on detecting a failure. However, remove it if you do not want ClusterCATS to be able to automatically restart the ColdFusion Server upon detecting a failure.
  10. If you want longer intervals for how often the probe checks the ColdFusion Server and for how much time can pass without a response from the ColdFusion Server before a failure is registered, change the Timeout and Frequency values to longer durations.
    Note Don't set the Timeout and Frequency interval values too low (below 60 seconds) because if the intervals are extremely narrow, they may cause the ColdFusion Server to reboot inadvertently (due to network congestion, for example) rather than detecting an actual failure on the ColdFusion Server. Allaire recommends you set your Timeout and Frequency intervals to 120 seconds.

  11. Click Register to create the probe.

Configuring session-aware load balancing

Sometimes referred to as a "sticky" session, session-aware load balancing guarantees that users won't get bumped from the server on which they started their session until the session is complete, regardless of the load thresholds that have been defined for the affected server.

Note Session-aware load balancing may not work if you've used absolute hyperlinks in an applicati. Absolute hyperlinks route the HTTP request back to the cluster entry point and redirect requests according to the current load threshold without regard to the state of the requesting client. To avoid this inadvertent loss of state, be sure to use only relative linking in your applicati.

Note To configure session-aware load balancing:
  1. Open ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of the server for which you want to configure session-aware load balancing in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Administration link under Cluster Attributes.

    The Cluster Administration page appears.

  5. Enable the Session-Aware Load Balancing check box and click OK.

    Session-aware load balancing is now enabled for the selected cluster.

Integrating ClusterCATS with a load balancing product

You can configure ClusterCATS to work in conjunction with a third-party hardware load balancing device or load balancing software product to provide more comprehensive load balancing and failover support for your server clusters.

Note You cannot integrate ClusterCATS with Cisco LocalDirector using the Web Explorer. This capability is only available in the Windows-based ClusterCATS Explorer.

Note To integrate your clusters with a load balancing product:
  1. Open ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of the server you want to integrate with another load balancing product in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Administration link under Cluster Attributes.

    The Cluster Administration page appears.

  5. In the Load Balancing Product field, enter the URL of the Web site for which the load balancing product has been set up to manage HTTP traffic.
  6. Click OK.

    ClusterCATS and the load balancing device will now work together to manage HTTP requests being sent to your servers.

Configuring alarm notifications

The ClusterCATS alarm notification feature provides you with instant feedback about critical events that take place within a cluster. Once the event triggers the alarm, you are notified by e-mail.

Note To configure administrator alarm notifications:
  1. Open ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of a server for which you want to configure administrator alarm notifications in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Alarm Notification link.

    The Alarm Notification page appears.

  5. Enter the e-mail address of the person you want to be notified about the occurrence of an event in that event's corresponding field.

    If you want multiple people to receive e-mail notification about the same event, separate each e-mail address with a comma.

  6. Enter the name of the default SMTP mail server to which your mail is delivered in the Default SMTP Host field and click OK.

    The e-mail addresses you specified will now receive e-mail notification if the corresponding events occur.

Configuring administration e-mail support

The ClusterCATS e-mail support functionality makes it possible for you to receive vital statistics about your cluster using designated e-mail accounts in your organization. There are two types of administration e-mail support that you can set up: Report e-mail and Support e-mail.

Report e-mail lets you know each day how your server clusters are functioning. It reports on the following information:

Support e-mail sends an automatic e-mail nightly to Allaire's Technical Support team that contains basic configuration information about your cluster. This information enables Allaire to provide optimal support by understanding your environment when you call a Technical Support representative. Support e-mail can contain the following information:

Note To configure administrator Report and Support e-mail:
  1. Open ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of a server for which you want to configure administrator e-mail support in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Support link.

    The Cluster Support page appears.

  5. Enter in the Support E-mail field the e-mail address of the person at your organization that should receive a copy of the e-mail that is sent nightly to Allaire's Technical Support.

    If more than one person should receive the e-mail, separate the e-mail addresses with commas.

  6. Enter in the Report e-mail field the e-mail address of the person at your organization that should receive daily reports about your clusters.

    Again, if more than one person should receive the e-mail, separate the e-mail addresses with commas.

  7. Enter the name of the mail server through which mail is delivered in the SMTP Gateway field and click OK.

    The ClusterCATS Report and Support e-mail options are enabled.

Configuring administrator authentication

Using the Web Explorer, you can configure two administration security modes, one of which keeps unauthorized users from accessing a cluster and its content. When authentication is enabled for a specific cluster, only authorized users will be able to access and administer that cluster using their ClusterCATS Web Explorer.

If you are going to use the Local User Authentication mode, you must first create user accounts on each server in the cluster for the individuals you want to be able to administer the cluster members using the ClusterCATS Web Explorer.

Note To configure authentication modes for your clusters:
  1. Open ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of the server for which you want to configure administrator authentication in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Authentication link.

    The Cluster Authentication page appears.

  5. Select either Disabled or Local User from the Authentication drop-down box.
    Note Disabled authentication mode is the default setting. It provides no security challenge and allows anyone to access the server using the Web Explorer. Local User authentication lets users who have accounts on the servers access and administer those servers using the Web Explorer.

  6. If using Local User authentication, enter a valid user name and password and click OK.

    ClusterCATS requires you to enter a valid user name and password after selecting the type of authentication you are using so that you don't inadvertently lock yourself out of the cluster.

Changing cluster members' state

All cluster members are added to a cluster in Active state by default. In Active state, ClusterCATS provides availability and failover services to your Web resources. From time to time, you may want to turn off these load balancing and failover services to help you troubleshoot problems or when you need to add additional servers to the cluster. To do this, you can change the cluster's state from Active to Passive. In the Passive state, clusters do not actively manage load nor protect against resource failures. Any HTTP requests sent or directed to a server that is in the Passive state are passed directly to that server without any ClusterCATS processing.

After you have added and configured all members that will be in the cluster, you need to change each server's state from Passive to Active.

Note To change a cluster member's state from Active to Passive:
  1. Open ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of the server that you want to activate in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Server Attributes link under Other.

    The Connect to Server page appears.

  5. Select the server you want to connect to from the Web Server Name drop-down box and click OK.

    The selected server's Properties page appears.

  6. Click the Administration link.

    The Server Administration page appears for the selected server.

  7. Select Active or Passive from the State drop-down box and click OK.

    If you selected Passive, the ClusterCATS load balancing and failover capabilities are now disabled for the selected server. If you selected Active, ClusterCATS will now actively monitor and load balance HTTP requests across the cluster.

Restricting cluster members

ClusterCATS lets you restrict a cluster member from receiving any HTTP requests by enabling a configuration option. You may want to do this for a variety of reasons, including server maintenance, server software updates, and as a load management method.

Note To restrict an active cluster member from receiving HTTP requests:
  1. Open ClusterCATS Web Explorer if it's not already open.
  2. Click the Show Cluster link.

    The Show Cluster page appears.

  3. Enter the fully qualified host name of a server that you want to restrict in the Web Server Name field and click OK.

    The Cluster Member List page appears.

  4. Click the Server Attributes link under Other.

    The Connect to Server page appears.

  5. Select the server you want to connect to from the Web Server Name drop-down box and click OK.

    The selected server's Properties page appears.

  6. Click the Administration link.

    The Server Administration page appears for the selected server.

  7. Select Restricted from the Restriction Status drop-down box and click OK.

    The selected server will no longer participate in the cluster and will not receive HTTP requests until you change its status back to Unrestricted.

Using the ClusterCATS server utilities

ColdFusion Enterprise ships with the following server utilities for configuring, administering, and troubleshooting your ClusterCATS clusters:

These server utilities work on both Windows and UNIX platforms.

btadmin utility

You can use the btadmin utility to:

Start and stop daemons

Use the following command-line syntax for starting and stopping daemons:

btadmin [start/stop/restart daemon] 
    [configure option]

You can start and stop the following daemons with btadmin:

Starting and Stopping daemons with btadmin
Daemon Description
appmgr Application manager daemon
failover Failover daemon
ns-httpd HTTP daemon

Following are examples of how you start and stop daemon processes with the btadmin utility:

btadmin start appmgr
btadmin stop failover
btadmin restart ns-httpd

Configure ClusterCATS options

Use the following command-line syntax for configuring ClusterCATS options:

btadmin [configure option]

You can configure the following ClusterCATS options using the btadmin utility:

Configuring Bright Tiger options with btadmin
Option Description
btcats Bright Tiger ClusterCATS server
failover Server failover (ipaliasd)
load Load Balancing preference
nsroot Configure new Netscape Server root directory (used when Netscape Server is moved).

The following example shows you how to configure a ClusterCATS option using the btadmin utility:

btadmin configure btcats

Enable and disable options

Use the following command-line syntax for enabling and disabling ClusterCATS options:

btadmin [enable/disable option]

You can enable or disable the following ClusterCATS options with btadmin:

Enabling and Disabling options with btadmin
Option Description
btcats Bright Tiger ClusterCATS server
failover Server failover (ipaliasd)
ns-httpd HTTP daemon

Below are examples of how you enable and disable ClusterCATS options with the btadmin utility:

btadmin enable btcats
btadmin disable failover

Show and reset clusters

You can display the ClusterCATS configuration settings currently enabled using the btadmin utility. For example:

btadmin show

You can also reinitialize your cluster configuration settings on the current server using the btadmin utility:

btadmin reset

Display btadmin online help

To get help about the btadmin utility's features, use the following command-line syntax:

btadmin help

bt-start and bt-stop utilities

The bt-start-server and bt-stop-server utilities start and stop a Netscape Enterprise or Apache Web server.

Use the following syntax to start and stop a Netscape or Apache Web server:

bt-start-server
bt-stop-server [-f]
Note Use the -f option to stop the Web server without being prompted for confirmation.

btcfgchk utility

The btcfgchk utility is a network management tool that displays information about your IP and DNS configurations. Use it to analyze and troubleshoot your servers and network.

To run the btcfgchk utility, enter the following command-line syntax:

/<bt-installdir>/program/btcfgchk

The following sample output shows how btcfgchk displays configuration information for a system with one network adapter and two IP addresses:

btcfgchk FQHN is hartford.brighttiger.com 
El90x1 [PRIMARY]:

hartford.brighttiger.com        192.168.0.31
255.255.255.0
hartford.brighttiger.com

hartford1.brighttiger.com       192.168.0.32
255.255.255.0
hartford1.brighttiger.com

btcfgchk DNS error reporting

The btcfgchk utility reports on DNS configuration problems. ClusterCATS requires that your DNS be configured with correct forward and reverse mappings. A forward mapping translates the host name to an IP address. Conversely, a reverse mapping translates an IP address to its host name. ClusterCATS expects the mapping to be one-to-one (one host name to one IP Address).

btcfgchk DNS error reporting 
Error Explanation
Host name does not map to a single IP address The main host name for this system is not mapping to one IP address. Possible problems are:
  • The main host name of the system could not be resolved to any IP address. Your fully qualified host name is the combination of the host name and the domain name. Make sure no typos appear in these names in your DNS definitions, both on the DNS server and on each cluster member's DNS definition. To verify that the host name is correct, enter the following command at a command-line prompt:
nslookup <fully qualified hostname>
  • The host name is a round-robin DNS name. Run the ClusterCATS hostinfo utility to see if more than one IP address is configured for the domain.
No adapter associated with host name found btcfgchk is unable to find the primary network adapter. The primary network adapter should be the network adapter containing the IP address of the main host name.
Duplicate Primary Adapter btcfgchk found two network adapters with the same IP address. Use the ifconfig -a command to see information about your adapter.
Name lookup for <hostname> failed btcfgchk was not able to determine the IP address for the specified host. Your DNS server may be down. Use nslookup to see if it can contact your DNS server.
<IP address 1> reverse maps to <hostname> which then forward maps to <IP address 2> btcfgchk did a lookup on <IP address 1> and found a host name to which it is mapped. It then attempted to verify that this host name maps back to the IP address specified, and the verification failed. There is likely an issue with your DNS configuration. Use the ClusterCATS hostinfo utility to gather more information on how the names and IP address are configured.
hostinfo <IP address 1>
hostinfo <hostname returned from initial hostinfo>
Error looking up <hostname> by name ClusterCATS could not resolve the given host name to an IP address. Use nslookup to look up the host name in DNS.
Host name a round-robin name, or does not map to configured IP address The host name maps to more than one IP address (round-robin DNS) or maps to an IP address not found on this machine. Use the ClusterCATS hostinfo utility to check the host name DNS configuration:
hostinfo <hostname>

If you see more than one IP address listed, then round-robin DNS is being used. If you see one IP address, check to see if that address is configured on this machine. You can use the ipconfig/all command to view all IP addresses on this machine.
Host name not found in any reverse mapping Probable forward mapping misconfiguration for <hostname> For each IP address found on the system, an attempt was made to find the corresponding host name. None of the IP addresses on the system reverse mapped to the system's main fully qualified host name. The problem is either:
  • The host name maps to the wrong IP address.
  • The IP address that the host name maps to does not have an entry in the DNS table for the reverse map. Consequently, nslookup does not return the hostname.
Probable round robin configuration for <hostname> The host name does not map to a single IP address. Use the hostinfo tool to determine to which IP address it maps.

hostinfo utility

The hostinfo utility is a network management tool that displays information about a specified domain name. Use it to analyze and troubleshoot problems you are having with DNS mappings to a particular domain.

To run the hostinfo utility, enter the following command-line syntax:

#cd <btinstall-dir>/program/

Set the default directory to the Programs Directory under Bright Tiger.

#<btinstall-dir>/program> hostinfo domain_name 

The following sample output from the hostinfo utility provides information about a set of round-robin DNS host names.

##<btinstall-dir>/program> hostinfo www.brighttiger.com
Information for host 'www.brighttiger.com':

FQHN: www.brighttiger.com
Primary Address: 0.0.0.0
Domain: .brighttiger.com
Aliases: btWeb1.brighttiger.com 
    btWeb2.brighttiger.com
    www.brighttiger.com 
Addresses: 444.87.27.76 444.87.27.77

The hostinfo utility displays the domain name, the primary IP address, and any IP aliases. If the primary IP address is set to 0.0.0.0, the domain is using round-robin DNS. The round robin names will appear under the Alias section of the DNS table and the round-robin addresses appear under the Addresses section.

sniff utility

The sniff utility is a network management tool that displays the packets that a specific Network Interface Card (NIC) is hearing.

To run the sniff utility, enter the following command-line syntax:

#/<btinstall-dir>/program/sniff

Below is sample output from the sniff utility:

Mail Test Environment Variables:
   BTMailHost,     BTSender,       BTRecipients,   BTSubject,    BTText
 Packet Test Environment Variables:
   BTPort,         BTMcastTTL,     BTUcastCount,   BTBcastCount, 
BTMcastCount
   BTSendInterval, BTDoLocalBind,  BTUcastAddress, BTBcastAddress
   BTMcastAddress, BTLocalAddress, BTSendSize,     BTRecvSize
   BTConsole,      BTLogFile,      BTSystem

 Press keys at run-time:
  d - dump sniff configuration information
  H - display this and more help
  h - display this help
  l - run load balance test thread
  m - run mail test thread
  p - toggle packet dump display
  q, <ESC>, <ENTER> - quit all active threads and exit
  r - run UDP listener thread
  s - run packet test thread
  x - execute system command

Use the "r" command within sniff to listen to intra-cluster packets:
Listen Thread thread running on 'any' interface...

[ SrvHello    @ Tue Jun 30 17:01:57 1998] 192.168.0.213
boston1.brighttiger.com          (192.168.0.118  ) (255.255.255.0  )
sales_automation   Mcast V1.2    Available   2/90
[[ SrvHello    @ Tue Jun 30 17:01:57 1998] 192.168.0.213
somewhere.brighttiger.com        (192.168.0.213  ) (255.255.255.0  )