Back | Next | Contents Cams Administrator's Guide

Policy Server Clustering Quick Start

This document provides the basic information required to configure a Cams policy server for use in a cluster. The instructions that follow focus on adding a new Cams policy server to an existing cluster. For general information on Cams policy server clustering and more detailed information on deployment options, see the following documents:

The instructions that follow assume that you'll be setting up a cluster containing two Cams policy servers. Deploying more than two Cams policy servers is easily achieved by simple extension of these instructions.

Prerequisites

Before attempting to configure Cams policy server clustering, you should:

  1. Obtain a Cams server license file (cams-license-keys.xml) from Cafésoft support for each policy server in your cluster. Cafésoft can also provide a single license file for use with all Cams policy servers in your cluster.
  2. Configure two computer systems with separate static IP addresses. For purposes of documentation, we'll use the hostnames and IP addresses: Orville=192.168.1.101, Wilbur=192.168.1.102. These computer systems may use any operating system supported by the Cams policy server.
  3. Configure each computer system to access a shared file system where master Cams policy server files will be installed and edited. NOTE: This should be done in such a way that the Cams policy server running on each computer system will not depend on full-time access to the shared file system (e.g., for loading centrally-managed configuration files or writing log files). This eliminates the shared file system as a single point of failure.
  4. Install and configure the Cams policy server on each computer system in your cluster as described in Installation and Integration Quick Start.

Step 1 - Create master Cams cluster files

Copy the entire Cams installation directory tree from one of the installed Cams policy servers to the shared file system where master files will be maintained. You'll need to do this only once!

Step 2 - Register each Cams policy server

On the master file system, create a Cams policy server registration file for each host: Orville and Wilbur. This will require creation of files with names containing the static IP address for each policy server host:

  1. For Orville: CAMS_HOME/conf/cams-reg-192.168.1.101.conf
  2. For Wilbur: CAMS_HOME/conf/cams-reg-192.168.1.102.conf

Examples 1 and 2 show the contents for each of these files.

NOTE: Be sure to use the host name and IP addresses appropriate for your environment and to use the same case-sensitive server name and cluster name in all locations!

#
#--- Cams Policy Server Registration for host: Orville
#
cams.server.name=Orville cams.cluster.name=MyCamsCluster

Example 1 - Cams Policy Server Registration File for CAMS_HOME/conf/cams-reg-192.168.1.101.conf

#
#--- Cams Policy Server Registration for host: Wilbur
#
cams.server.name=Wilbur cams.cluster.name=MyCamsCluster

Example 2 - Cams Policy Server Registration File for CAMS_HOME/conf/cams-reg-192.168.1.102.conf

NOTE: Cams provides a default registration file CAMS_HOME/conf/cams-reg-default.conf. If a Cams policy server is started and cannot find its IP address-specific registration file, the default registration file will be used. This enables a single Cams policy server to run in a default cluster without the need to configure other cluster-specific parameters. Rather than continuing to use this file for one of the servers in your Cams policy server cluster, we recommend that you create an IP address-specific file for each Cams policy server.

Step 3 - Create the cluster directory structure

Each configured Cams policy server cluster may have its own directory hierarchy to store per-cluster and per-server configuration files. Creation of a cluster-specific directory structure enables clear management of cluster-wide and server-specific license files and/or configuration files. Using operating system-specific commands or a file browser graphical user interface, create the Cams policy server directory structure represented by directory paths shown in Example 3.

CAMS_HOME/MyCamsCluster
CAMS_HOME/MyCamsCluster/conf
CAMS_HOME/MyCamsCluster/Orville
CAMS_HOME/MyCamsCluster/Orville/conf
CAMS_HOME/MyCamsCluster/Wilbur
CAMS_HOME/MyCamsCluster/Wilbur/conf

Example 3 - Example Cams Policy Server Cluster Directory Structure

Step 4 - Install cams-license-keys.xml files

If you have a distinct cams-license-keys.xml file for each Cams policy server (e.g., license keys that are IP address specific), copy the appropriate file to the server-specific config directories as shown in Example 4.

CAMS_HOME/MyCamsCluster/Orville/conf/cams-license-keys.xml
CAMS_HOME/MyCamsCluster/Wilbur/conf/cams-license-keys.xml

Example 4 - Example Server-specific cams-license-keys.xml Installation Paths

If you have a single cams-license-keys.xml file, copy it to the cluster-specific config directory as shown in Example 5.

CAMS_HOME/MyCamsCluster/conf/cams-license-keys.xml

Example 5 - Example Cluster-wide cams-license-keys.xml Installation Path

