--- title: Set up administration tools description: AM provides a set of administration tools that are now deprecated in favor of Amster. They are part of the AM distributable file. component: pingam version: 8 page_id: pingam:installation:install-openam-admin-tools canonical_url: https://docs.pingidentity.com/pingam/8/installation/install-openam-admin-tools.html keywords: ["Install", "Administration"] page_aliases: ["install-guide:install-openam-admin-tools.adoc"] --- # Set up administration tools AM provides a set of administration tools that are now deprecated in favor of Amster. They are part of the [AM distributable file](download-openam-software.html). The `ssoadm` tool requires access to the AM configuration files and therefore must be installed on the same host as AM. 1. Verify that AM is installed and running before proceeding. 2. Verify that the `JAVA_HOME` environment variable is set properly: ``` $ echo $JAVA_HOME /path/to/jdk ``` 3. Create a file system directory to unpack the tools: ``` $ mkdir -p /path/to/am-tools/admin ``` 4. Unpack the tools: ``` $ cd /path/to/am-tools/admin $ unzip ~/Downloads/am/AM-SSOAdminTools-5.1.3.30.zip ``` 5. Run the `setup` utility (`setup.bat` on Windows) providing the location, password, and type of the truststore containing the public certificate of the DS configuration store. Optionally, include the `--acceptLicense` option if you want to auto-accept the license agreement and suppress the display of the license acceptance page. > **Collapse: How do I create the truststore?** > > Even though you may have other truststores containing the public certificate of the configuration store, you should use a truststore specifically for the `ssoadm` command. > > To create it, follow the steps in [Prepare the truststore](prepare-trust-store.html), but *do not* configure the new truststore in the container. You will configure it in the `ssoadm` command script later. > > If the container where AM runs is configured for secure connections and is using self-signed certificates, import that public certificate into the new truststore, too. For more information, see [To Share Self-Signed Certificates](configure-container-HTTPS.html#share-self-signed-certs). > > | | | > | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | | When using self-signed certificates, for example, in non-production environments, you can configure the `ssoadm` command to trust all server certificates. Learn more in [How do I configure ssoadm to trust all certificates?](https://support.pingidentity.com/s/article/Installing-and-using-ssoadm-in-PingAM#trust) in the *Knowledge Base*. | You will also need to provide the paths to the directories where AM configuration files are located, and where the `ssoadm` debug and log information will be located. For example: ``` $ ./setup --truststore-path /my/ssoadm/truststore --truststore-password changeit \ --truststore-type JKS --acceptLicense Path to config files of OpenAM server [/home/user/am]: Debug Directory [/path/to/am-tools/admin/debug]: Log Directory [/path/to/am-tools/admin/log]: The scripts are properly setup under directory: /path/to/am-tools/admin/am Debug directory is /path/to/am-tools/admin/debug. Log directory is /path/to/am-tools/admin/log. The version of this tools.zip is: version and date The version of your server instance is: ForgeRock Access Management version, Build, and date ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If the `setup` utility cannot connect to the configuration store, it will show a message similar to the following:``` Connect Error: No operational connection factories available ```If you see this message, check that the truststore exists in the specified location, that it contains the configuration store certificate, and that the user running the `setup` utility can change directories to the specified location and open/read the file. | After setup, the tools are located under a directory named after the instance of AM: ``` $ ls am/bin/ ampassword amverifyarchive ssoadm ``` On Windows, these files are `.bat` scripts. 6. Edit the `ssoadm` script and configure the truststore containing the certificate of the configuration store. This truststore may also contain the certificate to connect to AM using SSL, if needed. * In the script, look for the following lines: ```none .... TRUSTSTORE="-Djavax.net.ssl.trustStore=$truststore_path" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStorePassword=$truststore_password" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStoreType=$truststore_type" .... ``` * Add the `truststore_path`, `truststore_password`, and `truststore_type` variables above the lines you found: ```none truststore_path=/my/ssoadm/truststore truststore_password=changeit truststore_type=JKS TRUSTSTORE="-Djavax.net.ssl.trustStore=$truststore_path" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStorePassword=$truststore_password" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStoreType=$truststore_type" .... ``` 7. Check that the `ssoadm` command works properly: * Create a text file, for example `$HOME/.pwd.txt`, containing the AM administrative user's password string in cleartext on a single line. * Make the text file read-only: ``` $ chmod 400 $HOME/.pwd.txt ``` * Run the `ssoadm` command to list the configured servers: ``` $ cd /path/to/am-tools/admin/am/bin/ $ ./ssoadm list-servers --adminid uid=amAdmin,ou=People,dc=am,dc=example,dc=com --password-file $HOME/.pwd.txt https://am.example.com:8443/am ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The value for the `--adminid` parameter is the universal ID of an administrative user.Administrative users are listed in the `com.sun.identity.authentication.super.user` or `com.sun.identity.authentication.special.users` advanced properties, under Configure > Server Defaults > Advanced.The default super-user account is `uid=amAdmin,ou=People,%ROOT_SUFFIX%`. To check your %ROOT\_SUFFIX% value, go to the `/path/to/am/config/boot.json` file, and find the value for the `configStoreList/baseDN` property. | 8. If you have deployed AM in a site configuration, edit the `ssoadm` (`ssoadm.bat` on Windows) script to map the site URL to the AM server URL. To do this, set the `com.iplanet.am.naming.map.site.to.server` system property as a `java` command option in the script. The option takes the following form: ``` -D"com.iplanet.am.naming.map.site.to.server=lb-url=openam-url[,other-lb-url=openam-url…​]" ``` The property maps each *lb-url* key to an *openam-url* value, where *lb-url* is the URL to a site load balancer, and *openam-url* is the URL to the AM server against which you set up the `ssoadm` command. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `ssoadm` command is dependent on the AM server against which you set it up, so always map site load balancer URLs to that server's *openam-url*.For example, if your site is behind `https://lb.example.com:443/am`, and the AM server against which you set up the `ssoadm` command is at `https://am.example.com:8443/am`, then add the following property to the `java` command (all on one line without spaces):```none -D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/am=https://am.example.com/am" ``` | Repeat this step for each AM server in your site configuration. You can install all your instances of `ssoadm` on the same host, but in each case the command should manage only one AM server.