Logs are of immense help while trouble shooting issues that occur during Siteminder installation and configuration.Although there is a lot of documentation on Siteminder but documentation about Siteminder logging is very scarce and distributed on internet.Here I am trying to pen down my understanding of logging in Siteminder version 6.0 and above and from various other sources available on internet.This post mainly deals with the Siteminder Web Agent logging.Hope this would help our friends.
The Web Agent uses two log files:
- Error log file—This file contains program and operational-level errors. For example, the Web Agent not being able to communicate with Policy Server. This file does not have an option to control the level of detail output in the log.
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.
2. Trace log file—contains detailed and configurable warning and informational messages, such as trace messages and flow state messages. It also includes data such as header details and cookie variables.
- 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.
The following parameters in the Agent Configuration Object play a vital role while enabling and configuring logs for Siteminder Agents.
|LogAppend||Determines whether the SiteMinder Agent logs information to an existing log file instead of rewriting the entire file each time logging is invoked.Note: To use the LogAppend parameter, also specify the LogFile and LogFileName parameters.|
|LogConsole||Logs messages in a Command Prompt window.|
|LogFile||Determines whether messages are written to a file.If you set the Logfile parameter to yes, be sure to specify the location of the log file in the LogFileName parameter.|
|LogFileName||If the Logfile parameter is set to yes, the location and file name of the file where the SiteMinder Agent writes messages.|
|LogLevel||Determines the amount and type of information that is logged in a file or a console window. The log levels are:0—No log messages, however, a log file is created.
|LogRollover||Determines whether the SiteMinder Agent starts a new log file after a specified period or when the log file reaches a certain size.If set to yes, a new log file is created after the amount of time specified in the LogRolloverTime parameter, or after the log reaches the size specified in the LogRolloverSize parameter.|
|LogRolloverSize||Indicates the maximum KB size of the log file before the SiteMinder Agent creates a new log file.The default is 10 MB (10240 KB).Note: The LogRollover parameter must be set to yes for this parameter to apply.|
|LogRolloverTime||Indicates when the SiteMinder Agent creates a new log file. Specify:
The default value is every 12 hours.
Note: The LogRollover parameter must be set to yes for this parameter to apply.
Enabling logs for the Web Agent
We can configure the Web Agent to write messages to a log file.To write messages to a log file:
1. Set the LogFile parameter in the ACO to Yes.
2. Specify a filename in the LogFileName parameter in the ACO.
Enable the LogAppend parameter to add logging information to an existing log file instead of rewriting the entire file,every time logging is invoked.
Setting the log level for the Web Agent
We can configure the Web Agent to generate different levels of log messages and then display them in a console window or a file. Choosing a log level facilitates troubleshooting because log levels determine the severity and extent of the logged messages. This allows us to control the detail that the Web Agent includes in a log.
For each log level we select, the Web Agent prints messages for that level and messages from any lower level. For example, if we choose level 0, the Web Agent prints only those messages. If We choose level 2, the Web Agent prints all messages from levels 0 through 2.
Initially, we must leave the log level at 0 so the Web Agent logs only critical errors. If we want to audit websites activity more closely, change the log level to 1 or 2. The log level is changed dynamically. Do not stop and restart the Web server. Within approximately 30 seconds (that of restarting the Web server, we will see new messages in the console window or in the log file.
Web Agent log file rollover
When data is appended to a log file continually, the file can grow to an unmanageable size. Rolling log files enables us to schedule a log file rollover based on a time interval and a file size limit.
Three parameters in the WebAgent.conf control log file rollover are as follows:
If we set the RollingLogPeriod and RollingLogSizeLimit parameters, log file rollovers and log file sizing will be effective. Rollover always occurs after the specified “log periods.” It also occurs when the size limit is reached; for example, if
RollingLogPeriod=4 and RollingLogSizeLimit=100:
If the log file size passes 100 KB at 3:12, rollover will occur at 3:12.
Another rollover will occur at 4:00, regardless of the log file size.
Subsequent rollovers will occur on the 4-hour targets and whenever the file size reaches 100 KB.
Displaying Web Agent log messages in a console
We can display log messages in a command prompt window by configuring the LogConsole parameter.To configure the LogConsole parameter:
1. In the WebAgent.conf file, set the LogConsole parameter to Yes.
2. In the Services control panel, restart the Web server.
To stop displaying messages in the Console window, set the LogConsole parameter to No.
Logs on the Policy Server machine:
We use the following logs on the Policy Server machine to troubleshoot SSO-related issues: