Previous Topic: Uninstall a SiteMinder WSS AgentNext Topic: How to Set Log Files, and Command-line Help to Another Language

Web Services Security Guides › CA SiteMinder® Web Services Security Agent Guide for iPlanet Web Servers › SiteMinder WSS Agent Logging

SiteMinder WSS Agent Logging

This section contains the following topics:

Logs of Start-up Events

Error Logs and Trace Logs

How to Set Up Trace Logging

Configure XML Message Processing Logging

Disable SiteMinder WSS Agent XML Message Processing Logging

How to Set Log Files, and Command-line Help to Another Language

Logs of Start-up Events

To assist in debugging, startup events are recorded in a log. Each message may provide clues about the problem. These logs are stored in the following locations:

Error Logs and Trace Logs

You can use the Web Agent logging function to monitor the performance of the Web Agent and its communication with the Policy Server. The logging feature provides accurate and comprehensive information about the operation of CA SiteMinder® processes to analyze performance and troubleshoot issues.

A log is a record of events that occur during program execution. A log consists of a series of log messages, each one describing some event that occurred during program execution. Log messages are written to log files.

Note: IIS Agents create log files only after the first user request is submitted. Apache 2.0 Web Agents create log files when the Apache server starts.

The Web Agent uses the following log files:

Error log

Contains program and operational-level errors. One example is when the Web Agent cannot communicate with Policy Server. The level of detail output in this log cannot be customized. Error logs contain the following types of messages:

Error messages

Contain program-level errors, which indicate incorrect or abnormal program behavior, or an inability to function as expected due to some external problem, such as a network failure. There are also operational-level errors. This type of error is a failure that prevents the operation from succeeding, such as opening a file or authenticating a user.

Informational messages

Contain messages for the user or administrator that some event has occurred; that is, that a server has started or stopped, or that some action has been taken.

Warning messages

Contain warnings for the user or administrator of some condition or event that is unusual or indicative of a potential problem. This does not necessarily mean there is anything wrong.

Trace log

Contains detailed warning and informational messages, which you can configure. Examples include trace messages and flow state messages. This file also includes data such as header details and cookie variables. Trace logs contain the following messages:

Trace messages

Provide detailed information about program operation for tracing and/or debugging purposes. Trace messages are ordinarily turned off during normal operation. In contrast to informational, warning, and error messages, trace messages are embedded in the source code and can not easily be localized. Moreover, trace messages may include significant data in addition to the message itself; for example, the name of the current user or realm.

You specify the location of both the error and trace log files when you configure the Web Agent. Use the error and trace logs to help solve any issues that may prevent the Web Agent from operating properly.

Note: For Agents on Windows platforms, set the EnableWebAgent parameter to yes to ensure that the Web Agent log gets created. If you leave EnableWebAgent set to no (the default) and set the logging parameters, the Agent log gets created only for Agents on UNIX platforms.

More Information

Set Up and Enable Error Logging

Configure Trace Logging

Parameter Values Shown in Log Files

Web Agents list configuration parameters and their values in the Web Agent error log file, but there are differences between the ways that Traditional and Framework agents do this.

Framework agents record the configuration parameters and their values in the log file exactly as you entered them in the Agent Configuration Object or the local configuration file. All of the parameters, including those which may contain an incorrect value, are recorded in the log file.

Traditional agents process the parameter values before recording them. If the parameter has a proper value, the parameter and its value are recorded in the log file. Parameters with incorrect values are not recorded in the log file.

Set Up and Enable Error Logging

Error logs require the following settings:

The parameters that enable error logging and determine options such as appending log data are defined in a local configuration file or an Agent Configuration Object at the Policy Server.

Agents that are installed on an IIS or Apache web servers do not support dynamic configuration of log parameters that are set locally in a local configuration file. The changes take effect when the Agent is restarts. However, these log settings can be stored and updated dynamically in an agent configuration object at the Policy Server.

Note: IIS Agents create log files only after the first user request is submitted. Apache 2.0 Web Agents create log files when the Apache server starts.

