--- title: Passive install using Amster description: Use Amster to configure a deployed AM instance as either a single, standalone server or as a server within a site. component: pingam version: 8.1 page_id: pingam:installation:passive-install-amster canonical_url: https://docs.pingidentity.com/pingam/8.1/installation/passive-install-amster.html page_aliases: ["user-guide:amster-install-am.adoc", "amster:configure-am-with-amster.adoc"] section_ids: install-am-examples: Examples example_1_standalone_server: "Example 1: Standalone server" example_2_two_servers_in_a_site: "Example 2: Two servers in a site" install-am-options: Configuration options am-post-install-steps-sites: Post-installation steps for site deployments amster-troubleshooting-am-install: Troubleshoot AM installations --- # 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](passive-install-fbc.html). | 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](#install-am-options). ## Examples Before you start, make sure your AM instance is deployed and running, but not yet configured. Learn more in [Deploy AM](deploy-openam.html). 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](prepare-ext-stores.html). 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](../amster/scripts.html). | ### 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](#install-am-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](#am-post-install-steps-sites). | * 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](../amster/connect-am.html). * `--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: 1. 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. 2. 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. 3. 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 | | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `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. |