Federation Guides › Partnership Federation Guide › Log Files that Aid Troubleshooting

Log Files that Aid Troubleshooting

This section contains the following topics:

Federation Web Services Trace Logging

Federation Services Trace Logging (smtracedefault.log)

Federation Web Services Trace Logging (FWSTrace.log)

Update FWS Data in the Logs

Secure Proxy Engine Logs for Federation

Resolving Signature Verification Failures

Federation Database Objects Trace

Federation Web Services Trace Logging

The Web Agent trace logging facility and the Policy Server Profiler monitor the performance of the Web Agent and Policy Server. These logging mechanisms provide comprehensive information about CA SiteMinder® operation so you can analyze the system performance and can troubleshoot issues.

For partnership federation, several logging components are available to collect trace messages for federated communication. Trace messages provide detailed information about system operation. Trace messages are ordinarily turned off during normal operation. You can enable them to extract in-depth information in addition to the trace message itself. For example, you can look at the fwstrace.log to see the generated SAML assertion or collect the name of the current user.

The collected trace messages are written to a trace log. The fwstrace.log is located in the directory web_agent_home/log.

You can establish trace logs at the Web Agent and the Policy Server to monitor CA SiteMinder® operation.

Federation Services Trace Logging (smtracedefault.log)

The profiler is the Policy Server facility for logging. You can use the profiler to collect trace messages for federation services and write them to the smtracedefault.log file.

The component that controls the trace messages for federation services at the Policy Server is the Fed_Server component.

The Policy Server Profiler allows you to trace internal Policy Server diagnostics and processing functions.

Follow these steps:

1. Start the Policy Server Management Console.

   Important! If you are accessing this graphical user interface on Windows Server 2008, open the shortcut with Administrator permissions. Use Administrator permissions even if you are logged in to the system as an Administrator. For more information, see the release notes for your CA SiteMinder® component.

2. Click the Profiler tab.
3. Set the Enable Profiling option to enable profiling.
4. To select configuration settings for the Profiler, do one of the following:
   • Accept the Profiler settings specified by the default smtracedefault.txt file presented in the Configuration File drop-down list.
   • Select another configuration file that has already been selected during this management session from the Configuration File drop-down list.
   • Click the Browse button to select another configuration file.
5. To change the Profiler settings stored in a Profiler configuration file and save them in the same or a new file, click the Configure Settings button to open the Policy Server Profiler dialog.
6. Adjust the settings presented in the Output group box to specify the output format for information generated by the Policy Server Profiler.
7. Click Apply to save your changes.

Notes:

Changes to the Profiler settings take effect automatically. However, if you restart the Policy Server, a new output file (if the Profiler is configured for file output) is created. The existing Profiler output file is automatically saved with a version number. For example:

smtracedefault.log.1

If changes to the Logging or Tracing facility settings are not related to the Profiler output file, for example, enabling/disabling the console logging on Windows, the existing file is appended with new output without saving a version of the file.

By default The Policy Server retains up to ten output files (the current file and nine backup files). Older files are replaced automatically with newer files when the ten file limit is reached. You can change the number of files to retain by configuring the TraceFilesToKeep DWORD registry setting to the required decimal value. The TraceFilesToKeep registry setting must be created in the following registry location:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Netegrity\SiteMinder\CurrentVersion\
LogConfig\TraceFilesToKeep

The Profiler tab has a "Buffered Tracing" option, which is set by default to improve Policy Server performance. This option is on Solaris systems only.

Trace Logging Templates for the IdP and SP

To make the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Policy Server. You can use these templates instead of creating your own trace configuration file to collect the data that gets written to a trace log.

The following templates are available for trace logging related to the Identity Provider and the Service Provider, such as assertion generation or SAML authentication.

Look at each template to see the exact contents. The templates are located in siteminder_home/config/profiler_templates.

Federation Web Services Trace Logging (FWSTrace.log)

To simplify the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Web Agent Option Pack. You can use these templates instead of creating your own trace configuration file to collect the data.

The following templates are available:

All the FWS templates include the Fed_Client component and subcomponents for the specific data being tracked. To see the exact contents, open each template.

Follow these steps:

1. Navigate to the template directory in web_agent or web_agent_option_pack_home/config.
2. Make a copy of the template, rename it.
3. (Optional) Modify the template so it includes only the data you want to monitor.

   Note: Do not edit the template directly.

4. Save the new template.

The templates determine the federation components that the federation system monitors. To enable trace logging and format how the data appears in the log file, modify the Logger.Config properties file.

Follow these steps:

1. Navigate to web_agent or webagent_optionpack_home/affwebservices/WEB-INF/classes.
2. Open the LoggerConfig.properties file. The LoggerConfig.properties file contains descriptions of all the settings.
3. Set the TracingOn setting to Yes. This option instructs the trace facility to write messages to the log file.
4. Set the TraceFileName setting to the full path of the log file. The default location is in web_agent or webagent_optionpack_home/config/FWSTrace.log.

   Note: You can rename the log file. FWSTrace.log is the default name.

5. Set the TraceConfigFile setting to the full path of the trace configuration file. This file can be the default template, one of the other preconfigured templates, or your own configuration file. Regardless of which template you specify, all output is written to the log file you specify in the TraceFileName setting.

   Specify only one template. All the templates reside in the directory web_agent or web_agent_option_pack_home/config.

6. Optionally, modify how the information in the trace log output file is displayed. The following settings dictate the format of the log file:
   • TraceRollover
   • TraceSize
   • TraceCount
   • TraceFormat
   • TraceDelim