Follow these steps:

  1. If you do not have a log file already, create a log file and any related directories.
  2. Set the value of the LogFile parameter to yes.

    Note: Setting the value of this parameter to yes in a local configuration file of a web server overrides any of the logging settings that are defined on the Policy Server. For example, suppose that the value of this parameter is set to yes in a LocalConfig.conf file. The agent creates log files even though the value of the AllowLocalConfig parameter in the corresponding agent configuration object is set to no. You can also set the related logging parameters in the LocalConfig.conf file also to override any other settings in the agent configuration object.

  3. Specify the full path to the error file, including the file name, in any of the following parameters:
    LogFileName

    Specifies the full path (including the file name) of the log file.

    Default: No

    Example: (Windows) agent_home\log\WebAgent.log

    Example: (UNIX/LInux) /export/iPlanet/servers/https-jsmith/logs/WebAgent.log

    LogFileName32

    Specifies the full path of a log file for a SiteMinder WSS Agent for IIS (on 64-bit Windows operating environments protecting 32-bit applications). The 32-bit applications run in Wow64 mode on the 64-bit Windows operating environment. If logging is enabled but this parameter is not set, the SiteMinder WSS Agent for IIS appends _32 to the log file name.

    Default: No

    Limits: For Windows 64-bit operating environments only. Specify the file name at the end of the path.

    Example: (Windows 64-bit operating environments using Wow64 mode) agent_home\log\WebAgent32.log.

  4. (Optional) Set the following parameters (in the Agent Configuration Object on the Policy Server or in the local configuration file):
    LogAppend

    Adds new log information to the end of an existing log file. When this parameter is set to no, the entire log file is rewritten each time logging is invoked.

    Default: No

    LogFileSize

    Specifies the size limit of the log file in megabytes. When the current log file reaches this limit, a new log file is created. The new log file uses one of the following naming conventions:

    • For framework agents, the new log file has a sequence number that is appended to the original name. For example, a log file named myfile.log is renamed to myfile.log.1 when the size limit is reached.
    • For traditional agents, the new log files are named by appending the date and timestamp to the original name. For example, a log file named myfile.log, is renamed to myfile.log.09-18-2003-16-07-07 when the size limit is reached.

    Archive or remove the old files manually.

    Default: 0 (no rollover)

    Example: 80

    LogLocalTime

    Specifies whether the logs use Greenwich Mean Time (GMT) or local time. To use GMT, change this setting to no. If this parameter does not exist, the default setting is used.

    Default: Yes

    If you use a local configuration file, your settings resemble the following example:

    LogFile="yes"
LogFileName="/export/iPlanet/servers/https-myserver/logs/errors.log"
LogAppend="no"
LogFileSize="80"
LogLocalTime="yes"

    Error logging is enabled.

Enable Transport Layer Interface (TLI) Logging

When you want to examine the connections between the agent and the Policy Server, enable transport layer interface logging.

To enable TLI logging

  1. Add the following environment variable to your web server. 
    SM_TLI_LOG_FILE
  2. Specify a directory and log file name for the value of the variable, as shown in the following example: 
    directory_name/log_file_name.log
  3. Verify that your agent is enabled.
  4. Restart your web server.

    TLI logging is enabled.

Limit the Number of Log Files Saved

You can limit the number of log files that an agent keeps. For example, if you want to save disk space on the system that stores your agent logs, you can limit the number of log files using the following parameter:

LogFilesToKeep

Specifies the number of agent log files that are kept. New log files are created in the following situations:

Changing the value of this parameter does not automatically delete any existing logs files which exceed the number that you want to keep. For example, If your system has 500 log files stored, and you decide to keep only 50 of those files, the agent does not delete the other 450 files.

Setting the value of this parameter to zero retains all the log files.

Default: 0

Follow these steps:
  1. Archive or delete any existing log files from your system.
  2. Set the value of the LogAppend parameter to no.
  3. Change the value of the LogFilesToKeep parameter to the number of log files that you want to keep.

How to Set Up Trace Logging

To set up trace logging, use the following process:

  1. Set up and Enable Trace logging.
  2. Determine what you want to record in the trace log by reviewing the following lists:
  3. Duplicate the default Trace Configuration File.
  4. Modify the duplicate file to include the items you want to record.
  5. Restart the agent.
Configure Trace Logging

Before you can use trace logging, you must configure it by specifying a name, location, and parameters for the trace log file. These settings control the size and format of the file itself. After trace logging is configured, you determine the content of the trace log file separately. This lets you change the types of information contained in your trace log at any time, without changing the parameters of the trace log file itself.

