Cams Administrator's Guide

Configuring Cams Policy Server

The Cams policy server is configured by editing the CAMS_HOME/conf/cams-reg-default.conf and CAMS_HOME/conf/cams.conf files. Many configuration options are provided, and, you are optionally empowered to extend some behaviors by implementing custom code. This document provides instructions on how to configure existing options and extend others.

Cams Policy Server Name

The Cams policy server name is defined within the registration file cams-reg-default.conf by property:

cams.server.name=MyCamsServer

This value is used for logging and to distinguish Cams policy server installations and their corresponding user sessions from each other. It does not need to correspond to the host's DNS name. You should change this value to something unique for your company or department, etc. For example, myhost_domain. Only alphanumeric and underscore ("_") characters are valid.

NOTE: The cams.server.name property may NOT be set within a cams.conf file, it must be set within a Cams policy server registration file.

Cams Cluster Name

The Cams cluster name is also defined within the Cams policy server registration file cams-reg-default.conf by property:

cams.cluster.name=MyCamsCluster

Every Cams policy server runs within a cluster, even if the cluster contains only one server. This value is used for logging and to distinguish 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 for hardening purposes. 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.

NOTE: The cams.cluster.name property may NOT be set within a cams.conf file, it must be set within a Cams policy server registration file.

For more information on Cams policy server clustering, see Policy Server Clustering Overview, Policy Server Clustering QuickStart, and Policy Server Clustering.

Connections

The Cams policy server listens for agent connections on a specified TCP/IP port specified by property:

cams.server.port=9191

The default server port is 9191, but you may also configure Cams to use any other available port.

NOTE: 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.

To limit the number of simultaneous Cams web agent connections, use property:

cams.server.maxConnections=200

The default maximum is 200. Remember that each Cams web agent may have many connections. For example, the Cams Apache 1.3 web agent uses one connection for each Apache process child.

Cams also provides a shutdown service on a different port. This is for security purposes to allow you to further refine access to only allow connections to the Cams shutdown service from administrative systems. Furthermore, a password you specify must be supplied by the client to activate shutdown. The default properties for the Cams shutdown service are:

cams.server.shutdown.port=9292
cams.server.shutdown.password=theEndIsNear

The default shutdown port is 9292. The Cams policy server shutdown scripts execute a client program that uses these properties. So, if these scripts are executed from the system that started the Cams policy server, the shutdown program will automatically connect to the correct shutdown port and provide the right password.

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

Email Notification

The Cams policy server may occasionally use email messages to notify administrators of configuration or administrative issues. The properties used to configure this service are:

cams.server.smtp.host=mail.mycompany.com
cams.server.smtp.from=cams@mycompany.com
cams.server.smtp.to=admin@mycompany.com

These values must be updated for compatibility with your installation environment. The value of cams.server.smtp.host must be the hostname or IP address of the mail server registered for your Internet domain. The value of cams.server.smtp.from must be an email identity permitted to send messages to the configured SMTP server. In general, an email alias or fictitious name associated with the Cams policy server should be used. The value of cams.server.smtp.to is the address of the administrator to which messages are sent. If this value is omitted, the value registered in your Cams product license contact attribute is used.

NOTE: Don't hand-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.

Secret Key Encryption

Default Cams policy server connections use selective encryption of data sent between Cams web agents and the Cams policy server. This is facilitated by use of encryption algorithms like Blowfish, DES, and DESede (triple DES) along with secret key values configured by the Cams policy server and participating Cams web agents. You use the following properties to set the options:

cams.skey.algorithm=Blowfish
cams.skey.key=ed28f2c7b60e978277d125d774bd25c1cad3c5c1a7f02757
cams.skey.iv=1a5dce1235fd429e

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

Logger

Cams configures it's own centralized trace logger, which logs 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.

Table 1 shows properties that can be used to customize a trace logger's behavior.

Property	Req/Opt	Description
logger.class	Req	The fully-qualified logger class name
logger.file.path	Req	The path where the log file is written, which can be fully-qualified or relative to CAMS_HOME.
logger.file.append	Opt	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.bufferedIO	Opt	If true the logger will buffer log messages before writing them to the log file. This can significantly improve logging performance. The default value is true.
logger.file.bufferSize	Opt	Indicates the size of the buffer to fill before writing to the log file. The default value is 4096.
logger.file.maxSize	Opt	The maximum size the logfile is allowed to grow before creating a new logfile. Suffixes KB, MB and GB are recognized. When log files are rolled over, the file name is appended with an numeric digit: 1, 2, 3, etc. The default value is 10MB.
logger.file.maxBackupIndex	Opt	The maximum rollover file index. When log files are rolled over, a numeric index is appended to the name, starting with 1 and proceeding to this value and then restarting at 1 again. The default value is 100.
logger.enableConsole	Opt	If true all log statements that are sent to the log file are also sent to the console. The default value is false.
logger.enableDebugFilter	Opt	If true all log statements that have the level DEBUG will not be logged. The default value is false.
logger.verbose	Opt	If true all DEBUG, INFO, WARN, ERROR and FATAL messages logged will contain the following format: [INFO ] Sample log message Class Name: com.cafesoft.cams.log.CamsTraceLogger Method Name: info() Line Number: 121 Timestamp: 25 Jul 2002 11:02:36,339 If false ONLY WARNING, ERROR and FATAL message level will use the verbose format, while DEBUG and INFO level messages will use the following format: [INFO ] Sample Log Message The default value is false.
logger.debug	Opt	If true the logger will output diagnostic debug statements to the System.err stream. The default value is false.

Table 1 - Properties for configuring a Cams trace logger

Debug

Cams policy server debug messages can be turned on or off at various levels. For example, you can enable global Cams policy server debug messages in cams.conf by setting:

cams.debug=true

Other service-level debug messages can also be enabled. Generally, you should only need to enable Cams policy server debug messages if instructed to do so by Cafésoft support.

Security Domain Registry

A Cams security domain registry factory is a Java class that loads information about the security domains known to Cams from the security-domain-registry.xml file. This factory is configured with the values shown in Example 1.

#
#---	The factory class used to create the SecurityDomainRegistry
#---	and it's configuration parameter(s)
#
security.domain.registry.factory=\
	com.cafesoft.security.engine.domain.XmlSecurityDomainRegistryFactory
security.domain.registry.factory.params=\
	${cams.home}/conf/domains/security-domain-registry.xml

Example 1 - The default Cams policy server security domain registry factor configuration

The default Cams policy server security domain registry factory (XmlSecurityDomainRegistryFactory), loads an XML registry file located in the directory specified by the parameter. The parameter's ${cams.home} substitution value is specified by the CAMS_HOME environment variable to the Cams policy server via the startup script.

Normally, you will only need to change this configuration if you move the security-domain-registry.xml file to another directory. However, the use of a factory provides the potential to store the Cams security domain registry in other document formats, a database or LDAP server should it be required.

Back | Next | Contents