Back | Next | Contents Cams Administrator's Guide

Policy Server Configuration

The Cams policy server is configured by editing the CAMS_HOME/conf/cams-reg-default.conf and CAMS_HOME/conf/cams.conf files. This document provides instructions on the properties you'll need to consider configuring. Information about the configuration requirements of each security domain hosted with a Cams policy server is found in Security Domain Configuration, Login Configuration and Access Control Services.

Configuring cams-reg.conf

The registration file CAMS_HOME/conf/cams-reg-default.conf configures the Cams cluster and Cams policy server names when only one Cams policy server is used. For Cams clusters with two or more Cams policy servers, the file name includes the IP address of the Cams policy server node it represents. This document only provides information on configuring cams-reg-default.conf when a single Cams policy is used. For information on naming conventions when using two or more Cams policy servers in a Cams cluster, see Policy Server Clustering Overview, Policy Server Clustering QuickStart and Policy Server Clustering.

Properties in bold red must have similar values set for Cams web agent properties in cams-web-agent.conf.

Property Description
cams.server.name

The Cams policy server name. The default name is MyCamsServer. This value distinguishes Cams policy servers and their corresponding user sessions from each other. It can but does not need to correspond to the host's DNS name. You should change this value to something unique to make it easy to identity. For example, cams1_host_domain. Only alphanumeric and underscore ("_") characters are valid.

cams.cluster.name

The Cams cluster name. The default name is MyCamsCluster. Every Cams policy server runs within a cluster, even if the cluster contains only one Cams policy server. This value distinguishes Cams cluster installations and their corresponding user sessions from each other. If your site deploys only one Cams policy server cluster, there is no need to change this value other than to customize it to your site. If you use multiple clusters in the same DNS domain, then it is wise to use different names for each cluster to prevent situations where a Cams web agent is sent a cookie for a Cams policy server that is not part of the cluster to which the Cams web agent belongs (this forces a Cams web agent 5100 error). Only alphanumeric and underscore ("_") characters are valid.

Table 1 - Properties for configuring the Cams policy server and cluster names

Configuring cams.conf

Most Cams policy server configuration values set in CAMS_HOME/conf/cams.conf should be left as supplied in the download. This section provides instructions on the properties at the top of CAMS_HOME/conf/cams.conf that you'll need to consider configuring. Properties in bold red must have similar values set for Cams web agent properties in cams-web-agent.conf.

Property Description
cams.debug

Toggle global Cams policy server-level debug messages on/off [true|false]. The default value is false. Global Cams policy server debug messages write to the Cams policy server trace log. Generally, you should only need to enable Cams policy server-level debug messages if instructed to do so by Cafésoft support.

cams.server.port

The TCP/IP port that the Cams policy server listens on for Cams web agent connections. The default port is 9191. You may use any available port.

WARNING: If a Cams web agent connects with the Cams policy server through your firewall, you must ensure that the port you use for the Cams connection is allowed to pass through your firewall.

cams.server.shutdown.port

The TCP/IP port that the Cams policy server shutdown service listens on. The default port is 9292. The Cams policy server shutdown service gracefully waits for all security domain services to finish processing current requests and closes all Cams web agent connections. Using a distinct port allows you to restrict network access to connections from administrative systems.

The CAMS_HOME/bin/shutdown.bat(.sh) scripts execute a client program that connects to the configured shutdown port and provides the cams.server.shutdown.password on the system that started the Cams policy server.

cams.server.shutdown.password

The password that must be supplied to activate the shutdown service. The default value is theEndIsNear.

NOTE: You should change this password as part of a hardening exercise.

cams.server.smtp.host

The DNS host name or IP address of the SMTP server at your site that will receive messages from Cams. The Cams policy server may occasionally use email messages to notify administrators of issues such as the maximum license count being exceeded.

WARNING: The cams.server.smtp.* values MUST be updated for your environment.

cams.server.smtp.from An email account address permitted to send messages to the configured SMTP server. In general, an administrator email address or an alias associated with Cams policy server administration should be used.
cams.server.smtp.to

An email address of the administrator to which messages are sent. If this value is omitted, the contact email address registered in your Cams product license keys is used.

WARNING: Don't edit your cams-license-keys.xml file to change the email address as this will corrupt the file. Instead, set cams.server.smtp.to to the desired email address.

cams.skey.algorithm
cams.skey.key
cams.skey.iv

