h1. [Diagnostics|TOC for Diagnostics]
h6. Author: Anant Kadam ([mailto:Anant.Kadam@sun.com])
h1. Table of Contents
h5. [#About Diagnostic Tool]
h5. [#Architecture]
h5. [#Contents of this package]
h5. [#Invoking the diagnostic tool]
h5. [#Diagnostic tool features]
h5. [#Compilation of the sample code]
h5. [#Adding new services]
h6. About Diagnostic Tool {anchor: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.
h6. Architecture {anchor: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.
h6. Contents of this package {anchor: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)
h6. Invoking the diagnostic tool {anchor: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.
{noformat}
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 |
{noformat}
h6. Diagnostic tool features {anchor: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:
!DiagnosticTool.jpg!
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 Configuration{_}The 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 Configuration{_}The 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 Failover{_}This 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 Checksum{_}This 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 Tamper{_}Once 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 Queue{_}If 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.
\*\* _Directory{_}All the directory server host related connections are attempted in this test.
\*\* _Server and Site{_}All 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)
{info:title=Useful Information}
The input value for "Configuration Directory" is not required to run this test
{info}
\*\* _JVM Version{_}This 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 File{_}OpenSSO 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 Settings{_}Some 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:title=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.
{note}
* *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 agent{_}The 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 agent{_}The 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 Report{_}The 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 Report{_}The 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 Report{_}The 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 Report{_}The 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.
h6. Compilation of the sample code {anchor:Compilation of the sample code}
The sample java source code under <ZIP_ROOT>/services/sample can be compiled as follows:
| %<JAVA_HOME>/bin/javac \-classpath .:<ZIP_ROOT>/lib/toolbase.jar SampleService.java |
h6. Adding new services {anchor: 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.
h6. Author: Anant Kadam ([mailto:Anant.Kadam@sun.com])
h1. Table of Contents
h5. [#About Diagnostic Tool]
h5. [#Architecture]
h5. [#Contents of this package]
h5. [#Invoking the diagnostic tool]
h5. [#Diagnostic tool features]
h5. [#Compilation of the sample code]
h5. [#Adding new services]
h6. About Diagnostic Tool {anchor: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.
h6. Architecture {anchor: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.
h6. Contents of this package {anchor: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)
h6. Invoking the diagnostic tool {anchor: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.
{noformat}
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 |
{noformat}
h6. Diagnostic tool features {anchor: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:
!DiagnosticTool.jpg!
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 Configuration{_}The 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 Configuration{_}The 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 Failover{_}This 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 Checksum{_}This 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 Tamper{_}Once 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 Queue{_}If 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.
\*\* _Directory{_}All the directory server host related connections are attempted in this test.
\*\* _Server and Site{_}All 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)
{info:title=Useful Information}
The input value for "Configuration Directory" is not required to run this test
{info}
\*\* _JVM Version{_}This 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 File{_}OpenSSO 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 Settings{_}Some 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:title=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.
{note}
* *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 agent{_}The 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 agent{_}The 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 Report{_}The 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 Report{_}The 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 Report{_}The 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 Report{_}The 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.
h6. Compilation of the sample code {anchor:Compilation of the sample code}
The sample java source code under <ZIP_ROOT>/services/sample can be compiled as follows:
| %<JAVA_HOME>/bin/javac \-classpath .:<ZIP_ROOT>/lib/toolbase.jar SampleService.java |
h6. Adding new services {anchor: 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.