Follow these steps:

  1. Locate the WebAgentTrace.conf file on your web server. Duplicate the file.
  2. Open your Agent Configuration Object or local configuration file.
  3. Set the TraceFile parameter to yes.

    Note: Setting the value of this parameter to yes in a local configuration file of a web server overrides any of the logging settings that are defined on the Policy Server. For example, suppose that the value of this parameter is set to yes in a LocalConfig.conf file. The agent creates log files even though the value of the AllowLocalConfig parameter in the corresponding agent configuration object is set to no. You can also set the related logging parameters in the LocalConfig.conf file also to override any other settings in the agent configuration object.

  4. Specify the full path to the trace log files in following parameters:
    TraceFileName

    Specifies the full path to the trace log file.

    Default: No default

    Limits: Specify the file name in this parameter.
    Example: web_agent_home\log\trace.log

  5. Specify the full path to the duplicate copies of WebAgentTrace.conf file (you created in Step 1) in the following parameters:
    TraceConfigFile

    Specifies the location of the WebAgentTrace.conf configuration file that determines which components and events to monitor.

    Default: No default

    Example: web_agent_home\config\WebAgentTrace.conf

    Note: This file is not used until the web server is restarted.

  6. Define the format of the information in your trace log file by setting the following parameters in your Agent Configuration Object or local configuration file:
    TraceAppend

    Adds new logging information to the end of an existing log file instead of rewriting the entire file each time logging is invoked.

    Default: No

    TraceFormat

    Specifies how the trace file displays the messages. Choose one of the following options:

    • default—uses square brackets [] to enclose the fields.
    • fixed—uses fields with a fixed width.
    • delim—uses a character of your choice to delimit the fields.
    • xml—uses XML-like tags. A DTD or style sheet is not provided with the Web Agent.

    Default: default (square brackets)

    TraceDelimiter

    Specifies a custom character that separates the fields in the trace file.

    Default: No default

    Example: |

    TraceFileSize

    Specifies (in megabytes) the maximum size of a trace file. The Web Agent creates a new file when this limit is reached.

    Default: 0 (a new log file is not created)

    Example: 20 (MB)

    LogLocalTime

    Specifies whether the logs use Greenwich Mean Time (GMT) or local time. To use GMT, change this setting to no. If this parameter does not exist, the default setting is used.

    Default: Yes

  7. Edit the WebAgentTrace.conf file to have agent monitor the activities you want.

    Framework Agents do not support dynamic configuration of log parameters set locally in the Agent configuration file. Consequently, when you modify a parameter, the change does not take effect until you restart the web server. However, these log settings can be stored and updated dynamically if you configure them in an Agent configuration object on the Policy Server.

  8. Restart the web server so the agent uses the new trace configuration file.
Trace Log Components and Subcomponents

The CA SiteMinder® Agent can monitor specific CA SiteMinder® components. When you monitor a component, all of the events for that component are recorded in the trace log. Each component has one or more subcomponents that the agent can also monitor. If you do not want the agent to record all of the events for a component, you can specify only those subcomponents you want to monitor instead.

For example, if you want to record only the single sign-on messages for an agent on a web server, you would specify the WebAgent component and the SSO subcomponent.

The following components and subcomponents are available:

AgentFramework

Records all Agent framework messages. (Applies only to framework agents.) The following subcomponents are available:

AffiliateAgent

Records web Agent messages related to the 4.x Affiliate Agent, which is part of Federation Security Services, a separately-purchased product. (Applies only to framework agents.) The following subcomponent is available:

SAMLAgent

Web Agent messages related to the SAML Affiliate Agent. (Applies only to framework agents.) The following subcomponent is available:

WebAgent

Records all Web Agent log messages. Applies to all Agents except IIS 6.0 or Apache 2.0 Agents. The following subcomponents are available:

Agent_Functions

Records all Agent API messages. The following subcomponents are available:

Agent_Con_Manager

Records messages related to internal processing of the Agent API. The following subcomponents are available:

For an explanation of each subcomponent, see the WebAgentTrace.conf file.

Trace Message Data Fields

You can define what each trace message for a specific component contains by specifying which data fields to include in the message.

Data fields use the following syntax:

data:data_field1,data_field2,data_field3

Some data fields are shown in the following example:

data:message,date,time,user,agentname,IPAddr

There may not be data for fields in each message, so blank fields my occur. For example, if you select RealmOID as a data field, some trace messages will display the realm's OID while others will not.

The following data fields are available:

Message

Includes the actual trace message

SrcFile

