Passive install using Amster

Use Amster to configure a deployed AM instance as either a single, standalone server or as a server within a site.

Amster configures AM to use an external configuration store and identity store.

You can’t use Amster to install PingAM in file-based configuration (FBC) mode. Instead, follow the instructions in Passive install with FBC.

To configure AM with Amster, run the install-openam command:

Usage:

am> install-openam \
 --serverUrl protocol://FQDN:port/URI \
 --adminPwd amAdmin_password \
   [options]

--serverUrl protocol://FQDN:port/URI: The protocol, URL, port, and deployment URI of the AM instance. For example, https://am.example.com:8443/am.
--adminPwd amAdmin-password: The password of the amAdmin user. If the --cfgStoreDirMgrPwd option is not specified, this value is also the password of the configuration store’s directory manager user.

The password must be at least 8 characters in length.

Options:

[options]: Use these optional parameters to configure properties like the cookie domain, ports, and passwords for the configuration store.

To see all available options, run the :help install-openam command or read Configuration options.

Examples

Before you start, make sure your AM instance is deployed and running, but not yet configured. Learn more in Deploy AM.

Before you run the amster command, you must create a truststore for AM, and prepare the external configuration and identity stores. Learn more in Prepare datastores.

You can’t install AM with an external configuration store that already contains configuration data, unless you’re adding a server to an existing site.

Amster also supports scripting the installation process. Learn more in Scripts.

Example 1: Standalone server

This example installs AM with external configuration and identity stores.

am> install-openam \
 --serverUrl https://am.example.com:8443/am \
 --adminPwd Ch4ng31t \
 --acceptLicense \
 --cfgStoreDirMgrPwd Ch4ng31t \
 --cfgStore dirServer \
 --cfgStoreHost ds.example.com \
 --cfgStoreAdminPort 4444 \
 --cfgStorePort 1636 \
 --cfgStoreSsl SSL \
 --cfgStoreRootSuffix ou=am-config \
 --userStoreDirMgrPwd Ch4ng31t \
 --userStoreHost ds.example.com \
 --userStoreType LDAPv3ForOpenDS \
 --userStorePort 1636 \
 --userStoreSsl SSL \
 --userStoreRootSuffix ou=identities
timestamp: Checking license acceptance…
timestamp: License terms accepted.
timestamp: Checking configuration directory /Users/Ping/am.
timestamp: …Success.
timestamp: Tag swapping schema files.
timestamp: …Success.
…
timestamp: Loading Schema /Users/Ping/am/opendj_pushdevices.ldif
timestamp: …Success.
timestamp: Installing new plugins…
timestamp: Plugin installation complete.
timestamp: Setting up monitoring authentication file.
Configuration complete!

When you install AM locally, Amster stores the AM configuration in the home directory of the user running the amster command. For example, for the tomcat user, the configuration is stored in /path/to/tomcat_home/am . To change this location, use the --cfgDir option.
The DS instances in this example require secure connections, so the amster command specifies port 1636 and SSL for both stores.

Find information about other options in Configuration options.

You must create a truststore and configure it in the AM container. If you don’t, the installation will fail.
If a problem occurs while setting up the configuration store, the installation process exits with an error. When this happens, going to the AM URL opens the configuration page.

Example 2: Two servers in a site

This example shows how to install two AM servers in a site with external configuration and identity stores.

Before you start, create a truststore for each AM server and prepare the external stores. Because both servers share the configuration and identity store, their truststores must contain the same certificates.

First instance:

am> install-openam \
 --serverUrl https://am1.example.com:8443/am \
 --adminPwd Ch4ng31t \
 --acceptLicense \
 --cookieDomain example.com \
 --lbSiteName TestSite01 \
 --cfgDir /tomcat/am1 \
 --lbPrimaryUrl https://site.example.com:8443/am \
 --cfgStoreDirMgr uid=am-config,ou=admins,ou=am-config \
 --cfgStoreDirMgrPwd Ch4ng31t
 --cfgStore dirServer \
 --cfgStoreHost ds.example.com \
 --cfgStoreAdminPort 3444 \
 --cfgStorePort 1636 \
 --cfgStoreSsl SSL \
 --cfgStoreRootSuffix ou=am-config \
 --userStoreDirMgrPwd Ch4ng31t \
 --userStoreHost ds.example.com \
 --userStoreType LDAPv3ForOpenDS \
 --userStorePort 1636 \
 --userStoreSsl SSL \
 --userStoreRootSuffix ou=identities
timestamp: Checking license acceptance…
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/am1.
timestamp: …Success.
…
timestamp: …Success.
…
timestamp: …Success.
timestamp: Installing new plugins…
timestamp: Plugin installation complete.
timestamp: Setting up monitoring authentication file.
Configuration complete!

Amster creates the directory specified with the --cfgDir option.
The --lbSiteName option creates a site with that name, accessible at the URL specified with --lbPrimaryUrl.
Use the --cookieDomain option to set the cookie domain. If you don’t specify it, Amster uses the server’s URL, which isn’t optimal for a site with multiple servers.

