Web Agent Guides › Web Agent Configuration Guide › Agent Configuration Methods

Agent Configuration Methods

This section contains the following topics:

Central and Local Configuration Together

Central Configuration

A central agent configuration manages one or more Web Agents from an Agent Configuration Object in the Policy Server. The Agent Configuration Object that resides in the Policy Server contains the parameters used by the Web Agents. One advantage of central configuration is that you can update the parameter settings of several agents at once. Most parameter changes occur dynamically, but some Framework parameters require a web server restart after they are changed.

You create and edit an Agent Configuration Object with the Administrative UI. Each Web Agent communicating with the Policy Server must be associated with an Agent Configuration Object, but many Web Agents can use a single Agent Configuration Object.

Note: For more information about creating an Agent Configuration Object, see the Policy Server documentation.

More Information

Parameters Requiring a Server Restart when Changed

Implement Central Configuration

Central configuration is enabled by default. The agent uses the configuration settings from the existing Agent Configuration Object that you specified when you configured the agent with the configuration wizard. You can change the settings of the parameters to suit your needs at any time.

Follow these steps:

Log in to the Administrative UI.
The Welcome screen appears.
Click Infrastructure, Agent Configuration Objects.
A list of agent configuration objects appears.
Click the modify icon in the row of Agent Configuration Object you want.
The Modify Agent Configuration window appears.
Verify that the value of the AllowLocalConfig parameter is set to no.
Use the Administrative UI to modify the settings of any other parameters according to your needs.
Click Submit.
The Modify Agent Configuration window closes, and a confirmation message appears.
(Optional) Enter any comments about the change in the comment field for future reference.
Click Yes.
A confirmation message appears. Central configuration is implemented. Most parameter changes occur dynamically, but some changes require a web server restart to take effect.

More information:

Parameters Requiring a Server Restart when Changed

Local Agent Configuration

Local Configuration

A local agent configuration manages a Web Agent using local files that are installed on the system hosting the web server. The parameter settings in the local file override any settings stored in an Agent Configuration Object on the Policy Server. The settings in the Agent Configuration Object do not change. Situations to consider local agent configuration include the following:

When you have three Apache Web Agents, and the first two (A and B) use identical parameter settings, but you want the third Apache Agent (C) use the most of the settings from A and B while acting as a reverse proxy. To accomplish this, use central agent configuration for Apache Agents A and B, but use local configuration for Apache Agent C.

When the Policy Server administrator is not the same person (or group) who configures an Agent. For example, the information technology department in a company maintains the Policy Server, but the finance department uses an Agent to control access to an accounting application. Someone from the information technology department enables local configuration for the Agent on the Policy Server, but another person from the finance department controls the specific configuration settings for the Agent that protects the accounting application.

Framework Web Agents use the following files for local configuration:

WebAgent.conf: Contains the core settings that the Framework Web Agent uses to start and connect to a Policy Server.
LocalConfig.conf: Contains the configuration settings for the Framework Web Agents.

Traditional Web Agents use the following file for local configuration:

WebAgent.conf: Contains all of the configuration settings for traditional Web Agents.

WebAgent.conf File Locations

The following table shows the locations of the WebAgent.conf file on various web servers:

web_agent_home

Indicates the directory where the CA SiteMinder® Agent is installed.

Default (Windows 32-bit installations of CA SiteMinder® Web Agents only): C:\Program Files\CA\webagent

Default (Windows 64-bit installations [CA SiteMinder® Web Agents for IIS only]): C:\Program Files\CA\webagent\win64

Default (Windows 32-bit applications operating on 64-bit systems [Wow64 with CA SiteMinder® Web Agents for IIS only]): C:\Program Files (x86)\webagent\win32

Default (UNIX/Linux installations): /opt/ca/webagent

Web Server	File Location
IIS	web_agent_home\bin\IIS
Oracle iPlanet (iPlanet/SunOne)	Oracle_iPlanet_server_home/https-hostname/config where Oracle_iPlanet_home is the location in which theOracle iPlanet web server is installed and hostname is the name of the server.
Apache, IBM HTTP Server Oracle HTTP Server	web_server_home/conf where web_server_home is the installed location of the web server
Domino	Windows: c:\lotus\domino UNIX: $HOME/notesdata

More information:

Enable a Web Agent

Disable a Web Agent

WebAgent.conf file for Framework Agents

In addition to the AgentConfigObject, HostConfigFile, and EnableWebAgent parameters, the following parameters are also added to the WebAgent.conf file of Framework Agents:

