PingAM 7.5.0

Start AM

AM is a web application installed in a web container, such as Apache Tomcat. Starting the web container starts the AM application.

At the beginning of its startup process, AM performs an operation called bootstrapping, during which AM obtains startup settings from a bootstrap file in its configuration directory, then uses those settings to initiate its operation. AM creates the bootstrap file, boot.json, during installation.

How is the bootstrap file created?

The installation or upgrade process creates the file after configuring the instance, provided it can find the AM keystore and its password files in either of the following locations:

  • Configure > Server Defaults > Security > Key Store

  • Deployment > Servers > Server Name > Security > Key Store

If possible, change the AM default keystore configuration at the Server Default level so that all servers in your site have the same keystore.

When is the bootstrap file updated?

After every successful startup, AM rewrites the bootstrap file using the current information for the AM keystore.

If you change the configuration of the AM keystore, for example, the path to its files, AM will save the changes to the bootstrap file the next time it starts successfully.

This is why, if you want to override AM’s startup settings, you need to replace the bootstrap file manually before AM starts.

Override startup settings

Users who deploy AM with DevOps tooling, such as Docker and Kubernetes, might want to launch multiple AM instances from a single image, providing startup settings dynamically when AM starts up instead of reading the settings from the bootstrap file created during AM installation.

You can replace the bootstrap file and provide your own static and dynamic startup settings. The following sections describe how to override the bootstrap file created during AM installation:

Replace the bootstrap File

AM’s bootstrap file is located at the path /path/to/openam/config/boot.json, where /path/to/openam is the AM configuration directory.

How is the AM configuration directory specified?

You specify it during AM installation, as follows:

  • In the Configuration Directory field on the Server Settings page when using GUI installation. See Install an instance for details.

  • In the BASE_DIR property in the installation configuration file when using command-line installation. See configurator.jar for more information.

To override AM’s startup configuration, modify the bootstrap file, boot.json, and then overwrite the existing bootstrap file with your modified file before every AM restart.

You must overwrite the file each time you start AM because after startup, AM overwrites the bootstrap file with the initial startup settings created during AM installation, removing any modifications you might have made to startup settings in the bootstrap file.

Make changes to supporting files and passwords before changing bootstrap file properties—AM will fail to start up when bootstrap file properties do not correspond to actual configuration. For example, if you change the value of the keyStorePasswordFile property to a file that does not exist, AM will not be able to start up.

Bootstrap file example, with properties
{
  "instance": "https://openam.example.com:8443/openam",
  "dsameUser": "cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org",
  "keystores": {
    "default": {
      "keyStorePasswordFile": "{amSecretsBase}/default/.storepass",
      "keyPasswordFile": "{amSecretsBase}/default/.keypass",
      "keyStoreType": "JCEKS",
      "keyStoreFile": "{amKeystoreBase}/keystore.jceks"
    }
  },
  "configStoreList": [
    {
      "baseDN": "ou=am-config",
      "dirManagerDN": "uid=am-config,ou=admins,ou=am-config",
      "ldapHost": "opendj.example.com",
      "ldapPort": 1636,
      "ldapProtocol": "ldap"
    }
  ]
}
Startup settings in the bootstrap file
Property Description and Derivation

instance

AM server URL.

Defaults to the Server URL field on the Server Settings page (GUI configurator) or the SERVER_URL configuration property (command-line configurator).

This property’s value is the URL for directly accessing an AM instance, not an AM site using a load balancer URL.

Do not modify this bootstrap file property. If you need to change the AM instance URL, reinstall AM.

dsameUser

An internal account that AM uses to connect to the configuration store. AM generates the password for this account on startup and you can’t read or change it.

The first part of the user’s DN is always created initially as cn=dsameuser,ou=DSAME Users. The second part of the DN defaults to the Root Suffix field on the Configuration Data Store Settings page (GUI configurator) or the ROOT_SUFFIX configuration property (command-line configurator).

