Basics of pdadmin: How to open the shell and authenticate yourself

This is the first in the series of posts that explain how to complete various tasks with ‘pdadmin’ command line tool. All versions of IBM Security Access Manager for Web (formerly known as IBM Tivoli Access Manager for e-Business) come with this tool, which sometimes makes it much more useful than Web Portal Manager UI. Here I will cover the basics – how to open the pdadmin shell and how to authenticate yourself.

There are several possible ways to get to the pdadmin prompt.

  • Open command prompt on your installation and type ‘pdadmin’ – usually the binaries directory that includes pdadmin tool is a part of the system path. But if this does not work, you can find pdadmin executable in the Policy Director’s “bin” directory. Typical path is “C:\Program Files\Tivoli\Policy Director\bin” on Windows systems and “/opt/PolicyDirector/bin” on UNIX.
  • New in v7.0: Use the so-called REST API, which is in fact simple HTTP interface to pdadmin utility. More about it in later posts.
  • In the new virtual appliance edition (also available in v7.0) you can log in to the appliance console, and then find the pdadmin prompt (covered up as ”admin” item) under “wga” menu.

The first thing you have to do after the pdadmin prompt was opened is to authenticate your session to the server. This task is pretty straightforward.

pdadmin> login
Enter User ID: sec_master
Enter Password: ********
pdadmin sec_master>

Note that there is no need to issue explicit login command when working via HTTP API, since the authentication credentials are specified in the dedicated section of the HTTP payload.

How to turn on debug log in WebSEAL

You can turn on debug logging with “trace” utility from “pdadmin” shell via “server task” call. Here is the general format of the call:

server task <instance>-<host> trace set <component> <level> file path=<path>

The parts in the angle brackets should be replaced with appropriate values:

  • <instance> – the name of WebSEAL instance
  • <host> – hostname of the server that runs WebSEAL
  • <component> – name of the component to turn logging on for (see below)
  • <level> – log level to use (1 to 9, where 1 is the most detailed; use 0 to turn logging off)
  • <path> – filename of the log file to fill with the information

The list of the components can be obtained with “trace list” command. Among the useful WebSEAL-related components:

  • pdweb – trace all WebSEAL-related information
  • pdweb.debug – list of HTTP header going trough WebSEAL
  • pdweb.snoop – same, but including message body
  • pdweb.snoop.client – same, but only for data sent between WebSEAL and the web client
  • pdweb.snoop.jct – same, for data sent between WebSEAL and the actual web servers (aka “junctions”)
In the example below you can see how to turn on debugging of the web traffic that goes through WebSEAL. The log will go to “C:\pdweb.debug” file. [ Update (April 2013): How to open the ‘pdadmin’ shell. ]
C:\>pdadmin
pdadmin> login
Enter User ID: sec_master
Enter Password: ********
pdadmin sec_master> server task default-webseald-tameb trace set pdweb.debug 2 file path=C:\pdweb.debug
pdadmin sec_master>

You can read more about “server task trace” in the TAMeb documentation.