Important! Do not modify any sections of the file that refer to other CA SiteMinder® products other than the Web Agent. However, you can change the values of the Web Agent parameters in the file.

LocalConfigFile

Specifies the location of the LocalConfig.conf file, where most of Agent configuration settings reside.

ServerPath

Identifies the web server directory (of Apache 2.0 and Oracle iPlanet web servers) to the Agent.

LoadPlugin

Specifies which plug-ins are loaded for Framework Agents. The plug-ins support different types of Agent functions. The following plug-ins are available:

HttpPlugin

Specifies whether the Web Agent operates as an HTTP agent.

Default: Enabled

SAMLAffiliatePlugin

Allows communication between the Web Agent and a SAML Affiliate Agent (if you have purchased Federation Security Services).

Default: Disabled

Affiliate10Plugin

Allows communication between the Web Agent and a 4.x Affiliate Agent.

Default: Disabled.

Limits: The SAML affiliate agent does not use this plug-in.

OpenIDPlugin

Lets the web agent use the OpenID authentication scheme (OIAS).

Default: Disabled

To enable the other LoadPlugin entries, remove the pound symbol (#) from the beginning of the line.

AgentIdFile

Specifies the path of the AgentId file which stores the unique ID string of the agent. The agent automatically generates the AgentId file, which must not be modified. Both on Windows and UNIX, the agent must have write permission to update the AgentId file. On Windows, the Web Agent configuration wizard grants the write permission automatically.

Default name: Agentid.dat

Path: WebAgent.conf directory/AgentId.dat

LocalConfig.conf File Locations (Framework Agents)

When you install a Framework Web Agent, the CA SiteMinder® installation program creates a LocalConfig.conf file in the following directory:

Windows: web _agent_home\config
UNIX: web _agent_home/config

Important! This file contains all of the default settings. Do not modify this file. We recommend creating a backup copy of this file for future reference or for recovery purposes.

When you configure the Web Agent, the configuration wizard copies the LocalConfig.conf file to the following directory:

IIS web server: web_agent_home\bin\IIS
Oracle iPlanet web server: Oracle_iPlanet_home/https-hostname/config
Apache web server: Apache_home/conf

The Web Agent retrieves its configuration settings from this copy of the LocalConfig.conf file.

Parameters Found Only in Local Configuration Files

For central Agent configurations, most of the parameters in the local configuration file are also in an Agent Configuration Object. The following parameters are used in the local configuration file only and are not found in Agent Configuration Objects:

AgentConfigObject

Defines the name of an Agent Configuration Object (stored on a policy server) in a local agent configuration file. This parameter is not used in Agent Configuration Objects.

Default: no default

EnableWebAgent

Activates a Web Agent and allows it to communicate with the Policy server. Set this parameter to yes only after you have finished changing all of the configuration parameters.

Default: No

HostConfigFile

Specifies the path to the SMHost.conf file (in an IIS 6.0 or Apache agent) that is created after a trusted host computer has been successfully registered with a Policy server. All Web Agents on a computer share the SMHost.conf file.

Default: No default

Implement Local Configuration

You can control whether local configuration is allowed with the following parameter:

AllowLocalConfig

Instructs the Agent Configuration Object on the Policy Server to read the local configuration file to obtain configuration parameters for the agent. This parameter is used only in Agent Configuration Objects.

Add multiple values for this parameter in the Agent Configuration Object to control which parameters can be changed in a local configuration file. When multiple values are set for this parameter, they are processed in the following order:

If yes is used, all parameters can be set locally.
No takes precedence over a list of parameters. No also overrides yes when both values are set together. This option lets you quickly disable local configuration entirely without having to remove any of the other configuration parameters from the Agent Configuration Object.

Default: No (local configuration prohibited).

Example: No, EnableAuditing, EnableMonitoring (all local configuration prohibited).

Example: No, Yes (all local configuration prohibited).

Example: EnableAuditing, EnableMonitoring (allows local control of the only the two previous parameters).

Follow these steps:

Log in to the Administrative UI.
Click Infrastructure, Agent Configuration Objects.
Click the modify icon in the row of the agent configuration object you want.
The Modify Agent Configuration dialog appears.
Click the edit icon to the left of the AllowLocalConfig parameter.
The Edit Parameter dialog appears.
Change the text in the Value field to yes, and then click OK.
The Edit Parameter dialog closes.
Click Submit.
(Optional) Enter any remarks about the change in the comment field for future reference.
Click Yes.
Local configuration is enabled.
Open the appropriate local configuration file on your web server and change the parameter settings you want.
For traditional agents only, set the value of the EnableWebAgent parameter to yes.
Save and close the local configuration file.
For Framework agents only, do the following steps:
1. Open the WebAgent.conf file.
2. Set the value of the EnableWebAgent parameter to yes.
3. Save and close the WebAgent.conf file.
Restart the web server.
Local configuration is enabled and any updated parameters are changed.

More information:

Enable a Web Agent

Parameters Requiring a Server Restart when Changed

How to Edit an Agent Configuration File

The agent configuration file controls the settings of a locally configured Web Agent. To change those settings, use the following process:

Create a backup copy of WebAgent.conf (for a traditional agent) or the LocalConfig.conf file (for a Framework agent).
Open the original copy of the agent configuration file with a text editor.
Enable or disable parameters by doing any of the following tasks:
- Removing the pound sign (#) from the beginning of the line to enable a parameter.
- Adding the pound sign (#) to the beginning of the line to disable a parameter.
Change the values of parameters using the following guidelines:
- Do not add spaces between the parameter names, the equal sign (=), and the parameter values.
- Surround the parameter values with quotation marks.
- The WebAgent.conf and LocalConfig.conf files are not case-sensitive. You do not have to match the case shown in the sample file that is installed with the agent.
- Many values are shown in the file as descriptive variables, such as <Agent Name>,<IP Address>. Replace the angle brackets and text with the values you want.
- In cases where the value is Empty, a blank is valid as the default. A default value applies only if there is no pound sign (#) preceding the parameter.
Set EnableWebAgent to yes only when you are done. Then save and close the file.
All local configuration changes are effective. If you make more changes after an Agent has been enabled, restart your web server to apply those changes.

Restrict Changes to Local Configuration Parameters

With central agent configuration, you can restrict the configuration parameters which local web server administrators modify. We recommend this method when the CA SiteMinder® administrator and the web server administrator are different people.

Follow these steps:

Log in to the Administrative UI.
The Welcome screen appears.
Click the Infrastructure, Agent Configuration Objects.
A list of Agent Configuration objects appears.

Click the edit icon in the line Agent Configuration Object you want.

The Modify Agent Configuration dialog appears.
Click the edit icon to the left of the AllowLocalConfig parameter.
The Edit Parameter dialog appears.
Erase the text in the Value field, and then click the multivalue option button.
Click Add.
An empty field appears.
Type the name of the parameter to which you want to allow access in the field. Separate multiple parameters with commas. Only those parameters in the list can be changed locally.
Example: The following example shows how to allow only the EnableAuditing and EnableMonitoring parameters to be set on the local web server:

AllowLocalConfig=EnableAuditing,EnableMonitoring
(Optional) Repeat Steps 5 and 6 to add more parameters.
Click OK.
The Edit Parameter dialog closes, and the Modify Agent Configuration dialog appears.
Click Submit.
The Modify Agent Configuration dialog closes, and a confirmation message appears.
(Optional) Enter any remarks about the change in the Comment field for future reference.
Click Yes.
Your changes will be applied the next time the Web Agent polls the Policy Server.

Central and Local Configuration Together

If you have a large number of Web Agents that you want to configure centrally, but the settings of a few of those Web Agents need to be different than the others, you can use a combination of central and local configuration together.

For example, if you need to configure multiple cookie domain single sign-on across a CA SiteMinder® network without configuring the Agents individually, you can use a central configuration for all of the agents, and local configuration settings for the smaller group that needs the different settings.

In the previous example, suppose the CookieDomain parameter in the Agent Configuration Object is set to example.com. However, for one Web Agent in your network, you want to set the CookieDomain parameter to .example.net, while still using all the other parameter values set in the Agent Configuration Object.

To implement the example configuration

With the Administrative UI, create an Agent Configuration Object with all the parameters that you want for your environment. Set the CookieDomain parameter to .example.com
Set the AllowLocalConfig parameter of the Agent Configuration Object to yes.
At one Web Agent, change only the local configuration file (on the web server) to use example.net as the value of the CookieDomain parameter. Do not modify any other parameters.

The value for the CookieDomain parameter in the lone Agent's local configuration file overrides the value in the Agent Configuration Object, while the Agent Configuration Object determines the settings for all the other parameters.