FWS Template Sample

The following text is an excerpt from the FWS_SLOTrace.conf template. Most of the file contains comments and instructions on how to use the file, the command syntax, and the available subcomponents for the Fed_Client component.

The excerpt shows the component, Fed_Client and the subcomponents (Single_Logout and Configuration) that are monitored. The excerpt also shows the specific data fields that indicate the required contents of each message (Date, Time, Pid, Tid, TransactionId, SrcFile, Function, Message).

components: Fed_Client/Single_Logout, Fed_Client/Configuration
data: Date, Time, Pid, Tid, TransactionID, SrcFile, Function, Message

Update FWS Data in the Logs

If you modify any part of the federation configuration, flush the Federation Web Services cache for the changes to appear in the trace logs.

Note: A brief delay can occur from when the changes are made and when Federation Web Services receives the information.

To flush the cache

1. Log in to the Administrative UI.
2. Select Administration, Policy Server, Cache Management.

   The Cache Management page displays.

3. Click Flush All in the All Caches section of the page.
4. Click Close

Secure Proxy Engine Logs for Federation

Partnership-based federation contains a secure proxy engine that forwards traffic to backend servers. The secure proxy engine includes the following components:

• Apache Web Server

  Acts as the HTTP listener, handling HTTP traffic for incoming requests, and can handle HTTPS traffic, once properly configured.

• Tomcat server

  Provides a servlet container for the operation of the UI. The Apache web server communicates to the Tomcat server through a Tomcat connector named mod_jk.

You can supply CA Support with log files related to these components to troubleshoot problems in your partnership federation environment.

Two Apache logs that aid partnership federation troubleshooting are:

mod_jk.log

mod_jk.log is enabled by default with the product. After the first contact with the federation server, information begins logging to this file. The mod_jk.log file is located in federation_mgr_home\logs\fws.

To modify this log file:

1. Navigate to federation_mgr_home\secure-proxy\httpd\conf
2. Open the httpd.conf file.
3. Change the following lines

   JkLogFile "federation_mgr_home/logs/fws/mod_jk.log"
   

   JkLogLevel error
   

   To disable the mod_jk.log, comment out or remove these lines from the file.

httpclient.log

For debug purposes only, you can enable the httpclient.log. The httpclient.log file is located in federation_mgr_home\secure-proxy\proxy-engine\logs.

To modify this log file:

1. Navigate to federation_mgr_home\secure-proxy\proxy-engine\conf.
2. Open the server.conf file
3. Change the following line:

   httpclientlog="yes"
   

To modify the location of the httpclient.log file and the log level, edit the httpclientlogging.properties file. This file is in the directory federation_mgr_home\secure-proxy\Tomcat\properties.

Resolving Signature Verification Failures

A malicious user can commit an XML signature wrapping attack by changing the content of a document without invalidating the signature. By default, software controls for the Policy Server and Web Agent Option Pack are set to defend against signature wrapping attacks. However, a third-party product can issue an XML document in a way that does not conform to XML specifications. As a result, the default signature checks can result in a signature verification failure.

Signature verification failures occur for the following reasons:

• A duplicate ID element is in the XML document and the signature references this duplicate ID. Duplicate ID attributes are not permitted.
• The XML signature does not reference the expected parent element, and a signature wrapping vulnerability is logged.

If a federation transaction fails, examine the smtracedefault.log file and the fwstrace.log file for a signature verification failure. These errors can indicate that the received XML document is not conforming to XML standards. As a workaround, you can disable the default Policy Server and Web Agent protection against signature wrapping attacks.

Important! If you disable the protection against signature vulnerabilities, determine another way to protect against these attacks.

To disable the XML signature wrapping checks:

1. Navigate to the xsw.properties file. The file exists in different locations for the Policy Server and the Web Agent.
   • For error messages in the Policy Server smtracedefault.log file, go to siteminder_home/config/properties
   • For error messages in the Web Agent fwstrace.log, go to

     web_agent_option_pack_ home/affwebservices/web-INF/classes.

     Note: If the web agent option pack is installed on the same system as the web agent, the file resides in the web_agent_home directory.

2. Change the following xsw.properties settings to true:
   • DisableXSWCheck=true (Policy Server setting only)
   • DisableUniqueIDCheck=true (Policy Server and Web Agent Option Pack setting)

     Note: The value of the DisableUniqueIDCheck setting must be the same for the Policy Server and the Web Agent Option Pack.

3. Save the file.

Federation Database Objects Trace

Enable XPS validation and federation object tracing to monitor federation database activities. CA SiteMinder® logs these activities to the smps.log file, in the directory siteminder_home\log.

Follow these steps:

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

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

   The Products Menu displays.

3. Enter XPS.

   The Parameters Menu displays.

4. Enter the number for the LogValidationWarnings parameter.
5. Enter c to change the value to true. With a Boolean value, XPSConfig automatically changes the value to the opposite of the current setting.

   When set to true, the parameter enables tracing for XPS Validation warnings.

6. Enter the number for the Trace parameter.
7. Enter c to change the value to true.

   When set to true, the parameter enables XPS trace debugging.

8. Enter q until you return to the Product Menu.
9. Enter FED.

   The FED parameters menu display.

10. Enter the number for the TRACE parameter.
11. Enter c to enable it.

    When set to true, the TRACE parameter enables tracing for federation XPS objects.

12. Enter q to return to the Parameters Menu. If you are done modifying 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 services.

13. Restart the Policy Server.