IBM Support

Enabling routing trace on the ISAM appliance for the Reverse Proxy

Question & Answer


Question

How to enable and collect a routing trace of the Reverse Proxy ( WebSEAL ) instance on the ISAM appliance?

Cause

IBM support may ask for routing trace to be collected for analyzing a problem.

Answer

STATEMENT OF INTENT

This document serves as instructions for gather and uploading a routing trace to the IBM Support Team. IBM Support recommends verifying the available space on the ISAM for Web appliance to successfully complete the data gathering.

Failure to do so may cause an outage.

This sequence should only be attempted on direct request from IBM Support.



Notice! Enabling tracing for all the Reverse Proxy components using asterisk has been introduced in ISAM 8.0.1.3. Prior to ISAM 8.0.1.3 individual components had to be configured in the routing trace. For details how to setup a routing trace on the ISAM 8.0.1.2 or older version of the appliance view the "Use of Asterisk in Reverse Proxy Routing File Prevents WebSEAL from Starting" link provided in the "Related Information" section.

1) Enable routing trace for the Reverse Proxy ( WebSEAL )

1. Use a browser to access the ISAM Local Management Interface ( LMI )
  • Connect to https://<Management Interface>/core/login
  • Authenticate using an admin id


2. Edit Tracing Configuration File
  • On the LMI, navigate to Secure Web Settings > Manage > Reverse Proxy.
  • Select the Reverse Proxy ( WebSEAL ) instance of interest.
  • Select Manage > Configuration > Edit Tracing Configuration File.



  • Add the following line at the end of the routing configuration file.

    *:*.9:UTF8FILE.10.10000000:trace__webseald-<instance name>.log
    10 = the maximum amount of trace files
    10000000 = the amount of events per trace file

  • Modify <instance name> to match the selected instance. For example, "test" is the name of the instance here.


  • Click Save to save settings.

3. Deploy changes
  • Select "Click here to review the changes or apply them to the system."
  • Verify your pending changes and click Deploy


4. Restart Reverse Proxy ( WebSEAL ) instance
After deploying the changes you will see a System Warning stating the reverse proxy instance in question needs to be restarted.
  • Select the instance.
  • Click Restart.





2) Recreate the problem

3) Collect the routing trace
  • Unless otherwise instructed, collect the support file. From the LMI, use Manage System Settings > Support Files. For more details collecting the support file view the "Creating support file" link under the Related Information section.

Optionally IBM support may ask for you to deliver just the specific trace/log files.
  • While in "Manage Reverse Proxy Log Files" view, select the trace file of interest and select Manage > Export.



4) Disable routing trace for the Reverse Proxy ( WebSEAL )
1. Edit Tracing Configuration File
  • On the LMI, navigate Secure Web Settings > Manage > Reverse Proxy.
  • Select the Reverse Proxy ( WebSEAL ) instance of interest.
  • Select Manage > Configuration > Edit Tracing Configuration File.
  • Comment following line at the end of the routing configuration file and save settings.

    #*:*.9:UTF8FILE.10.10000000:trace__webseald-<instance name>.log



2. Deploy changes
3. Restart Reverse Proxy ( WebSEAL ) instance

5) Optional. Check the routing trace file prior uploading to IBM support
The following steps are not necessary for enabling and collecting the routing trace events. These are merely for guidance to validate existence of a routing trace file as well as to verify the time frame of the events written in the trace. The following simple checks assist in noticing missing data at an early stage which in turn will help speed up the problem solving process.

(A) Verify routing trace file gets successfully generated.
At the time of the Reverse Proxy instance startup a lot of information is written to a routing trace file. If a routing trace is not generated after the instance restart please verify the trace configuration setting for any misspelling or syntax errors. To check the existence of a routing trace file open the "Manage Reverse Proxy Log Files" view.
  • Select Reverse Proxy instance of interest.
  • Select Manage > Logging.



At minimum expect to find trace__webseal-<instance name>.log file generated. Additionally you may notice trace files named as
trace__webseal-<instance name>.log.1
trace__webseal-<instance name>.log.2
...
trace__webseal-<instance name>.log.<n>

Trace files with a numeric suffix are either rotated files from a trace file exceeding the maximum amount of events per file or if a reverse proxy instance has been restarted between the generated files.




(B) Verify the problem has been recreated inside the time frame events are written in the routing trace.
Many times IBM Support needs to compare different trace and log files between each other for the cross reference. Therefore it is important to collect all requested log and trace files concurrently so that each log/trace file contain events at the time of a problem. In a busy web site older events in the Reverse Proxy routing trace may get overwritten by the new events causing the crucial information about the problem being lost.

Always mark down the time when the problem is reproduced. By checking the first and the last event timestamp of a trace file it is possible to verify that problem was recreated between the collected events. Notice that you may have to check all the rotated files to find out the oldest timestamp of the collected events. In case the problem recreation seems to be outside of the time frame of collected events it is best to try collecting the trace again. If the maximum amount of routing trace files has been reached and recreation of the problem does not fit inside the time frame it may be necessary to increase the value of the "maximum amount of trace files" and/or value of the "amount of events per trace file". When necessary consult IBM Support for assistance setting appropriate values for the routing trace.

6) Upload to IBM support

[{"Product":{"code":"SSPREK","label":"Tivoli Access Manager for e-business"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"General Information","Platform":[{"code":"PF004","label":"Appliance"}],"Version":"8.0.1.3;9.0","Edition":"","Line of Business":{"code":"LOB24","label":"Security Software"}}]

Document Information

Modified date:
16 June 2018

UID

swg21974925

Page Feedback