| Back | Next | Contents | Cams Administrator's Guide |
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.
Before attempting to configure Cams policy server clustering, you should:
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!
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:
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 # |
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 # |
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.
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
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:
NOTE: Only the first license file found is loaded, so it must be valid for the IP address the server.
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
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:
... # # 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
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 |
Example 10 - Example INFO level messages when Cams policy server Orville is started
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 |
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).
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 |
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:
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
For more details on Cams policy server configuration and debugging, please see Policy Server Clustering.
© Copyright 1996-2005 Cafésoft LLC. All rights reserved.