1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Copyright (c) 2008 Sun Microsystems Inc. All Rights Reserved
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The contents of this file are subject to the terms
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein of the Common Development and Distribution License
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein (the License). You may not use this file except in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein compliance with the License.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein You can obtain a copy of the License at
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein https://opensso.dev.java.net/public/CDDLv1.0.html or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein See the License for the specific language governing
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein permission and limitations under the License.
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater When distributing Covered Code, include this CDDL
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Header Notice in each file and include the License file
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein If applicable, add the following below the CDDL Header,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein with the fields enclosed by brackets [] replaced by
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews your own identifying information:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein "Portions Copyrighted [year] [name of copyright owner]"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein $Id: README.ssodtool,v 1.3 2008/12/19 00:28:24 ak138937 Exp $
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Portions Copyrighted 2012 ForgeRock Inc
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinOpenAM Diagnostic Tool
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein======================
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThis file contains information about the OpenAM diagnostic tool.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinIt is assumed that OpenAM Server is available.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinTable of contents:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein------------------
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein1. About Diagnostic Tool
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein2. Supported versions of Java Runtime
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein3. Architecture
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updater4. Contents of this package
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater5. Adding new services
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews6. Invoking the diagnostic tool
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein1. About Diagnostic Tool
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein------------------------
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinOpenAM Diagnostic Tool provides a means to validate the sanity of configured
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeininstance and environment. The tool can be used to verify the configuration
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinsettings and identify any possible issues. The issues that can occur after the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinproduct is installed/deployed/configured can be either static or dynamic. Static
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinissues pertain to misconfigurations, while the dynamic issues occur during
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updaterrun-time. The tool does not address the dynamic issues.
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater2. Supported versions of Java Runtime
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater-------------------------------------
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinJava SE 1.5 or higher.
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic UpdaterNote: Embedded quotes in JAVA_HOME environment variable are not supported.
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater3. Architecture
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater---------------
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic UpdaterThis tool can be extended since the implementation is based on a plug-in model.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinProduct/field teams or partners can build custom diagnostic tool services
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein(plug-ins) for new services that can be seamlessly integrated with the existing
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic UpdaterEach feature that is part of the tool and provides certain functionality in a
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updaterdomain, is viewed as a service. For example, a tool that provides OpenAM
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic UpdaterServer configuration related feature is viewed as "Server configuration service"
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updateror in the server domain. A given service can provide one or more related
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updateroperations in a particular functional area. For example, "Server configuration
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinservice" may provide features to view server configuration parameters, validate
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinsession-failover configuration etc.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein4. Contents of this package
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein---------------------------
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic UpdaterThe directory in which the tool is unzipped is referred as ZIP_ROOT.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe directory layout would look something as :
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater |----README (file containing the information about the Tool)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein |----config (Any configuration related files required by the Tool)
1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic Updater |----lib (jar files that are required by the tool to operate)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein |----services (All the services implemented should be under this
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | directory, including service descriptor files
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | i.e. service.xml, jar files, resource files etc)
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | |----resources (Properties file, images etc required by the
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | |----lib (Jar files required by the services)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----sample
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | |----service.xml (Defines the sample service)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----sample_service.xml (Defines the sample service)
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | (This is a sample service used to illustrate the
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | structure of service descriptor file. Any new service
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | can use this file as a reference for integration into
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | the tool. Once a new service is implemented, create a
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | separate directory if the need be and place all the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | related files under this new directory. The tool when
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | started will pick this new service and shall display
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | in the GUI or CLI.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----SampleService.java (Sample source for writing a service)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----service.xml (Defines the service related to server)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----config (Any configuration related files required by the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | server. This is handled by the implementation of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | the service)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----service.xml (Defines the service related to agent(s)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | i.e. Web 3.0 and J2EE 3.0 agents)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----config (Any configuration related files required by the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | agent service. This is handled by the
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | implementation of the service)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----connect
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | |----service.xml (Defines the service related to connectivity
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | of servers. It includes directory server,
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | session failover and site)
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | |----config (Any configuration related files required by the
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | connectivity service. This is handled by the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | implementation of the service)
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | |----tamperdetection
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | |----service.xml (Defines the service related to detecting
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | changes to files of the configured server
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----config (Any configuration related files required by the
98b5a9d1099f72169c90de39712fc4f63e9d990eAutomatic Updater | | tamperdetection service. This is handled by the
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | implementation of the service)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----reports
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----service.xml (Defines the service related to reporting
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----config (Any configuration related files required by the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | reporting service. This is handled by the
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | implementation of the service)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----webcontainer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----service.xml (Defines the service related to web container
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | |----config (Any configuration related files required by the
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater | | web container service. This is handled by the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | implementation of the service)
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews | |----service.xml (Defines the service related to system
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein | | information)
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews5. Adding new services
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein-----------------------
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNew services can be seamlessly added to the Diagnostic Tool. Refer to the sample
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updaterjava code provided under the sample service. The new service can provide
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinadditional functionality as a service or as a feature to an existing service
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updaterdomain. Adding a new service domain or functionality needs to add a new
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updaterdirectory with the domain specific name under the services directory.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAdditionally, the service should provide a service descriptor file providing the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinservice specific details.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinIn order to add a new feature to an existing service domain, the service
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindescriptor file of that service needs to be updated with the corresponding
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater6. Invoking the diagnostic tool
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updater--------------------------------
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinDiagnostic Tool can be invoked in two modes i.e. CLI or GUI. The default
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinbehavior is GUI mode and can be overridden as shown in step 7b and 7c.
2cc6eb92f9443695bc32fa6eed372d983d261a35Automatic Updatera. Invoking the diagnostic tool in GUI mode.
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews %cd <ZIP_ROOT>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein For Unix platforms:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein For Windows platforms:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinb. Invoking the diagnostic tool in CLI mode using the "--console" option.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein %cd <ZIP_ROOT>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews For Unix platforms:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews For Windows platforms:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsc. Invoking the diagnostic tool in CLI mode using the configuration
922312472e2e05ebc64993d465999c5351b83036Automatic Updater The default behavior can be changed to CLI mode by editing the
922312472e2e05ebc64993d465999c5351b83036Automatic Updater configuration file (DTConfig.properties) under
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater <ZIP_ROOT>/config directory.
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater %cd <ZIP_ROOT>/config
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Set the property as follows to override the default GUI mode:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Invoke the tool in CLI mode for Unix platforms:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Invoke the tool in CLI mode for Windows platforms: