Debugging RSA Access Manager (AxM) Servers

[#1]

Article Number

000037641

Applies To

RSA Product Set: RSA Access Manager
RSA Version/Condition: 6.2
 

Issue

How to enable debug level logging in RSA Access Manager (AxM) Servers.

Resolution

Debug

The various debug parameters are used by the RSA Access Manager command files aserver.bat, eserver.bat and dispatcher.bat on Windows, and aserver.sh, eserver.sh, dispatcher.sh on Unix.
Basics
There are three key values to understand to debug a RSA Access Manager server to generate RSA debugging.
-DDEBUG
This is the most basic debugging operation.  This simply means that standard debug will be generated and (usually) will be displayed in the command window where the RSA Access Manager server was started.
-DDEBUG_FILE=<filename>
In many situations we want to save debug output for review later or to be sent to RSA Customer Support for analysis.  Where this is required this additional parameter may be used which when combined with -DDEBUG means that the debug output is redirected to the specified file.  Note that you must also use the -DDEBUG option; just using -DDEBUG_FILE<filename> on its own will not be of any value.
-DDEBUG_STDOUT=<filename>
This command sends standard output to a log file.  This command may be used without the -DDEBUG flag. 
-DDEBUG_FULL
If this parameter is supplied then debug output will contain an extended date format that shows the date as well as the time as well as the name of the class that generated the message.
-DDEBUG=<facility>[:<facility>][:<facility>]...
It is possible to limit the debug output to specific facilities within RSA Access Manager.  This option is subject to change and should only be used on a specific request of RSA staff.  At the release of RSA Access Manager 5.5.3 the various facilities available for debugging are:
 

Debug Options

 

*	The Default facility.  Add * if you want normal debug in addition to one of the specific facilities.
DAL_CONN	DAL connection (pool) information.
CACHE	Low-level cache events (only Eserver caches currently).
CEREAL	Admin API serialization.
DAL_PROFILE	DAL command performance profiling. Currently LDAP-only.
DAL_POOL	DAL connection pool statistics; used for performance tuning.
DAL_POOL_MASSIVE	Enables additional tracing of the DAL connection pool to track leaks. In order to use this, DAL_POOL must also be turned on.
KEYCLIENT	Key client events.
MUXPOOL	MUX pool statistics; used for performance tuning.
OBJADAPTORS	API adaptors.
READCMD	GetObjsByRelRangeCmd
SEARCH	Some search routines.
SEARCHADAPTORS	NameSearchAdaptor
SSL	Low-level SSL initialization and session information.
USERSEARCH	User search classes (under da.admin.search)
WRITECMD	APIUserAdaptor
Additional in 6.0:
DAL_ADMIN_SEARCH	High level of detail regarding the admin DAL search code.
SECURID	Special facility for SecurID debugging.
SORT	Sorting of data for admin API calls.
Additional in 6.1.4
SNMPTABLEMODEL	SNMP Table model related updates
JMX_CONN_POOL	Information regarding JMX connection pool status.
SESSION	Information related to Cookie replay operations.
Additional in 6.2
DCP	Debug messages related to user migration during DCP capture mode.

Examples
The basic debug option -DDEBUG is already built into the command files and is simply activated by supplying a parameter at the command line.  For example, when you normally start a dispatcher it might be like this:

C:\ct\server\bin>dispatcher
RSA Access Manager Authorization Dispatcher
Version 5.5.3 (Build 2588)
Copyright (c) 1997-2005 RSA Security Inc.
All rights reserved.
http://www.rsasecurity.com
Bootstrap at Fri Jan 19 16:27:27 EST 2007
Loading configuration:
        dispatcher.conf ... done.
Validating license: done.
Initializing email notification handler with the following parameters
Hostname: mailhost
Port: 25
Starting dispatcher list server on port 5608
KEY-00004-I: Status for server localhost:5609:500 at Fri Jan 19 16:27:37 EST 2007 is:
        status: 0
        leader: localhost:5609:500
        number of keys: 0
        next key creation: .Fri Jan 19 16:27:37 EST 2007
        next key expiration: Tue Dec 21 08:14:41 EST 292269018
KEY-00008-I: Generating new session key at Fri Jan 19 16:27:39 EST 2007.

Now if we do the same operation but we want to active the -DDEBUG option then we simply run "dispatcher debug", for example:
 

C:\ct\server\bin>dispatcher debug
RSA Access Manager Authorization Dispatcher
Version 5.5.3 (Build 2588)
Copyright (c) 1997-2005 RSA Security Inc.
All rights reserved.
http://www.rsasecurity.com
Bootstrap at Fri Jan 19 16:30:43 EST 2007
# RSA Access Manager Authorization Dispatcher
# Version 5.5.3 (Build 2588)
#
# Date:   Fri Jan 19 16:30:43 EST 2007
# Java:   1.4.2_10 / Sun Microsystems Inc.
# System: kerry@192.168.51.205, running Windows XP 5.1 on x86
#
Loading configuration:
        dispatcher.conf ... done.
16:30:43:124 [*] [main] - Loaded configuration:
16:30:43:134 [*] [main] - ----
16:30:43:134 [*] [main] - RSA Access Manager.dispatcher.admin_address: mjbond@csau.ap.rsa.net
16:30:43:134 [*] [main] - RSA Access Manager.dispatcher.email_threshold: 5
16:30:43:134 [*] [main] - RSA Access Manager.dispatcher.lease_expiration: 15
16:30:43:134 [*] [main] - RSA Access Manager.dispatcher.list_port: 5608
16:30:43:134 [*] [main] - RSA Access Manager.dispatcher.list_port.backward_compatible: true
16:30:43:134 [*] [main] - RSA Access Manager.dispatcher.log: dispatcher.log
16:30:43:134 [*] [main] - RSA Access Manager.dispatcher.log.backups: 10000
16:30:43:144 [*] [main] - RSA Access Manager.dispatcher.log.delimiter: ,

Advanced

For the other debug options, we must make some minor modification to the particular start script to include the desired option.  Here is a section of the bottom of dispatcher.bat (although the other two files are almost identical.  Also, one of the lines (starting %_EXECJAVA%) will line wrap.
 

:run
set JAVA_HOME=%CT_ROOT%\jre
title %TITLE%
%_EXECJAVA% -DDisp -Xmx64m %DEBUG% -Djava.ext.dirs=%JAVA_HOME%\lib\ext;%CT_ROOT%\lib -DCT_ROOT=%CT_ROOT% sirrus.dispatcher.AuthorizationDispatcher %ACTION%
set JAVA_HOME=%OLD_JAVA_HOME%
To add any of the other debug values we simply insert any of them after the %DEBUG% value and can supply more than one, so for example to insert -DDEBUG_FILE and -DDEBUG_FULL we simply modify the file as shown below where the modifications are in bold.
:run
set JAVA_HOME=%CT_ROOT%\jre
title %TITLE%
%_EXECJAVA% -DDisp -Xmx64m %DEBUG% -DDEBUG_FILE=dispdebugfile.log -DDEBUG_FULL -Djava.ext.dirs=%JAVA_HOME%\lib\ext;%CT_ROOT%\lib -DCT_ROOT=%CT_ROOT% sirrus.dispatcher.AuthorizationDispatcher %ACTION%
set JAVA_HOME=%OLD_JAVA_HOME%

 Now when we save the file and go to use it (just as we did above) then we should not see this:
 

C:\ct\server\bin>dispatcher debug
RSA Access Manager Authorization Dispatcher
Version 5.5.3 (Build 2588)
Copyright (c) 1997-2005 RSA Security Inc.
All rights reserved.
http://www.rsasecurity.com
Bootstrap at Fri Jan 19 16:50:25 EST 2007
Writing debug log to dispdebugfile.log
Loading configuration:
        dispatcher.conf ... done.
Validating license: done.
Initializing email notification handler with the following parameters
Hostname: mailhost
Port: 25
Starting dispatcher list server on port 5608
KEY-00004-I: Status for server localhost:5609:500 at Fri Jan 19 16:50:27 EST 2007 is:
        status: 0
        leader: localhost:5609:500
        number of keys: 0
        next key creation: Fri Jan 19 16:50:27 EST 2007
        next key expiration: Tue Dec 21 08:37:31 EST 292269018
KEY-00008-I: Generating new session key at Fri Jan 19 16:50:28 EST 2007.

Notice that the amount of data displayed on the screen is back to the "non-debug" amount but that we additionally have a line telling us that debug is being directed to dispdebugfile.log.


Netscape tracing
In addition to the RSA supplied debug levels other third party debug code may also be activated.  If the RSA Access Manager system is connected to an LDAP back end (rather than a SQL database) then. the LDAP traffic can be debugged:

-Dcom.netscape.ldap.trace=
If no file name is specified then the output appears in any console window.  If a filename is supplied, then the debug goes to the names file. 
In many instances, the RSA Access Manager services will be running as Windows services started at boot time rather than as command windows.  For details about how to insert these same debug options into the services startup see the solution
a18246     How to enable debugging for RSA RSA Access Manager backend services on Microsoft Windows
a37296     Debugging the RSA Access Manager admin API
Additional
Additional documentation on running RSA Access Manager processes may be found in the documentation supplied with the software as well as online copies available in RSA SecurCare Online
 
RSA Access Manager Installation and Configuration Guide
(insert link)