Previous Topic: Log File DescriptionsNext Topic: Error Messages


Publishing Diagnostic Information

This section contains the following topics:

Diagnostic Information Overview

Use the Command Line Interface

Published Data

Diagnostic Information Overview

The Policy Server includes a command line tool for publishing diagnostic information about a SiteMinder deployment. Using the tool, you can publish information about Policy Servers, policy stores, user directories, Agents, and custom modules.

Use the Command Line Interface

The Policy Server includes a command that can be executed at the command line to publish information. The command is located in the installation_dir/siteminder/bin directory.

To publish information, use smpolicysrv command, followed by the -publish switch. For example:

smpolicysrv -publish <optional file_name>

Note: On Windows systems, do not run the smpolicysrv command from a remote desktop or Terminal Services window. The smpolicysrv command depends on inter-process communications that do not work if you run the smpolicysrv process from a remote desktop or Terminal Services window.

Important! Before running a SiteMinder utility or executable on Windows Server 2008, open the command line window with administrator permissions. Open the command line window this way, even if your account has administrator privileges.

Specify a Location for Published Information

Published information is written in XML format to a specified file. The specified file name is saved in the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Netegrity\SiteMinder\CurrentVersion\
Publish

This key is located in the system registry on Windows systems, and in the install_dir/registry/sm.registry file on UNIX. The default value of the registry setting is:

policy_server_install_dir>\log\smpublish.xml

If you execute smpolicysrv -publish from a command line, and you do not supply a path and file name, the value of the registry setting determines the location of the published XML file.

Note: On Windows systems, do not run the smpolicysrv command from a remote desktop or Terminal Services window. The smpolicysrv command depends on inter-process communications that do not work if you run the smpolicysrv process from a remote desktop or Terminal Services window.

Important! Before running a SiteMinder utility or executable on Windows Server 2008, open the command line window with administrator permissions. Open the command line window this way, even if your account has administrator privileges.

To specify a location and generate output in an XML file

  1. From a command line, navigate to:
    installation_dir/siteminder/bin
    
  2. Type the following command:
    smpolicysrv -publish path_and_file_name
    

    For example, on Windows:

    smpolicysrv -publish c:\netegrity\siteminder\published-data.txt
    

    For example, on UNIX:

    smpolicysrv -publish /netegrity/siteminder/published-data.txt
    

    The Policy Server generates XML output in the specified location and updates the value of the HKEY_LOCAL_MACHINE\SOFTWARE\Netegrity\
    SiteMinder\CurrentVersion\Publish registry key to match the location you specified.

Published Data

This section outlines the information that may be published for the following:

Published Policy Server Information

The Policy Server information includes the server name, platform, configuration, and server versions information. In addition, any registry settings used to configure the Policy Server may be published.

Published Policy Server information includes:

Published Policy Server XML Output Format

The following example shows how Policy Server information is formatted:

   <SERVER>
        < SHORT_NAME>   smpolicysrv </SHORT_NAME>
        <FULL_NAME>    SiteMinder Policy Server </FULL_NAME>
        <PRODUCT_NAME> SiteMinder(tm) </PRODUCT_NAME>
        <VERSION>  6.0 </VERSION>
        <UPDATE>   01 </UPDATE>
        <LABEL>    283 </LABEL>
        <PLATFORM> Windows (Build 3790)
       </PLATFORM>
        <SERVER_PORT>     44442 </SERVER_PORT>
        <RADIUS_PORT> 0 </RADIUS_PORT>
        <THREADPOOL>
            <MSG_TOTALS>    15011 </MSG_TOTALS>
            <MSG_DEPTH>     2 </MSG_DEPTH>
            <THREADS_LIMIT> 8 </THREADS_LIMIT>
            <THREADS_MAX>   3 </THREADS_MAX>
            <THREADS_CURRENT> 3 </THREADS_CURRENT>
        </THREADPOOL>
        <CRYPTO> 128 </CRYPTO>
        <KEYMGT>
            <GENERATION> enabled </GENERATION>
            <UPDATE>     disabled </UPDATE>
        </KEYMGT>
        <JOURNAL>
            <REFRESH> 60 </REFRESH>
            <FLUSH>   60 </FLUSH>
        </JOURNAL>
        <PSCACHE>
            <STATE>          enabled </STATE>
            <PRELOAD>        enabled </PRELOAD>
        </PSCACHE>
        <USERAZCACHE>
            <STATE>    enabled </STATE>
            <MAX>      10 </MAX>
            <LIFETIME> 3600 </LIFETIME>
        </USERAZCACHE>
   </SERVER>

The following table defines the Policy Server information that is published.

TAG

Contains

Description

Parent Tag

Required

SERVER

Elements

Denotes server information

SMPUBLSIH

Required

SHORT_NAME

Text

Abbreviated name of the server

SERVER

Required

FULL_NAME

Text

Full name of the running
server

SERVER

Required

PRODUCT_NAME

Text

Name of the Product

SERVER

Required

VERSION

Text

Version of the server

SERVER

Required

UPDATE

Text

Service Pack version

SERVER

Required

LABEL

Text

Build or CR number

SERVER

Required

PLATFORM

Text

OS platform identifying data

SERVER

Required

THREAD_POOL

Elements

Information about the thread
pool

SERVER

Required

MSG_TOTAL

Int

Number of thread pool
messages handled

THREAD_POOL

Required

MSG_DEPTH

Int

Max number of messages in thread pool

THREAD_POOL

Required

THREADS_LIMIT

Int

Ceiling on number of threads

THREAD_POOL

Required

THREADS_MAX

Int

Max number of threads used

THREAD_POOL

Required

THREADS_CURRENT

Int

Current number of threads
used

THREAD_POOL

Required

PSCACHE

Elements

Denotes information on policy server cache settings

SERVER

Required

PRELOAD

Text

Indicates if enabled/disabled

PSCACHE

Required

JOURNAL

Empty,

Indicates the journaling settings, refresh rate and time values to flush

SERVER

Required

FLUSH

Int

Value at which to flush

JOURNAL

Required

REFRESH

Int

Refresh rate

JOURNAL

Required

KEYMGT

Empty,

Indicates Key Management settings

(Generation: if automatic key generations is enable)

(Update: if automatic updating
of agent keys is done.)

SERVER

Required

GENERATION

Enabled or disabled

Enabled or disabled indicates
the automatic key generation
is enabled

KEYMGT

Required

UPDATE

Enabled or disabled

Indicates that automatic
update of agent keys is
enabled

KEYMGT

Required

USERAZCACHE

Elements

Information about the User AZ cache settings

SERVER

Required

MAX

Int

Maximum number of cache entries

USERAZCACHE

Required

LIFETIME

int

Life time of cached object

USERAZCACHE

Required

PORT

Int

Port Number

SERVER

Required

RADIUS_PORT

Int

Radius Port number
(if enabled)

SERVER

Required

STATE

text, enabled or disabled

Indicates if something is
enabled or disabled

Many tags

Various

Published Object Store Information

The Policy Server can store information in the following types of object stores:

Published object store information includes the type of object store that is being used, back–end database information, configuration, and connection information.

Published Policy/Key Store XML Output Format

The following example shows how policy/key store information is formatted:

<POLICY_STORE>

   <DATASTORE>
      <NAME> Policy Store   </NAME>
      <USE_DEFAULT_STORE>  false </USE_DEFAULT_STORE>
      <LOADED> true </LOADED>
      <SERVER_LIST>
         <CONNECTION_INFO>
            <TYPE> ODBC</TYPE>
            <SERVICE_NAME> sm </SERVICE_NAME>
            <USER_NAME> sa </USER_NAME>
            <DBMS_NAME> Microsoft SQL Server </DBMS_NAME>
            <DRIVER_NAME> Microsoft SQL Server </DRIVER_NAME>
            <DBMS_VERSION> 08.00.0760 </DBMS_VERSION>
         </CONNECTION_INFO>
     </SERVER_LIST>
   </DATASTORE>

   <DATASTORE>
      <NAME>  Key Store </NAME>
      <USE_DEFAULT_STORE> true </USE_DEFAULT_STORE>
      <LOADED> true </LOADED>
   </DATASTORE>

   <DATASTORE>
      <NAME> Audit Log Store </NAME>
      <USE_DEFAULT_STORE> true </USE_DEFAULT_STORE>
      <LOADED> true </LOADED>
   </DATASTORE>

   <DATASTORE>
      <NAME> Session Server Store </NAME>
      <USE_DEFAULT_STORE>  false </USE_DEFAULT_STORE>
      <LOADED> false </LOADED>
   </DATASTORE>

</POLICY_STORE>

The following table defines the policy/key store information that is published.

TAG

Contains

Description

Parent Tag

Required

POLICY_STORE

Elements

Denotes all the Data Store information

SMPUBLISH

Required

DATASTORE

Elements

 

Denotes information about a particular Object Store.

  • Type is the type of data store.
  • Use defaults indicates if default objectstore is being used for that type.
  • Loaded indicates if that type is loaded.

POLICY_STORE

Required

NAME

Text

Name/Type of Data Store

DATASTORE

Required