The algorithm, secret key and initialization vector for encrypting and decrypting selected values sent between the Cams policy server and Cams web agents. Valid algorithms are AES, Blowfish, DES and DESede (triple DES). AES uses a 16 byte encryption key, Blowfish uses a 16 byte encryption key, DES uses an 8 byte key and DESede uses a 24 byte key. Blowfish is recommended. The number of secret key bytes used depends on the algorithm, although it is legal to supply more key bytes than needed. The initialization vector should be an 8 byte (16 hex digit) value.

NOTE: Use CAMS_HOME/bin/camsSecretKeyGen.bat(.sh) or the web application in the Cams Jetty test server to select the algorithm and generate the key and initialization vector values. Changing the secret key should be part of a hardening exercise.

Detailed information on configuring the values for these options is provided in Securing Cams Communications using Secret Keys.

logger.file.path

The fully-qualified path to the Cams policy server trace log. If the directory or log file is missing, it will be created. The Cams policy server trace log contains information about the startup, shutdown, warnings and errors of it's services. If Cams is not configured correctly, fails to load, detects a runtime error, or experiences any other anomaly, a message will be written by this logger.

NOTE: You will usually not need to update logger properties that are not documented here but may do so. See the comments within CAMS_HOME/conf/cams.conf for information on other properties.

logger.file.append

If true new log messages will be appended to the current log file. If false the current log file will be deleted and a new log file will be created. The default value is true.

logger.file.maxSize The maximum log file size before creating a new one in KB, MB or GB. The default value is 10MB.

Table 2 - Properties for configuring the Cams policy server

Configuring the Bind Address

By default the Cams policy server listens for network connections on the loopback IP address (127.0.0.1). However, only Cams web agents running on the same system as the Cams policy server can connect using this address. Because you'll probably use one or more Cams web agents installed on different network systems, you'll need to set the Cams policy server bind address to an IP address that is network accessible.

The Cams policy server bind address is specified as a command-line parameter when the Cams policy server is started. For example, if the system on which the Cams policy server is installed is 192.168.1.101, then:

-Dcams.server.bindaddr="192.168.1.101"

will tell the Cams policy server to bind to that IP address. If the value of this parameter is not a valid IP address or not an IP address assigned to the local system, then a fatal configuration error will be reported and the Cams policy server will fail to startup. If this parameter is not specified, the Cams policy server will bind to the first IP address returned from the list of IP addresses assigned to the local system.

To set the Cams policy server bind address:

Windows

Edit CAMS_HOME\conf\runcams.conf and set -Dcams.server.bindaddr to your server's IP address:

wrapper.java.additional.4=-Dcams.server.bindaddr=192.168.1.101

Linux/UNIX

Edit CAMS_HOME/bin/runcams.sh and set -Dcams.server.bindaddr to your server's IP address:

P="${P} -Dcams.server.bindaddr=192.168.1.101"

NOTE: Though you may use a DNS host name for the bind address, it is recommended that you use an IP address for best performance.

WARNING: The Cams web agent in your test Jetty web server will no longer connect after you change the Cams policy server bind address. If you make this change and desire to use the test Jetty web server, you must update the Cams web agent server URL value found in CAMS_HOME/jetty/etc/cams-webagent.conf.

Allocating Memory

The Cams policy server default settings allocate a maximum heap of 128MB system memory for the Java virtual machine (JVM) that will be used. This value is set low to enable use on virtually any system, including desktop systems that simultaneously run other development servers and applications. Though this setting may work for some production sites, we generally recommend allocating a maximum heap of at least 512MB (with 1GB of physical memory on the system). Because memory is relatively inexpensive you should avoid any chance of swapping to disk as this will dramatically reduce Cams policy server performance!

NOTE: It is good practice to set the -Xmx maximum heap JVM switch to no more than 50 percent of the physical memory on the system. That leaves plenty of memory for system level resources. You should NEVER set this value to the same size as the physical memory on the system.

You'll need to change the default Cams policy server JVM startup settings to take advantage of the additional memory. For example, for 1GB:

-Xms256m
-Xmx512m

To set the Cams policy server minimum and maximum JVM heap:

Windows

Edit CAMS_HOME\conf\runcams.conf and set:

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=256

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=512

Linux/UNIX

Edit CAMS_HOME/bin/runcams.sh and set:

#
#--- Start the Cams policy server.
#
${JAVA_HOME}/bin/java -server -Xms256m -Xmx512m -classpath ${CP} ${P} com.cafesoft.security.provider.CamsPolicyServer

See Performance Tuning for more addition information on customizing JVM parameters and hardware recommendations.

Back | Next | Contents