Diagnostics

Author: Anant Kadam (Anant.Kadam@sun.com)

Table of Contents

About Diagnostic Tool

Architecture

Contents of this package

Invoking the diagnostic tool

Diagnostic tool features

Compilation of the sample code

Adding new services

About Diagnostic Tool

OpenSSO Diagnostic Tool provides a means to validate the sanity of configured instance and environment. The tool can be used to verify the configuration settings and identify any possible issues. The issues that can occur after the product is installed/deployed/configured can be either static or dynamic. Static issues pertain to misconfigurations, while the dynamic issues occur during run-time. The tool does not address the dynamic issues.

Architecture

This tool can be extended since the implementation is based on a plug-in model. Product/field teams or partners can build custom diagnostic tool services (plug-ins) for new services that can be seamlessly integrated with the existing services.

Each feature that is part of the tool and provides certain functionality in a domain, is viewed as a service. For example, a tool that provides OpenSSO Server configuration related feature is viewed as "Server configuration service" or in the server domain. A given service can provide one or more related operations in a particular functional area. For example, "Server configuration service" may provide features to view server configuration parameters, validate session-failover configuration etc.

Contents of this package

OpenSSO diagnostic is delivered as part of opensso.zip file. The directory in which the tool is unzipped is referred as ZIP_ROOT.