Second instance:

am> install-openam \
 --serverUrl https://am2.example.com:8443/am \
 --adminPwd Ch4ng31t \
 --acceptLicense \
 --cookieDomain example.com \
 --lbSiteName TestSite01 \
 --cfgDir /tomcat/am2 \
 --lbPrimaryUrl https://site.example.com:8443/am \
 --cfgStoreDirMgr uid=am-config,ou=admins,ou=am-config \
 --cfgStoreDirMgrPwd Ch4ng31t \
 --cfgStore dirServer\
 --cfgStoreHost ds.example.com \
 --cfgStoreAdminPort 3444 \
 --cfgStorePort 1636 \
 --cfgStoreSsl SSL \
 --cfgStoreRootSuffix ou=am-config \
 --userStoreDirMgrPwd Ch4ng31t \
 --userStoreHost ds.example.com \
 --userStoreType LDAPv3ForOpenDS \
 --userStorePort 1636 \
 --userStoreSsl SSL \
 --userStoreRootSuffix ou=identities \
 --pwdEncKey MneLwkkOokJx58znp7QyvGmiawmc2vl4
timestamp: Checking license acceptance…
timestamp: License terms accepted.
timestamp: Checking configuration directory /tomcat/am2.
timestamp: …Success.
timestamp:Reinitializing system properties.
timestamp:…Done
timestamp:Configuring server instance.
timestamp: …Done
timestamp: Installing new plugins…
timestamp: Plugin installation complete.
timestamp: Setting up monitoring authentication file.
Configuration complete!

To finish adding the second server to the site, you must follow the steps in Post-installation steps for site deployments.

This command adds a new AM server to the TestSite01 site. The configuration store details are identical to the first server’s, as they share the same DS instance.
The password for --adminPwd must be the same one used for all other servers in the site.
The --cookieDomain must be the same as the one used for the first server (example.com).

If this option isn’t set correctly, you might not be able to sign in to the new server.
The --pwdEncKey option specifies the encryption key used by the existing servers in the site. To find this key, sign in to an existing server and go to Deployment > Servers > Server Name > Security > Encryption.

You must set this option to the correct value. If you don’t, the original encryption key will be overwritten, which will prevent the site from reading the configuration and identity stores.

Configuration options

The following options are available to use with the install-openam command:

--acceptLicense

Indicates the user accepts Amster usage terms and conditions.

--authorizedKey path

The path to an SSH public key file. The content of this file is appended to the authorized_keys file of the newly-installed AM instance, allowing users to connect to it with Amster after the install completes.

Find more information about connecting to AM with Amster in Connect to AM.

--cfgDir path

The configuration directory where AM stores files, such as $HOME/am.

--cfgStore dirServer

Set this to dirServer to install AM with an external DS server as the configuration store.

By default, identities are stored in the same directory server instance as the configuration store.

You must use an external directory server for the configuration store. If you try to install AM with the --cfgStore embedded option, the installation fails with the following exception From AM 8, embedded DS configuration is not supported.

--cfgStoreAdminPort port

The administration port number for the configuration store, such as 4444.

--cfgStoreDirMgr username

The bind DN of the configuration store user account, such as uid=am-config,ou=admins,ou=am-config.

--cfgStoreDirMgrPwd password

The password for the bind DN. If not set, it takes the password defined for the --adminPwd option.

--cfgStoreHost FQDN

The FQDN of the configuration store directory server host, for example, ds.example.com.

--cfgStorePort port

The LDAPS or LDAP port number for the configuration store directory server, such as 1636 or 1389.

--cfgStoreRootSuffix DN

The root suffix DN for the configuration store, such as ou=am-config.

--cfgStoreSsl [SIMPLE|SSL]

Set this to SSL to use LDAP with SSL. DS is configured for LDAPS by default. To use LDAP without SSL, set this to SIMPLE.

--cookieDomain domain

The name of the trusted DNS domain AM returns to a browser when it grants a session ID to a user.

Default: FQDN used in the --serverUrl option

--installLocale locale

The locale to use during the install process.

Default: en_US

--lbPrimaryUrl URL

The load balancer URL of the site, such as https://lb.example.com:443/am

--lbSiteName name

The name of the site to create, if any.

--platformLocale locale

The default locale for the AM installation.

Default: en_US

--pwdEncKey key

The encryption key value used to encrypt passwords in the AM instance. For example O6QWwHPO4os+zEz3Nqn/2daAYWyiFE32.

If you’re installing an AM instance that will use existing data, you must provide the same encryption key value originally used to encrypt the passwords in those data stores.

To locate the encryption key value in an AM instance, navigate to Deployment > Servers > server name > Security > Encryption.

If you are installing a new AM instance that won’t use existing data in a data store, you can leave this property empty. AM generates a random encryption key during installation to encrypt the data that will be added to the data store.

This option is required when configuring an AM instance into a site, and must be set to the encryption key configured for the rest of the servers in the site. Failure to set this option to the appropriate value will cause the original encryption key to be overwritten, which will render the site unable to read the configuration, and the identity stores.

Default: No value; a random encryption key is generated during installation

--userStoreDirMgr username

The bind DN of the identity store user account, such as uid=am-identity-bind-account,ou=admins,ou=identities.

--userStoreDirMgrPwd password

The password for the bind DN.

--userStoreDomainName FQDN

The Active Directory Domain Name, such as ad.example.com, when the --userStoreType option is set to LDAPv3ForADDC.

--userStoreHost FQDN

The FQDN of the identity store directory server, such as ds.example.com.

--userStorePort port

The LDAPS or LDAP port number for the identity store. Default for LDAPS is 636 and for LDAP is 389.

--userStoreRootSuffix DN

The root suffix DN for the identity store, such as ou=identities.

--userStoreSsl [SIMPLE|SSL]

Set this to SSL to use LDAP with SSL. DS is configured for LDAPS by default. To use LDAP without SSL, set this to SIMPLE.

--userStoreType type

The type of directory server used for the identity store. Possible values for type are:

LDAPv3ForAD: Active Directory with host and port settings
LDAPv3ForADDC: Active Directory with domain name setting

If you use this type, you must also set the --userStoreDomainName option.
LDAPv3ForADAM: Active Directory Lightweight Directory Services (AD LDS)
LDAPv3ForForgeRockIAM: PingDS

Only use this type if DS is the shared identity store in a Ping Identity Platform deployment. Otherwise, use LDAPv3ForOpenDS.
LDAPv3ForOpenDS: PingDS
LDAPv3ForPingDirectory: PingDirectory

--userStoreDomainName

If --userStoreType is LDAPv3ForADDC, set this to the Active Directory Domain Name, such as ad.example.com. Then only set the --userStoreSsl, --userStoreDirMgr, and --userStoreDirMgrPwd options to let Active Directory use DNS to retrieve service locations. Otherwise, don’t set this option.

Post-installation steps for site deployments

All AM servers in a site share the same keystore and secret store infrastructure. This sharing ensures every server in the site can encrypt, decrypt, and verify items like messages and JWTs with the same keys.

The installation process creates these stores only on the first server in the site. You must manually configure them on all other servers you add to the site.

After you’ve used Amster to add a new server to your site, follow these steps:

Make the site keystore infrastructure available to the new instance:
- Back up the new instance’s default keystore and password files in the following locations:
  - /path/to/am/security/keystores/
  - /path/to/am/security/secrets/default/
- Make the existing site keystores available to the new server in the same location. For example, you might copy the keystores and their password files, or mount a shared volume.
- Make sure the keystore files configured in the /path/to/am/config/boot.json are available to the new instance.
Make the secret store infrastructure in the site available to the new instance:
- Sign in to the AM admin UI of an existing server in the site and go to Configure > Secret Stores.
- Review the list of globally configured secret stores and make sure the new server has access to the required stores. For example:
  - For keystore-type secret stores, copy the keystores to the same path on the new server.
  - For filesystem-type secret stores, copy the directory contents to the same path, or make the filesystem available on the same mount point.
  - For HSM-type stores, make sure the new server can access the HSM.
  - For secrets configured as environment variables, make sure the new server’s container can access them.
- Go to Realms > realm name > Secret Stores.
- Review the list of realm-specific secret stores and provide access to the new server as needed.
Restart the new server.

The server is now fully configured and part of the site.

Troubleshoot AM installations

The following table describes possible errors when installing AM with the install-openam command:

Error Solution

Error	Solution
`Invalid Suffix for directory server ds.example.com:1636. No Base Entity dc=incorrectsuffix,dc=com found.`	Check that the suffix you are trying to use exists in DS.
`Cannot connect to Directory Server. Invalid Credentials.`	Check the credentials you’re using to connect to DS.
`Cannot connect to Directory Server. Connect Error: Connection refused.`	Check the DS host and connection port.
`Unexpected LDAP exception occurred.`	Check the DS logs. DS may be stopped or may have become unreachable during the installation.
`Cannot connect to Directory Server. Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake.`	Make sure the container where AM is installed trusts the DS SSL certificates.

Invalid Suffix for directory server ds.example.com:1636. No Base Entity dc=incorrectsuffix,dc=com found.

Check that the suffix you are trying to use exists in DS.

Cannot connect to Directory Server. Invalid Credentials.

Check the credentials you’re using to connect to DS.

Cannot connect to Directory Server. Connect Error: Connection refused.

Check the DS host and connection port.

Unexpected LDAP exception occurred.

Check the DS logs. DS may be stopped or may have become unreachable during the installation.

Cannot connect to Directory Server. Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake.

Make sure the container where AM is installed trusts the DS SSL certificates.