Alternatively, you can install a multi-server cams-license-keys.xml file to the global config directory as shown in Example 6.

CAMS_HOME/conf/cams-license-keys.xml

Example 6- The global cams-license-keys.xml Installation Path

When a Cams policy server is started, the license file is sought in the directory hierarchy from most specific to most general. For example, the following license file paths will be searched for host Orville:

  1. Per-server config directory: CAMS_HOME/MyCamsCluster/Orville/conf/cams-license-keys.xml
  2. Per-cluster config directory: CAMS_HOME/MyCamsCluster/conf/cams-license-keys.xml
  3. Global config directory: CAMS_HOME/conf/cams-license-keys.xml

NOTE: Only the first license file found is loaded, so it must be valid for the IP address the server.

Step 5 - Copy master files to Cams policy servers

Now that you've populated and edited all master configuration files, you'll need to copy the entire Cams master directory tree to the local file system on each Cams policy server host. This will ensure that all Cams policy servers in the same cluster use the same Java classes, security domains, access control policies, login configurations, and server configuration settings.

Once you've synchronized the Cams directory trees on each Cams policy server host, you may find it useful to create command scripts that automate copying of key configuration directories from the master file system to per-server local file systems. Example 7 shows an example Windows NT/2000/2003 batch script that can be executed on hosts Orville and Wilbur to copy important master configuration files (from master disk "m:").

rem
rem Copy Master Cams Configuration Files to Local File System
rem
xcopy m:\cams\conf .
xcopy m:\cams\MyCamsCluster .

Example 7 - A Windows Batch Script (copyMaster.bat) for Copying Master Cams Config Files to Local System

Example 8 shows an example Unix shell script that can be executed on hosts Orville and Wilbur to copy important master configuration files (from remote file system: /usr/export/master) to the local Cams installation directory.

#!/bin/sh
#
# Copy Master Cams Configuration Files to Local File System
#
cp -r /usr/export/master/cams/conf .
cp -r /usr/export/master/cams/MyCamsCluster .

Example 8 - A Unix Shell Script (copyMaster.sh) for Copying Master Cams Config Files to Local System

Step 6 - Configure Cams web agents

For each Cams web agent, configure the Cams cluster name and per-server connection parameters. Example 9 shows the important cluster settings for a Cams webagent configuration file. All other agent configuration settings should remain the same as configured for a single Cams policy server environment. Important considerations when configuring Cams web agents include:

  • The Cams cluster name and Cams server names must appear exactly as configured in master Cams policy server files.
  • If your agent communicates with Cams policy servers through a firewall, you may need to enable a Network Address Translations (NAT) or another form of network routing to each Cams policy server IP address.
  • During initial setup, enable Cams cluster debugging by setting cams.cluster.debug=true. Once proper Cams cluster operation is confirmed, disable debugging by setting cams.cluster.debug=false.
...
#
# Configure the Cams Cluster Name associated with this agent
#
cams.cluster.name=MyCamsCluster


#
# Enable/disable Cams Cluster debugging
#
cams.cluster.debug=true


#
# Configure all Cams Policy Server URLs
#
cams.server.url.Orville=cams://192.168.1.101:9191

cams.server.url.Wilbur=cams://192.168.1.102:9191


...

Example 9 - Sample cams-webagent.conf Cluster Configuration Settings

Step 7 - Start Cams policy servers

Each Cams policy server must be started on the computer system on which it is intended to run. During Cams cluster deployment, we recommend that you start Cams policy servers from a command line to more easily debug possible configuration errors. After Cams cluster configuration is debugged, you can start each Cams policy server as an operating system-level service.

Starting a clustered Cams policy server is done the same way that stand-alone servers are started. Login to one of the Cams policy server computer systems (Orville) and issue the appropriate command:

Linux/UNIX:

$CAMS_HOME/bin/runcams.sh

Windows:

%CAMS_HOME%\bin\runcams.bat

Some INFO-level messages displayed on the console will report important configuration settings as shown in Example 10.

[INFO ] Initializing Cams Policy Server version: 2.0
[INFO ] IP Address: 192.168.1.101
[INFO ] Using registration file: c:\cams\conf\cams-reg-192.168.1.101.conf
[INFO ] Using cams.server.name=Orville
[INFO ] Using cams.cluster.name=MyCamsCluster
[INFO ] Using cams.home=..
[INFO ] Using cams.cluster.home=../MyCamsCluster
[INFO ] Using cams.server.home=../MyCamsCluster/MyCamsServer
[INFO ] Loading global config file: c:\cams\conf\cams.conf
[INFO ] Skipping cluster config file: c:\cams\MyCamsCluster\conf\cams.conf (Does not exist)
[INFO ] Skipping server config file: c:\cams\MyCamsCluster\MyCamsServer\conf\cams.conf (Does not exist) [INFO ] Cams Policy Server ready on port: 9191 [INFO ] Listening for Shutdown connections on port: 9292

Example 10 - Example INFO level messages when Cams policy server Orville is started

Step 8 - Start the Cams web agent

Start the Cams web agent by starting the associated web or application server as you normally would. The Cams web agent will report its connection parameters in cams-webagent.log as shown in Example 11.

...
[14 Oct 2003 08:57:20,424] [StandardConnection...] [INFO ] Connection established to 192.168.1.101:9191
[14 Oct 2003 08:57:20,524] [StandardConnection...] [INFO ] Connection established to 192.168.1.101:9191
[14 Oct 2003 08:57:20,634] [StandardConnection...] [INFO ] Connection established to 192.168.1.101:9191
[14 Oct 2003 08:57:20,705] [StandardConnection...] [INFO ] Connection established to 192.168.1.101:9191 [14 Oct 2003 08:57:20,724] [StandardConnection...] [INFO ] Connection established to 192.168.1.102:9191
[14 Oct 2003 08:57:20,824] [StandardConnection...] [INFO ] Connection established to 192.168.1.102:9191
[14 Oct 2003 08:57:20,934] [StandardConnection...] [INFO ] Connection established to 192.168.1.102:9191
[14 Oct 2003 08:57:20,998] [StandardConnection...] [INFO ] Connection established to 192.168.1.102:9191 ...

Example 11 - INFO reported by Cams Agent after connecting to clustered Cams policy servers (abbreviated)

NOTE: Some Cams web agents (like the IIS, Tomcat 4.X, ServletFilter webagents) are configured to proactively connect with the configured Cams server(s). Other web agents (like Apache 1.3 and Apache 2.0) use a lazy connection scheme because these web servers can create many child processes to handle HTTP requests, some of which are never used. To confirm Cams policy server connectivity when using Cams web agents with a lazy connection scheme, use a web browser to request a resource from the web server. This will force creation of one or more attempted connections between the Cams agent and the configured Cams policy server(s).

Step 9 - Confirm proper Cams cluster operation

Perhaps the easiest way to confirm proper operation of your clustered Cams environment is by monitoring the Cams webagent log file when cams.cluster.debug=true. This will cause the Cams web agent to report the Cams policy server to which a request is being delegated and will also report a failed or unavailable Cams policy server if the agent would otherwise attempt to use that server.

NOTE: The IP addresses should appear as configured in cams-webagent.conf, but if connections cross a network boundary via a router or firewall, they will not match Cams policy server IP addressses.

To confirm proper Cams agent detection of an unavailable Cams policy server, shutdown one of the servers. Example 12 shows the INFO-level messages when Cams policy server Orville is shutdown.

...
... [INFO] Attempting to reconnect to Orville at 192.168.1.101:9191
... [INFO] Attempting to reconnect to Orville at 192.168.1.101:9191 ... [INFO] Attempting to reconnect to Orville at 192.168.1.101:9191
...

Example 12 - The Cams Agent ConnectionMonitor Reports a Failed Policy Server Connection

Another way to confirm proper operation of Cams policy server clustering is to monitor server-side log files. By default, log files are written to directory: CAMS_HOME/logs on each policy server host using the following naming scheme:

${cams.server.name}-{cams.security-domain.name}-<Service Name>.log

For example: Orville-system-access-control.log

To confirm proper round-robin load balancing across Cams policy servers:

  • Disable Cams web agent access control check caching (cams.access.check.cache=false). This will disable caching of unconditionally granted/denied web resources, which ensures that access control checks will be attempted to a Cams policy server.
  • Access a series of unconditionally granted or denied resources from the web or application server associated with the Cams web agent.

You should see an approximately equal number of logged access-control transactions in Wilbur-system-access-control.log and Orville-system-access-control.log.

Now shutdown one of the Cams policy servers (Orville) and attempt to access the same unconditionally granted or denied web resources. All access-control transactions should now be handled by the available Cams policy server (Wilbur).

Once you have confirmed proper operation of Cams policy server clustering, be sure to disable Cams cluster debug messages and enable Cams agent access control check caching (if desired):

cams.cluster.debug=false
cams.access.check.cache=true

More Cams Clustering Information

For more details on Cams policy server configuration and debugging, please see Policy Server Clustering.

Back | Next | Contents