The directory layout would look something as :

    <ZIP_ROOT>
      |
      |----README (file containing the information about the Tool)
      |
      |----license.txt
      |
      |----ssodtool.sh
      |
      |----ssodtool.bat
      |
      |----config (Any configuration related files required by the Tool)
      |
      |---lib (jar files that are required by the tool to operate)
      |
      |----services (All the services implemented should be under this
      |       |       directory, including service descriptor files i.e. service.xml, jar files, resource files etc)
      |       |
      |       |----resources (Properties file, images etc required by the services)
      |       |
      |       |----lib (Jar files required by the services)
      |       |
      |       |----sample
      |       |       |
      |       |       |---- sample_service.xml (Defines the sample service)
      |       |       (This is a sample service used to illustrate the structure of service descriptor file. Any new service can use this file as a reference for integration into the tool.
      |       |        Once a new service is implemented, create a separate directory if the need be and place all the related files under this new directory. The tool when started
      |       |        will pick this new service and shall display in the GUI or CLI.
      |       |       |
      |       |       |---- SampleService.java (Sample source for writing a service)
      |       |
      |       |----server
      |       |       |---- service.xml (Defines the service related to server)
      |       |       |---- config (Any configuration related files required by the server. This is handled by the implementation of the service)
      |       |
      |       |----agent
      |       |       |---- service.xml (Defines the service related to agent(s) i.e. Web 3.0 and J2EE 3.0 agents)
      |       |       |---- config (Any configuration related files required by the agent service. This is handled by the implementation of the service)
      |       |
      |       |----connect
      |       |       |---- service.xml (Defines the service related to connectivity of servers. It includes directory server, session failover and site)
      |       |       |---- config (Any configuration related files required by the connectivity service. This is handled by the implementation of the service)
      |       |
      |       |----tamperdetection
      |       |       |---- service.xml (Defines the service related to detecting changes to files on file-system of the configured server instance)
      |       |       |---- config (Any configuration related files required by the tamperdetection service. This is handled by the implementation of the service)
      |       |
      |       |----reports
      |       |       |---- service.xml (Defines the service related to reporting service)
      |       |       |---- config (Any configuration related files required by the reporting service. This is handled by the implementation of the service)
      |       |
      |       |----webcontainer
      |       |       |---- service.xml (Defines the service related to webcontainer service.)
      |       |       |---- config (Any configuration related files required by the webcontainer service. This is handled by the implementation of the service)
      |       |
      |       |----system
      |       |       |---- service.xml (Defines the service related to system information)

Invoking the diagnostic tool

Diagnostic Tool can be invoked in two modes i.e. CLI or GUI. The default behavior is GUI mode and can be overridden as shown in step b and c.

a. Invoking the diagnostic tool in GUI mode.
   %cd <ZIP_ROOT>

   For Unix platforms:
   >ssodtool.sh

   For Windows platforms:
   >ssodtool.bat

b. Invoking the diagnostic tool in CLI mode using the "--console" option.
   %cd <ZIP_ROOT>

   For Unix platforms:
   >ssodtool.sh --console

   For Windows platforms:
   >ssodtool.bat --console

c. Invoking the diagnostic tool in CLI mode using the configuration
   property.

   The default behavior can be changed to CLI mode by editing the
   configuration file (DTConfig.properties) under
   <ZIP_ROOT>/config directory.

   %cd <ZIP_ROOT>/config

   Set the property as follows to override the default GUI mode:
   odt.application.runmode=CLI

   Invoke the tool in CLI mode for Unix platforms:
   >ssodtool.sh

   Invoke the tool in CLI mode for Windows platforms:
   >ssodtool.bat |

Diagnostic tool features

This section briefly describes the features of Diagnostic Tool. This is the first version of the tool, hence does not cover all the aspects of the product.

The features are divided into specific categories based on the scope of the domain i.e. any functionality related to server is addressed under the "server" category. Features are explained using the GUI mode as a reference.

Once the tool in invoked in the GUI mode, you will see a window as seen below:

The following are the details of the tests along with a brief description that are performed under each category:

• Server

This category handles the configuration settings related to the server. The only input required for running the tests under this category is Configuration Directory path. This configuration directory path corresponds to the configuration path location where the bootstrap file of the OpenSSO configured instance resides.

** Server ConfigurationThe tool reads the bootstrap file and detects if the configured server instance can be accessed. It then checks for the connectivity to the configuration store with the credentials in the bootstrap file. Once the configuration store is successfully accessed, it retrieves and validates the configuration properties as follows:
             - detect all the global changed properties
             - detect changed properties per instance
             - validate some of the changed properties i.e. persistence, encryption keys etc.

** SAML ConfigurationThe scope of SAML configuration values is limited to the following properties. In future, it will be extended to address more scenarios.
             - Keystore File
             - Keystore Password File
             - Private Key Password File
             - Certificate Alias

** Session FailoverThis component validates if OpenSSO server is configured for Session Failover. It checks for the session failover related properties and additionally makes a connection attempt to the backend message queue servers.

** Site Configuration
Site configuration validates if site is configured and contains valid entries under "Servers and Sites" settings of OpenSSO server. It also checks for corresponding site entry under the Realm/DNS Alias.

• Tamper-Detection

This category handles detecting any changes made to the OpenSSO server configuration settings and the deployed OpenSSO server bits on the file-system. The input required for running the tests under this category is Configuration Directory path for OpenSSO server configuration and Web Container Directory path where the OpenSSO server bits are deployed respectively. For OpenSSO server configuration, the configuration directory path corresponds to the configuration path location where the bootstrap file of the OpenSSO configured instance resides. For OpenSSO server deployed bits, the path is to the Web container instance where the OpenSSO server bits are laid out.

          This is a two step process:

             a> Creating a snapshot of the OpenSSO server configuration files or the deployed bits on the file-system
             b> Detecting any changes made since the snapshot was taken and stored

** Create ChecksumThis is the first step required to create a check-sum in order to detect any subsequent changes made. Distinct files containing the check-sums are created and stored locally inside the tool file hierarchy. If tamper detection is required for OpenSSO configuration and OpenSSO server deployed bits, then this test needs to be run twice by providing the required paths.

For OpenSSO configuration settings, the tool reads the configuration directory entries and creates a check-sum file. The directories under the configuration directory path that needs to be skipped is configurable.

For OpenSSO server deployed bits, the tool reads the directory entries under the deployed instance and creates a check-sum file.

** Detect TamperOnce a snapshot of the files under configuration directory or the deployed instance is created using Create Checksum, this test will determine and report any changes made to the OpenSSO configuration files or OpenSSO deployed bits on the file-system. Only one test can be run at a given time i.e. to detect changes in OpenSSO configuration or OpenSSO deployed bits.

The following considerations should be taken when running this test case for enhanced security:

           o As a general guideline, the Create Checksum test should be run once the system is properly configured and functional. All the subsequent Detect Tamper tests should be run after any configuration related changes have been made.
           o The tamper detection component relies on the security permissions offered by the Operating System to protect the file containing the checksum. This file can be copied over to a more secure location if higher degree of security is desired.
           o As a security precaution, this test should be run by authorized personal to safegaurd the contents of the checksum files.

• System

This category reports the system details of the host machine on which the tool is running. No input parameter is required to run this test.

** System Configuration
Current implementation displays system information for the following operating systems:
             o Solaris
             o Linux
             o Windows

• Connectivity

This category deals with the connections of different configuration related host machines. The only input required for running the tests under this category is Configuration Directory path. This configuration directory path corresponds to the configuration path location where the bootstrap file of the OpenSSO configured instance resides.

** Message QueueIf the session failover is enabled for the OpenSSO server, then this test would make an attempt to validate and connect to back-end message queue servers.

** DirectoryAll the directory server host related connections are attempted in this test.

** Server and SiteAll the URL's under "Servers and Sites" settings of OpenSSO configured instance are verified for connectivity. Additionally when a site is configured, the site URL is also verified for connectivity.

• Web-Container

This category deals with the container related configurations as required by OpenSSO server instance. There are two inputs required for running the tests under this category. The input values will vary based on the Container Type chosen. The following lists the implemented container type's and the required values:

             Container Type: Sun Application Server
             Container Base Directory: (i.e. /opt/glassfish)
             Container Domain Directory: (i.e. /opt/glassfish/domains/domain1)

             Container Type: Sun Web Server
             Container Base Directory: (i.e. /opt/sun/WebServer7)
             Container Domain Directory: (i.e. /opt/sun/WebServer7/https-host.domain.com)

             Container Type: BEA WebLogic
             Container Instance Directory: (i.e. /opt/bea/wlserver_10.0)
             Container Domain Directory: (i.e. /opt/bea/wlserver_10.0/ samples/domains/wl_server)

             Container Type: IBM WebSphere
             Container Profile Directory: (i.e. /opt/IBM/WebSphere/AppServer/profiles/AppSrv01)
             Container Server Directory: (i.e. /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/hostNameNode01Cell/nodes/hostNameNode01/servers/server1)

Useful Information The input value for "Configuration Directory" is not required to run this test

** JVM VersionThis test indicates the version of JVM version used by the container with an exception of BEA Weblogic. For BEA WebLogic, the version of JVM can be determined only at runtime and is indicated as such by the tool.

** Policy FileOpenSSO web application needs to be granted certain permissions when deployed on a container of choice. This test determines if the required permissions are granted to OpenSSO web application. This test is independent of Security Manager being turned on or off.

** JVM SettingsSome JVM options are required based on the Container Type for OpenSSO server to function properly. This test determines if the required JVM options are set which can be either in the container's configuration file or command-line script.

Note Web-Container configuration checking in diagnostic tools will not exclude comments. It means if the required directives are in the configuration files but have been commented out, diagnostic tools will still assume the directives as valid. It is the responsibility of the end-user to make sure the directives are not within any comments in the configuration file.

• Agents

This category deals with the Agent (Web and J2EE) related configurations. Agents can be deployed as either remote or centralized. This tool works against agent configured in centralized mode. The input required for running the tests under this category is the location of configuration directory on Agent host machine. The value for Configuration Directory will vary based on the type of Agent (Web or J2EE).

** J2EE agentThe test reads the J2EE agent bootstrap file under the value specified for Configuration Directory. It does a sanity check on the following:

             - Naming URL syntax
             - OpenSSO server hostname
             - OpenSSO sever connection
             - Naming URL connection
             - Authenticate to OpenSSO server based on credentials specified in bootstrap file
             - Retrieves and displays the J2EE agent configuration properties
             - checks if CDSSO is enabled

** Web agentThe test reads the Web agent bootstrap file under the value specified for Configuration Directory. It does a sanity check on the following:

             - Naming URL syntax
             - OpenSSO server hostname
             - OpenSSO sever connection
             - Naming URL connection
             - Authenticate to OpenSSO server based on credentials specified in bootstrap file
             - Retrieves and displays the Web agent configuration properties
             - checks if CDSSO is enabled

• Reports

This category does the reporting of configuration properties for OpenSSO server, Web Agent and J2EE agent. It also displays the content of the server key store. The input required for running the tests under this category depends on the type of test selected. For Servert Report and KeyStore Report, the value of Configuration Directory should be the location of the OpenSSO server configuration directory. For J2EE Agent Report and Web Agent Report the value should be the location of the configuration directory on the Agent host machine respectively.

** Server ReportThe test runs against the configured OpenSSO server instance. The tool reads the OpenSSO server bootstrap file under the value specified for Configuration Directory and displays the server properties stored in the configuration store. Additionally, it displays the JVM properties of the JDK being used.

** KeyStore ReportThe test runs against the configured OpenSSO server instance. The tool reads the OpenSSO server bootstrap file under the value specified for Configuration Directory. It reads the server properties stored in the configuration store and displays the contents of Key Store based on the server configured values.

** J2EE Agent ReportThe test runs against the configured J2EE agent instance. The tool reads the J2EE Agent bootstrap file under the value specified for Configuration Directory. It reads the agent properties stored in the configuration store and displays the contents.

** Web Agent ReportThe test runs against the configured Web agent instance. The tool reads the Web Agent bootstrap file under the value specified for Configuration Directory. It reads the agent properties stored in the configuration store and displays the contents.

Compilation of the sample code

The sample java source code under <ZIP_ROOT>/services/sample can be compiled as follows:

Adding new services

New services can be seamlessly added to the Diagnostic Tool. Refer to the sample java code provided under the sample service. The new service can provide additional functionality as a service or as a feature to an existing service domain. Adding a new service domain or functionality needs to add a new directory with the domain specific name under the services directory. Additionally, the service should provide a service descriptor file providing the service specific details.

In order to add a new feature to an existing service domain, the service descriptor file of that service needs to be updated with the corresponding entry.