Starting Instances

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

ForgeRock recommends changing the AM default keystore configuration at Server Default level, so that the environment is homogeneous.

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.

Overriding Startup Settings

Users who deploy AM with DevOps tooling—for example, 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:

"Replacing the Bootstrap File" covers how to specify a custom bootstrap file, and describes all the startup settings in the bootstrap file.
"Overriding Startup Settings by Using Environment Variables" covers how to dynamically override startup settings in the bootstrap file with environment variables.
"Overriding Startup Settings by Using Java Properties" covers how to dynamically override startup settings in the bootstrap file with Java properties.

Replacing 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.

When/Where 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 "To Configure 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 prior to 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": "/path/to/openam/security/secrets/default/.storepass",
      "keyPasswordFile": "/path/to/openam/security/secrets/default/.keypass",
      "keyStoreType": "JCEKS",
      "keyStoreFile": "/path/to/openam/security/keystores/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`	Special AM user. 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).

Overriding Startup Settings by 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:

To Override Startup Settings by Using Environment Variables

Set an environment variable named MY_INSTANCE in the shell that starts AM.
Create a modified version of the bootstrap file with the following line:
```
"instance" : "${env.MY_INSTANCE}",
```
Overwrite the initial bootstrap file with the modified bootstrap file.
Start AM.

Overriding Startup Settings by 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:

To Override Startup Settings by Using Java Properties

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"
    }
},

Overwrite the initial bootstrap file with the modified bootstrap file.
Start AM.