keystores.default

The AM keystore. Currently, no other keystores are referenced in the bootstrap file.

keystores.default.keyStorePasswordFile

Path to the file that contains the password required to open the AM keystore. Always created initially as /path/to/openam/security/secrets/default/.storepass.

When creating a new .storepass file, ensure that there are no hidden trailing characters after the password. For example, use the echo -n command to add the password to the new file.

keystores.default.keyPasswordFile

Path to the file that contains the password used to encrypt individual keystore entries. Always created initially as /path/to/openam/security/secrets/default/.keypass.

When creating a new .keypass file, ensure that there are no hidden trailing characters after the password. For example, use the echo -n command to add the password to the new file.

keystores.default.keyStoreType

AM key store type. Currently, the only valid value is JCEKS.

keystores.default.keyStoreFile

Path to the AM keystore. Always created initially as /path/to/openam/security/keystores/keystore.jceks.

The AM keystore is required for startup because it contains the password of the directory manager user of the AM configuration store.

configStoreList[*]

Array of one or more objects that describe AM configuration stores. The initial object in the array is mandatory and defines the primary configuration store. Additional objects are optional and define failover configuration stores.

configStoreList[*].baseDN

Root suffix of the AM configuration store.

Defaults to the Root Suffix field on the Configuration Data Store Settings page (GUI configurator) or the ROOT_SUFFIX configuration property (command-line configurator).

configStoreList[*].dirManagerDN

DN of the configuration store directory manager user.

Defaults to uid=admin (GUI configurator) or the DS_DIRMGRDN configuration property (command-line configurator).

configStoreList[*].ldapHost

fully qualified domain name (FQDN) of the configuration store’s host.

Defaults to the Host Name field on the Configuration Data Store Settings page (GUI configurator) or the DIRECTORY_SERVER configuration property (command-line configurator).

configStoreList[*].ldapPort

LDAP or LDAPS port number on which to access the configuration store.

Defaults to the Port field on the Configuration Data Store Settings page (GUI configurator) or the DIRECTORY_PORT configuration property (command-line configurator).

configStoreList[*].ldapProtocol

Protocol with which to access the directory service running the configuration store. The value can be ldap or ldaps.

Defaults to the SSL/TLS Enabled field on the Configuration Data Store Settings page (GUI configurator) or the DIRECTORY_SSL configuration property (command-line configurator).

Override startup settings using environment variables

You can dynamically override startup settings in the bootstrap file by defining environment variables in the shell that starts AM and referencing the variables in a modified version of the bootstrap file.

Specify JSON properties that reference environment variables in a modified bootstrap file that uses the notation ${env.MY_ENVIRONMENT_VARIABLE}.

For example, you could dynamically change the AM instance URL as follows:

  1. Set an environment variable named MY_INSTANCE in the shell that starts AM.

  2. Create a modified version of the bootstrap file with the following line:

    "instance" : "${env.MY_INSTANCE}",
  3. Overwrite the initial bootstrap file with the modified bootstrap file.

  4. Start AM.

Override startup settings using Java properties

You can dynamically override startup settings in the bootstrap file by referencing Java system properties in a modified version of the bootstrap file. You can reference both built-in Java system properties and properties specified with the -D option in the web container that runs AM.

Specify JSON properties that reference Java properties in a modified bootstrap file that uses the notation ${MY_JAVA_PROPERTY}.

For example, you could dynamically change the AM keystore’s path to the user’s home directory as follows:

  1. Create a modified version of the bootstrap file, specifying the default AM keystore as follows:

    "keystores" : {
        "default" : {
           "keyStorePasswordFile" : "/home/jenkins/.storepass",
           "keyPasswordFile" : "/home/jenkins/.keypass",
           "keyStoreType" : "JCEKS",
           "keyStoreFile" : "/home/jenkins/keystore.jceks"
        }
    },
  2. Overwrite the initial bootstrap file with the modified bootstrap file.

  3. Start AM.