Includes the source file and line number of the trace message

Pid

Includes the process ID

Tid

Includes the thread ID

Date

Includes the date

Time

Includes the time

PreciseTime

Includes the time, including milliseconds

Function

Includes the function in the code containing the trace message

User

Includes the name of the user

Domain

Includes the CA SiteMinder® domain

Realm

Includes the CA SiteMinder® realm

AgentName

Includes the Agent name being used

TransactionID

Includes the transaction ID

DomainOID

Includes the CA SiteMinder® domain OID

IPAddr

Includes the client IP address

RequestIPAddr

Includes the trace file displays the IP of the server where Agent is present

IPPort

Includes the client IP port

CertSerial

Includes the certificate serial number

SubjectDN

Includes the subject DN of the certificate

IssuerDN

Includes the Issuer DN of the certificate

SessionSpec

Includes the CA SiteMinder® session spec

SessionID

Includes the CA SiteMinder® session ID

UserDN

Includes the User DN

Resource

Includes the requested resource

Action

Includes the requested action

RealmOID

Includes the realm OID

ResponseTime

Includes the average response time in milliseconds of the Policy Servers associated with a CA Web Agent or SDK Agent and API application

Note: To output the ResponseTime to a trace log, include the component Agent_Con_Manager along with the data field ResponseTime in the WebAgentTrace.conf file or other file specified in the Policy Server Configuration Object (ACO) and restart the Policy Server. The Agent_Con_Manager component, or Agent API Connection Manager, calculates the ResponseTime each time a response is received from a Policy Server and keeps a running average. To locate the ResponseTime in the trace log, search for [PrintStats].

Trace Message Data Field Filters

To focus on a specific problem, you can narrow the output of the trace log by specifying a filter based on the value of a data field. For example, if you are having problems with an index.html page, you can filter on resources with an html suffix by specifying Resource:==/html in the trace configuration file. Each filter should be on a separate line in the file.

Filters use the following syntax:

data_field:filter

The following types of filters are available:

The filters use boolean logic as shown in the following examples:

Action:!=get (all actions except get)

Resource:==/html (all resources ending in /html)

Determine the Content of the Trace Log

The WebAgentTrace.conf file determines the content of the trace log. You can control which components and data items appear in your trace log by modifying the settings of the WebAgentTrace.conf file on your web server. The following factors apply when editing the file:

Follow these steps:

  1. Open the WebAgentTrace.conf file.

    Note: We recommend duplicating the original file and changing the copy. Modifying the copy preserves the default settings.

  2. Add components and subcomponents using the following steps:
    1. Find the section that matches your type of agent. For example, if you have an Apache 2.0 Agent that is installed on your server, look for a line resembling the following example: 
      # For Apache 2.0, Apache 2.2, IIS 7.0 and SunOne Web Agents

      Note: For more information, see the CA SiteMinder® Web Agent Installation Guide.

    2. Locate the following line in that section: 
      #components:
    3. Uncomment the line. Then add the component names that you want after the colon. Separate multiple components commas as shown in the following example: 
      components:  AgentFramework, HTTPAgent
    4. (Optional) Follow the component name with the name of a subcomponent you want. Separate the subcomponent name with a slash as shown in the following example: 
      components:  AgentFramework/Administration
  3. Add data fields and filters using the following steps:
    1. Locate the following line in the appropriate section: 
      #data:
    2. Uncomment the line. Then add the data fields that you want after the colon. Separate multiple data fields with commas as shown in the following example: 
      data: Date, Time, Pid, Tid, TransactionID, Function, Message, IPAddr
    3. (Optional) Add filters to your data fields by following the data field with a colon, the Boolean operator and the value you want. The values you specify for the filters must match exactly. The following example shows a filter which logs activities for a specific IP address: 
      data: Date, Time, Pid, Tid, TransactionID, Function, Message, IPAddr:==127.0.0.1

      Note: Each filter must be on a separate line in the file.

  4. Save your changes and close the file.
  5. Restart the web server to apply your changes.

    The content of the trace log has been determined.

Limit the Number of Trace Log Files Saved

You can limit the number of trace logs that a CA SiteMinder® agent keeps. For example, if you want to save disk space on the system that stores your agent logs, you can limit the number of trace logs using the following parameter:

TraceFilesToKeep

Specifies the number of CA SiteMinder® agent trace log files that are kept. New trace logs are created in the following situations:

Changing the value of this parameter does not automatically delete any existing trace logs which exceed the number that you want to keep. For example, If your system has 500 trace logs stored, and you decide to keep only 50 of those files, the agent does not delete the other 450 trace logs.

Setting the value of this parameter to zero retains all the trace logs.

Default: 0

Follow these steps:

  1. Archive or delete any existing trace logs from your system.
  2. Set the value of the TraceAppend parameter to no.
  3. Change the value of the TraceFilesToKeep parameter to the number of trace logs that you want to keep.

Collect Detailed Agent Connection Data with an Agent Connection Manager Trace Log

To collect detailed information about the connections between a SiteMinder WSS Agent and Policy Server, you create a Trace Log file that contains information gathered by the Agent Collection Manager.

Follow these steps:

  1. Open your Agent Configuration object or local configuration file.
  2. Set the value of the TraceFile parameter to yes.

    Note: Setting the value of this parameter to yes in a local configuration file of a web server overrides any of the logging settings defined on the Policy Server. For example, when the value of this parameter is set to yes in a LocalConfig.conf file log files are generated even if the value of the AllowLocalConfig parameter in the corresponding Agent Configuration object on the Policy Server is set to no. Additionally, set the related trace logging parameters (that define the file name, size, and so on) in the LocalConfig.conf file to override any Policy Server trace log settings.

  3. Specify the full path to the trace log file for your Agent Connection Data in the TraceFileName parameter. This is the file that contains the trace log output.
  4. Set the value of the TraceConfigFile parameter to the full path of the following file: 
    agent_home/config/AgentConMgr.conf
    agent_home

    Indicates the directory where the SiteMinder WSS Agent is installed on your web server.

    Default (Windows 32-bit SiteMinder WSS Agent installations: C:\Program Files\CA\Web Services Security\webagent

    Default (Windows 64-bit SiteMinder WSS Agent installations: C:\Program Files\CA\Web Services Security\webagent\win64

    Default (Windows 32-bit SiteMinder WSS Agent installations operating on 64-bit systems: C:\Program Files (x86)\CA\Web Services Security\webagent\win32

  5. Define the format the trace log file for your Agent Connection Data by setting the following parameters:
    TraceAppend

    Adds new logging information to the end of an existing log file instead of rewriting the entire file each time logging is invoked.

    Default: No

    TraceDelimiter

    Specifies a custom character that separates the fields in the trace file.

    Default: No default

    Example: |

    TraceFileSize

    Specifies (in megabytes) the maximum size of a trace file. The Web Agent creates a new file when this limit is reached.

    Default: 0 (a new log file is not created)

    Example: 20 (MB)

    TraceFormat

    Specifies how the trace file displays the messages. Choose one of the following options:

    • default—uses square brackets [] to enclose the fields.
    • fixed—uses fields with a fixed width.
    • delim—uses a character of your choice to delimit the fields.
    • xml—uses XML-like tags. A DTD or style sheet is not provided with the Web Agent.

    Default: default (square brackets)

    LogLocalTime

    Specifies whether the logs use Greenwich Mean Time (GMT) or local time. To use GMT, change this setting to no. If this parameter does not exist, the default setting is used.

    Default: Yes

  6. Restart your web server so the new settings take effect.

    Detailed information about the SiteMinder WSS Agent connections will be collected.

    Note: For CA SiteMinder® 12.52, the BusyHandleCount and FreeHandleCount attributes are not used.

Configure XML Message Processing Logging

In addition to Web Agent logging functionality, the SiteMinder WSS Agent provides an additional level of log information relating specifically to its processing of XML messages. SiteMinder WSS Agent logging is implemented using Apache’s log4j standard (see http://logging.apache.org).

Note: SiteMinder WSS Agent logging does not start until an XML message that needs to be processed is received.

By default, SiteMinder WSS Agent logging is enabled and written to the soasm_agent.log file in:

You can change logging parameters for your SiteMinder WSS Agent by editing the log.config file, which can be found in:

Disable SiteMinder WSS Agent XML Message Processing Logging

To disable SiteMinder WSS Agent XML message processing logging, remove or comment out (using a "#" prefix) the following lines from the log.config file located in the Agent config subdirectory:

log4j.appender.A2=org.apache.log4j.DailyRollingFileAppender
log4j.appender.A2.File=${NETE_TXM_ROOT}/bin/soasm_agent.log