Previous Topic: How to Migrate SSL Keys and CertificatesNext Topic: Audit Logging

CA SiteMinder® Federation Standalone Guide › Logs to Monitor Federation Activities

Logs to Monitor Federation Activities

This section contains the following topics:

Federation Logging Overview

Federation Web Services (FWS) Logging

Server Trace Logging

server.log File Setup

Federation Data Object Trace Logging

Audit Logging

Transaction IDs to Aid Federation Troubleshooting

Federation Logging Overview

Troubleshoot federation operation by enabling logging. Logs provide important diagnostic information for you and for CA Support.

Several logs provide information about federated activities. By default, the system enables the following logs:

You can also enable the federation data store objects trace log, XPSConfig_date_time_stamp.log. This trace log monitors trace activity for the federation objects in the data store.

Checkpoint Log Messages

In the FWSTrace.log and the smtracedefault.log, there are checkpoint log messages that indicate what is happening during a transaction. For example:

[07/30/2013][11:34:44][4260][5824][1181adbb-993f775c-33ba08f3-76b52f3b-3d2280cd-4ae][SSO.java][processRequest][Reading SAML 2.0 SP Configuration [CHECKPOINT = SSOSAML2_SPCONFREAD_REQ]

You can search on these checkpoint messages to follow some of the processes occurring during a transaction.

In addition to the checkpoint messages, there are transaction IDs, which you can use to follow a transaction. If a transaction fails, the checkpoint messages and transaction IDs can help you determine the specific problem.

Federation Web Services (FWS) Logging

You can monitor the FWS application run-time activities by enabling the following logs:

To manage the log behavior, such as rollover frequency and log size, modify settings in the LoggerConfig.properties file.

Note: Do not confuse the LoggerConfig.properties file with the logger.properties file that configures the server.log file. The names are similar, but the files are different.

Follow these steps:

  1. Navigate to the following directory: 
    federation_install_dir\secure-proxy\Tomcat\webapps\affwebservices\WEB-INF\classes\

    Note: Use a forward slash (/) in the paths for a UNIX operating environment.

  2. Open the LoggerConfig.properties file in a text editor.
  3. (Optional) Modify the log settings. Review explanations and options for each setting in the LoggerConfig.properties file. The settings are:
    LoggingOn

    Enables or disables informational logging.

    LogFileName

    Default: federation_install_dir\\logs\\fws\\affwebserv.log

    affwebserv.log is the default file name. You can change the name.

    LogLocalTime
    LogRollover
    LogSize
    LogCount
  4. (Optional) Modify the trace settings for logging FWS messages. Review the explanations and the options for each setting in the LoggerConfig.properties file.
    TracingOn

    Enables or disables FWS trace logging to the FWSTrace.log file.

    EnableDNSLookUp
    TraceFileName

    The default output file name is FWSTrace.log. You can change this name.

    TraceConfigFile

    Identifies the trace configuration file. The configuration file determines which components and subcomponents the system monitors and logs messages.

    TraceRollover
    TraceSize
    TraceCount
    TraceFormat
    TraceDelim
  5. Save and close the file.
  6. Restart the federation services according to your operating environment.

Server Trace Logging

The server trace log (smtracedefault.log file) follows federation server runtime activities. The default location for this trace log is in the directory federation_install_dir\logs\server.

Note: If you enable tracing, large log files can result.

Two tasks are required to set up server-side trace logging:

  1. Set up the server trace log configuration file. The configuration file defines which components are monitored and written to the smtracedefault.log file. You can use the default file, smtracedefault.txt or use one of the other templates provided.
  2. Configure the behavior of the server trace log file, smtracedefault.log. Specify the location of the log output file, the location of the log configuration file, the format of the log output file, and the log rollover frequency.

Set Up the Server Trace Log Configuration File

Set up the log configuration file. A log configuration file defines which components are monitored and therefore, what is written to the smtracedefault.log file. You can use one of the following files for federation:

For efficiency, use one of the templates. Enter the name of a template in the LogTraceConfig parameter, which you access with the XPSConfig command and by selecting the SM option.

Note: The preconfigured templates are in federation_install_dir\siteminder\config\profiler_templates.

In place of the templates, you can use the default file and manually add all federation components in this file.

Follow these steps:

  1. Navigate to federation_install_dir\siteminder\config\smtracedefault.txt.
  2. Back up the template file.
  3. Open the smtracedefault.txt file in an editor.
  4. Edit the file by copying and pasting the following text into the file. Overwrite the existing text. 
    components: Server/Policy_Server_General, IsProtected/Resource_Protection,
Login_Logout/Authentication, Login_Logout/Policy_Evaluation,
Login_Logout/Active_Expression, Login_Logout/Session_Management,
IsAuthorized/Policy_Evaluation, JavaAPI, 
Fed_Server/Assertion_Generator, Fed_Server/Auth_Scheme,
Fed_Server/Configuration 
data: Date, Time, Tid, TransactionID, SrcFile, Function, Domain,
Resource, Action, User, SessionID, Data, AuthReason, Message
  5. Save the file.

Configure the Behavior of the Server Trace Log File

Use the XPSConfig tool, included with the product, to enable tracing for server-side runtime activities. XPSConfig is an interactive command-line utility that allows you to view product parameters and edit their settings.

Follow these steps:

  1. Open a command window on the system where the product is installed.
  2. Enter XPSConfig.

    Type the command as it is shown here. The command is case-sensitive.

    The Products Menu displays.

  3. Enter SM.

    The Parameters Menu displays. A number is associated with each parameter that you can modify.

  4. Enter the number associated with the parameter you want to modify.
  5. Enter c to change the value.
  6. Enter q to return to the parameter list.
  7. For server tracing, specify values for the following settings.
    LogTrace

    Enables tracing. The default for tracing is to be off, which is indicated by a space between two quotation marks (" "). Do not leave the setting blank.

    LogTraceConfig

    This value points to the tracing configuration file. There is no default value. Enter federation_install_dir\siteminder\config\template_name. The default template is smtracedefault.txt. There are other trace templates specifically for federation.

    Examples:

    federation_install_dir\siteminder\config\samlidp_trace.template

    federation_install_dir\siteminder\config\samlsp_trace.template

    LogTraceConsole

    Indicates whether messages are displayed in a console window. The default is not to log to the console.

    LogTraceFormat

    Determines how information is displayed in the log. The default is sm. Works with the LogTraceDelimiter setting to specify which character acts as a delimiter.

    LogTraceMode

    Specifies the trace mode. The default is 0.

    LogTraceDelimiter

    Identifies a character to serve as a delimiter in the log output file. There is no default value.

    LogTraceOutput

    Specifies the location of the log output file. The default is federation_install_dir\logs\server.

  8. Configure how frequently the logging and tracing files rollover by modifying the rollover settings. Enter the number associated with the parameter you want to modify.

    Note: Any changes to the log rollover settings apply to the smtracedefault.log file and the smps.log file.

    The rollover parameters are as follows:

    LogFilesToKeep

    Represents the number of Policy Server error logs to keep. Older files are deleted older files.

    LogRolloverDays

    Indicates if a rollover occurs on a daily basis. Enter the number that corresponds to the number of days that pass before a rollover occurs.

    LogRolloverInterval

    Indicates if a rollover occurs on an hourly basis. If this value is set, LogRolloverDays is ignored.

    LogRolloverOnStart (enabled by default)

    Indicates whether the log file is rolled over when the services are started.

    LogRolloverSize

    Indicates at what size the log files is rolled over. If the system reaches the size limit before the next rollover interval, the log file still rolls over.

    LogRolloverTime

    Indicates what time of day to perform the rollover. The system uses this setting with the LogRolloverDays parameter. Enter a value in the form "hour:minutes" using a 24 hour clock.

    Example: "22:00"

  9. If you are finished configuring parameters, keep entering q until you exit XPSConfig.

Changes made in XPSConfig are not recognized until you exit the XPSConfig tool. Where noted, some changes require that you restart the system services.

server.log File Setup

The server.log file is useful for examining the Administrative UI operation of the product. This log also contains messages about the embedded SPS server. This log file resides in the directory federation_install_home/logs/ui.

The logger.properties file and the log4j.properties file contain the log settings that determine what is recorded in the server.log file. The settings are groups of name/value pairs or directives that the system reads at run time.

Logger.properties file

The logger.properties file resides in the directory federation_install_dir/secure-proxy/Tomcat/properties. The file contents are grouped into the following sections:

The directives contained in this file follow the format name=value. Any lines beginning with the # symbol are comments, and are not read when the system loads configuration settings.

Note: Pathnames on Windows systems use double backslashes (\\).

Log4j.properties

The lo4j.properties file resides in the directory federation_install_dir/secure-proxy/Tomcat/webapps/fedui/WEB-INF/classes. This file determines the log level recorded for Administrative UI operation.

The procedure for modifying the log files is the same. You can modify the files without restarting the system.

Follow these steps:

  1. Open the file in a text editor.
  2. Edit the directives, as necessary.
  3. Save the file.

The log settings are changed.

Log Settings

Server.conf Settings

The Server.conf settings in the logger.properties file enable and disable logging, sets logging level, and sets the output format of the log messages. The entry that you can modify in this section must be in the following format:

log4j.rootCategory=<log_level>,<output_format>

log_level

Specifies the log level of a message. The following values are listed in an increasing order of priority:

OFF, FATAL, ERROR, WARN, INFO, DEBUG, ALL

To disable logging, set the log level to OFF. If the value is set to any other value, logging is enabled.

Default: INFO

output_format

Specifies whether a log message is displayed in a console, or in a file, or both.

Default: SvrFileAppender

Example: To set the log level to INFO and display a log message in a console and in a file, use the following entry:

log4j.rootCategory=INFO,SvrConsoleAppender,SvrFileAppender

SvrConsoleAppender Settings

The SvrConsoleAppender Settings section controls logging events to a console. The entry that you can modify in this section is:

log4j.appender.SvrConsoleAppender.layout.ConversionPattern=<log_message_format>

log_message_format

Specifies the format of a log message output to the console. The product supports all the log4j date pattern strings.

Default Value: [%d{dd/MMM/yyyy:HH:mm:ss-SSS}] [%p] - %m%n

SvrFileAppender Settings

The SvrFileAppender Settings section controls logging events to a file. This section defines the log rollover frequency and the format of the log messages that are written to the file. The entries that you can modify in this section are:

log4j.appender.SvrFileAppender.File=<log_file_path>
log4j.appender.SvrFileAppender.Append=true
log4j.appender.SvrFileAppender.layout.ConversionPattern=<log_message_format>

log_file_path

Specifies the name and path of the log file.

Default Name: server.log

Default Path: install_dir_home/secure-proxy/proxy-engine/logs/ui/server.log

true|false

Directs the system whether to append log messages to an existing file. If this value is set to true, the system appends new log messages to the existing log file. If this value is set to false, the system rolls over the existing log file and generates a new log file.

Default Value: true

log_message_format

Specifies the format of log messages that the system writes to the server.log file. The product supports all the log4j date pattern strings.

Default Value: [%d{dd/MMM/yyyy:HH:mm:ss-SSS}] [%p] - %m%n

Type of Log Rolling Used

The log rolling section determines when an existing log file is rolled over and a new log is generated. Enable a log to rollover based on the file size or the file date.

The entries that you can modify in this section are:

log4j.appender.SvrFileAppender.MaxFileSize=1MB
log4j.appender.SvrFileAppender.MaxBackupIndex=10
#log4j.appender.SvrFileAppender.DatePattern='.'yyyy-MM-dd

MaxFileSize

Specifies the maximum size the log file can reach after which the system must create a log file.

Default Value: 1MB

MaxBackupIndex

Specifies the maximum number of log files that the system creates. If the number of log files exceed the MaxBackupIndex number, the system deletes the oldest log file and it generates a new one.

Default Value: 10

DatePattern

Specifies the date when the system must create a log file.

Default: yyyy-MM-dd

A new log file is created with the name <log_file_name>.<date_format>

log_file_name

Specifies the name of the log file.

Default: server.log

date_format

Specifies the date when the log file was created. The file supports all the log4j date pattern strings.

Default: yyyy-MM-dd

log4j.properties File for server.log

The log4j.properties file controls extra Administrative UI logging that the system writes to the server.log file. This file resides in the directory federation_install_dir\secure-proxy\Tomcat\webapps\fedui\WEB-INF\classes.

You can modify the following entries:

log4j.appender.UIConsoleAppender.layout.ConversionPattern=<log_message_format>

log_message_format

Specifies the format of the log message output to the console. The product supports all the log4j date pattern strings.

Default Value: [%p] %c - %m%n

log4j.rootCategory=<log_level>,<output_format>

log_level

Specifies the log level of a message. The following values are listed in an increasing order of priority:

OFF, FATAL, ERROR, WARN, INFO, DEBUG, ALL

To disable logging, set the log level to OFF. If the value is set to any other value, logging is enabled.

Default: INFO

output_format

Specifies whether a log message is output to a console, or in to file, or both.

Default: UIConsoleAppender

Example: To set the log level to INFO and display a log message in a console and in a file, use the following entry:

log4j.rootCategory=INFO,UIConsoleAppender,UIFileAppender

You can also uncomment the two DEBUG entries.

Federation Data Object Trace Logging

Enable XPS tracing to monitor federation data store objects. These activities are written to the smtracedefault.log. The smtracedefault.log is in the directory federation_install_dir\logs\server.

Follow these steps:

  1. Open a command window.
  2. Enter XPSConfig.

    Type the command as it is shown here. The command is case-sensitive.

    The Products Menu displays.

  3. Enter X for the xTrace option.

    The Tracer Menu displays.

  4. Enter the number that is associated with the fed option. All options that are related to fed are selected and marked with an "x."
  5. Enter U to save the selections. This updates the tracer menu.
  6. Enter q until you exit the XPSConfig tool.
  7. Restart the federation services so that the changes take effect.
  8. Restart the federation services according to your operating environment.

    Note: Do not stop and start the services as the root user.