Web Services Security Guides › CA SiteMinder® Web Services Security Agent Guide for Apache-based Web Servers › SiteMinder WSS Agent Logging › How to Set Up Trace Logging

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:
   • Trace Log Components and Subcomponents
   • Trace Message Data Fields
   • Data Field Filters
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:

• Administration
• Filter
• HighLevelAgent
• LowLevelAgent
• LowLevelAgentWP

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:

• RequestProcessing

SAMLAgent

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

• RequestProcessing

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:

• AgentCore
• Cache
• authentication
• Responses
• Management
• SSO
• Filter

Agent_Functions

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

• Init
• UnInit
• IsProtected
• Login
• ChangePassword
• Validate
• Logout
• Authorize
• Audit
• FreeAttributes
• UpdateAttributes
• GetSessionVariables
• SetSessionVariables
• DeleteSessionVariables
• Tunnel
• GetConfig
• DoManagement

Agent_Con_Manager

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

• RequestHandler
• Cluster
• Server
• WaitQueue
• Management
• Statistics

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:

• == (exact match)
• != (does not equal)

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:

• Entries are case-sensitive.

  When you specify a component, data field, or filter, the values must match exactly the options in the WebAgentTrace.conf file instructions.

• Uncomment the configuration settings lines.
• If you modify the WebAgentTrace.conf file before installing a new agent over an existing agent, the file is overwritten. Rename or back up the file first. After the installation, you can integrate your changes into the new 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
      

   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:

• When the agent starts.
• When the size limit of the trace log (specified by the value of the TraceFileSize parameter) is reached.

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 is collected.

   Note: For CA SiteMinder® 12.52 SP1, 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:

• Windows—agent_home\bin\
• UNIX—agent_home/bin/

  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

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

• Windows—agent_home\config\
• UNIX— agent_home/config/

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