USE_DEFAULT_STORE

Text

Indicates (True/false) if storage
is within the default
‘Policy Store’

DATASTORE

Required

LOADED

Text

Indicates (true/false) if the data store has been loaded and
initialized

DATASTORE

Required

TYPE

Text

Type of policy store, that is, ODBC/LDAP

DATASTORE

Required

SERVER_
LIST

Elements

List of fail over servers used for data store (ODBC)

DATASTORE

Optional

CONNECTION_INFO

Elements

Type of Server Connection

SERVER_LIST

Optional

DRIVER_NAME

Text

Name of the ODBC driver name

CONNECTION

Optional

IP

Text

IP address

DATASTORE

Optional

LDAP_VERSION

Text

LDAP version

DATASTORE

Optional

API_VERSION

Text

LDAP API version

DATASTORE

Optional

PROTOCOL_VERSION

Text

LDAP protocol version

DATASTORE

Optional

API_VENDOR

Text

API Vendor

DATASTORE

Optional

VENDOR_VERSION

Text

Vendor version

DATASTORE

Optional

Published User Directory Information

For each user directory that has been loaded and accessed by the Policy Server, the following information can be published:

Published User Directory XML Output Format

The user directory information will be formatted like the following example:

Note: The published information will vary depending on the type of user directory.

< USER_DIRECTORIES>

   <DIRECTORY_STORE >
      <TYPE> ODBC </TYPE>
      <NAME> sql5.5sample </NAME>
      <MAX_CONNECTIONS> 15 </MAX_CONNECTIONS>
         <SERVER_LIST>
            <CONNECTION_INFO>
               <TYPE> ODBC</TYPE>
               <SERVICE_NAME> sql5.5sample </SERVICE_NAME>
               <USER_NAME> sa </USER_NAME>
               <DBMS_NAME> Microsoft SQL Server </DBMS_NAME>
               <DRIVER_NAME> Microsoft SQL Server </DRIVER_NAME>
               <DBMS_VERSION> 08.00.0760 </DBMS_VERSION>
            </CONNECTION_INFO>
         </SERVER_LIST>
   </DIRECTORY_STORE >
   <DIRECTORY_STORE>
      <TYPE> LDAP:  </TYPE>
      <NAME> LDAPsample </NAME>
      <FAILOVER_LIST> 172.26.14.101:12002 </FAILOVER_LIST>
      <VENDOR_NAME> Netscape-Directory/4.12 B00.193.0237
      </VENDOR_NAME>
      <SECURE_CONNECTION> disabled </SECURE_CONNECTION>
      <CREDENTIALS>       required </CREDENTIALS>
      <CONNECTION_INFO>
         <PORT_NUMBER> 12002 </PORT_NUMBER>
         <DIR_CONNECTION> 172.26.14.101:12002 </DIR_CONNECTION>
         <USER_CONNECTION> 172.26.14.101:12002 </USER_CONNECTION>
      </CONNECTION_INFO>
      <LDAP_VERSION>     1 </LDAP_VERSION>
      <API_VERSION>      2005 </API_VERSION>
      <PROTOCOL_VERSION> 3 </PROTOCOL_VERSION>
      <API_VENDOR>       mozilla.org </API_VENDOR>
      <VENDOR_VERSION>   500 </VENDOR_VERSION>
   </DIRECTORY_STORE>
</USER_DIRECTORIES>

The following table defines the user directory information that will be published.

TAG

Contains

Description

Parent Tag

Required

USER_DIRECTORIES

Elements

Denotes a collection of loaded directory stores

SMPUBLISH

Required

DIRECTORY_STORE

Elements

Denotes a particular directory store.

USER_DIRECTORIES

Optional

TYPE

Text

Type of Directory Store

DIRECTORY_STORE

Required

NAME

Text

Defined name of the Directory store

DIRECTORY_STORE

Required

MAX_CONNECTIONS

Int

Maximum number of connections defined

DIRECTORY_STORE

Optional

SERVER_LIST

Elements

Collection of servers
(ODBC)

DIRECTORY_STORE

Optional

FAILOVER_LIST

Text

 

 

 

Published Agent Information

Published Agent information lists the agents currently connected to policy server, including their IP address and name.

Published Agent XML Output Format

The Agent information will be formatted as in the following example:

< AGENT_CONNECTION_MANAGER>
   <CURRENT>      4 </CURRENT>
   <MAX>          4 </MAX>
   <DROPPED>      0 </DROPPED>
   <IDLE_TIMEOUT> 0 </IDLE_TIMEOUT>
   <ACCEPT_TIMEOUT> 10 </ACCEPT_TIMEOUT>

   <AGENT_CONNECTION>
      <NAME> agent1 </NAME>
      <IP>   172.26.6.43 </IP>
      <API_VERSION> 1024 </API_VERSION>
      <LAST_MESSAGE_TIME> 0x05705E0C </LAST_MESSAGE_TIME>
   </AGENT_CONNECTION>
   <AGENT_CONNECTION>
      <NAME> agent1 </NAME>
      <IP>   172.26.6.43 </IP>
      <API_VERSION> 1024 </API_VERSION>
      <LAST_MESSAGE_TIME> 0x05705E0C </LAST_MESSAGE_TIME>
   </AGENT_CONNECTION>
   <AGENT_CONNECTION>
      <NAME> agent1 </NAME>
      <IP>   172.26.6.43 </IP>
      <API_VERSION> 1024 </API_VERSION>
      <LAST_MESSAGE_TIME> 0x05705E0C </LAST_MESSAGE_TIME>
   </AGENT_CONNECTION>
   <AGENT_CONNECTION>
      <NAME> 940c0728-d405-489c-9a0e-b2f831f78c56 </NAME>
      <IP>   172.26.6.43 </IP>
      <API_VERSION> 1482282902 </API_VERSION>
      <LAST_MESSAGE_TIME> 0x05705E0C </LAST_MESSAGE_TIME>
   </AGENT_CONNECTION>
</AGENT_CONNECTION_MANAGER>

Note: The Agent connections information is contained within the <AGENT_CONNECTION_MANAGER>tag.

The following table defines the Agent information that will be published.

TAG

Contains

Description

Parent Tag

Required

AGENT_CONNECTION-_MANAGER

Elements

Defines data for the agent connections

SM_PUBLISH

Required

CURRENT

Int

Number of current connections

AGENT_CONNECTION-_MANAGER

Required

MAX

Int

Maximum number of connections

AGENT_CONNECTION-_MANAGER

Required

DROPPED

Int

Maximum number of connections

AGENT_CONNECTION-_MANAGER

Required

IDLE_TIMEOUT

Int

Time after which an idle connection is timed out.

AGENT_CONNECTION-_MANAGER

Required

ACCEPT_TIMEOUT

Int

Time after which an
attempted connection is timed out

AGENT_CONNECTION-_MANAGER

Required

AGENT_CONNECTION

Elements

Denotes data about an active agent connection

AGENT_CONNECTION-_MANAGER

Optional

IP

Text

IP address of agent

AGENT_CONNECTION

Required

API_VERSION

Int

Version of the API used
by the connected agent

AGENT_CONNECTION

Required

NAME

Text

Name of the agent

AGENT_CONNECTION

Required

LAST_MESSAGE_TIME

Int

Time since last message from agent

AGENT_CONNECTION

Required

AGENT_CONNECTION-_MANAGER

Elements

Defines data for the agent connections

SM_PUBLISH

Required

Published Custom Modules Information

Custom modules are DLLs or libraries that can be create to extend functionality of an existing Policy Server. These come in several types: event handlers, authentication modules, authorization modules, directory modules, and tunneling modules. Authentication modules are generally referred to as custom Authentication schemes and the Authorization modules are known as Active Policies. Tunnel modules are used to define a secure communication with an Agent. Event modules provide a mechanism for receiving event notifications. Information about which custom modules have been loaded by a Policy Server can be published. Each type of custom module is defined in its own XML Tag

Published Custom Modules XML Output Format

The following table defines the custom module information that will be published.

TAG

Contains

Description

Parent Tag

Required

EVENT_LIB

Elements

Indicates data about Event API custom Modules

SMPUBLISH

Optional

AUTH_LIB

Elements

Indicates data about Authentication API custom Modules

SMPUBLISH

Optional

DS_LIB

Elements

Indicates data about Directory API custom Modules

SMPUBLISH

Optional

TUNNEL_LIB

Elements

Indicates data about Tunnel API custom Modules

SMPUBLISH

Optional

AZ_LIB

Elements

Indicates data about Authorization API custom Modules

SMPUBLISH

Optional

There following are common to every type of custom module:

TAG

Contains

Description

Parent Tag

Required

FULL_NAME

Text

Full name of library or DLL include path.

 

Required

CUSTOM_INFO

Text

Information provided by the custom library.

 

Optional

LIB_NAME

Text

Library or DLL name

 

Optional

VERSION

Int

Version of the API supported

 

Optional

The following are specific to certain types of modules:

TAG

Contains

Description

API Type

Required

ACTIVE_FUNCTION

Text

Name of function loaded to
be callable as an active expression

Authorization API

Optional