--- title: configurator.jar description: Install or upgrade AM using a configuration file. component: pingam version: 8 page_id: pingam:am-reference:man-configurator-jar-1 canonical_url: https://docs.pingidentity.com/pingam/8/am-reference/man-configurator-jar-1.html keywords: ["Administration", "Install", "Configuration"] page_aliases: ["reference:man-configurator-jar-1.adoc"] section_ids: man-configurator-jar-1-desc: Description man-configurator-jar-1-options: Options man-configurator-jar-1-config: Installation configuration file server_properties: Server Properties configuration_store_properties: Configuration Store Properties identity_store_properties: Identity Store Properties site_properties: Site Properties man-configurator-jar-1-upgrade: Upgrade Configuration File upgrade_properties: Upgrade Properties man-configurator-jar-1-examples: Examples --- # configurator.jar Install or upgrade AM using a configuration file. ``` configurator.jar { options } ``` ## Description This executable `.jar` file, `openam-configurator-tool-14.1.3.30.jar`, lets you perform silent installation, configuring a deployed AM server by applying settings from a configuration file. ## Options The following options are supported. * `-f | --file configuration-file` Configure a deployed AM web application archive using the specified configuration file. Installation and upgrade configuration files are described in the sections below. * `--acceptLicense` Auto-accept the software license agreement and suppress the display of the licence acceptance page to the user. If the configuration file contains the `ACCEPT_LICENSES` property, it will have precedence over the command-line option. * `-? | --help` Display the usage message. ## Installation configuration file Base your configuration on the `sampleconfiguration` file delivered with AM, and using the hints in this section, or the comments included in the file. ### Server Properties These properties pertain to the AM server instance. * SERVER\_URL URL to the web container where you want AM to run, such as `https://am.example.com:8443`. * DEPLOYMENT\_URI URI where you want to deploy AM on the web container, such as `/am`. * BASE\_DIR Configuration directory where AM stores files, such as `$HOME/am`. * locale The user locale, such as `en_GB` * PLATFORM\_LOCALE The locale of the AM server, such as `en_US` * AM\_ENC\_KEY The password encryption key, which must be the same on all servers in a multiserver installation, such as `O6QWwHPO4os+zEz3Nqn/2daAYWyiFE32`. If left blank, installing AM generates a random password encryption key that you can view in the AM admin UI, under Deployment > Servers > *server name* > Security. * ADMIN\_PWD The password of the AM administrator user `amAdmin`, which must be at least 8 characters in length and must match that of other servers in a multiserver deployment. * COOKIE\_DOMAIN The name of the trusted DNS domain AM returns to a browser when it grants a session ID to a user. By default, it is set to the full URL used to access the configurator, such as `example.com`. * ACCEPT\_LICENSES Optional boolean property that can be set to always auto-accept the software license agreement and suppress the display of the license acceptance page to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the `openam-configurator-tool-14.1.3.30.jar` file. ### Configuration Store Properties These properties pertain to the directory server where AM stores its configuration. * DATA\_STORE Set this to `dirServer` to indicate an external PingDS directory server. If the configuration store contains the configuration of other AM servers, then the server is added to the existing multiserver installation. You must use an external directory server for the configuration store. If you try to install AM with the `DATA_STORE=embedded` property, the installation fails with the following exception `From AM 8, embedded DS configuration is not supported`. * DIRECTORY\_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`. * DIRECTORY\_SERVER The fully qualified domain name of the configuration store directory server host, such as `ds.example.com`. * DIRECTORY\_PORT The LDAPS or LDAP port number for the configuration store directory server, such as `1636` or `1389`. * DIRECTORY\_ADMIN\_PORT The administration port number for the configuration store directory server, such as `4444`. * ROOT\_SUFFIX The root suffix distinguished name (DN) for the configuration store, such as `ou=am-config`. * DS\_DIRMGRDN The bind DN of the configuration store user account, such as `uid=am-config,ou=admins,ou=am-config`. * DS\_DIRMGRPASSWD The password for the bind DN. ### Identity Store Properties These properties pertain to the directory server where AM stores identity profiles. If you don't include these properties, or you leave these properties commented out, then AM uses the same directory server as it uses for the configuration store. * USERSTORE\_TYPE The type of directory server used for the identity store. Valid values include the following. * `LDAPv3ForOpenDS`: PingDS * `LDAPv3ForAD`: Active Directory with host and port settings * `LDAPv3ForADDC`: Active Directory with a Domain Name setting * `LDAPv3ForADAM`: Active Directory Lightweight Directory Services (Formerly known as *Active Directory Application Mode* (ADAM).) * USERSTORE\_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`. * USERSTORE\_DOMAINNAME If `USERSTORE_TYPE` is `LDAPv3ForADDC`, you set this to the Active Directory Domain Name, such as `ad.example.com`, and then set only the `USERSTORE_SSL`, `USERSTORE_MGRDN`, and `USERSTORE_PASSWD` additional parameters. This lets Active Directory use DNS to retrieve service locations. Otherwise, don't use this property. * USERSTORE\_HOST The fully qualified domain name of the identity store directory server, such as `ds.example.com`. * USERSTORE\_PORT The port number of the identity store. Default for LDAPS is `636` and for LDAP is `389`. * USERSTORE\_SUFFIX The root suffix DN for the identity store, such as `ou=identities`. * USERSTORE\_MGRDN The bind DN of the identity store user account, such as `uid=am-identity-bind-account,ou=admins,ou=identities`. * USERSTORE\_PASSWD The password for the bind DN. ### Site Properties These properties pertain when you configure multiple AM servers in a site deployment, where a load balancer spreads request across multiple servers. * LB\_SITE\_NAME The name of the AM site * LB\_PRIMARY\_URL The load balancer URL for the site, such as `https://lb.example.com:8443/am`. ## Upgrade Configuration File Base your configuration on the `sampleconfiguration` file delivered with AM, and using the hints in this section, or the comments included in the file. ### Upgrade Properties * SERVER\_URL URL to the web container where AM runs, such as `https://am.example.com:8443` * DEPLOYMENT\_URI URI where AM is deployed on the web container, such as `/am` * ACCEPT\_LICENSES Optional boolean property that can be set to always auto-accept the software license agreement and suppress displaying the license acceptance page to the user. A value of `true` auto-accepts the license; any other value will be assumed to equal `false`, resulting in the presentation of the license. Default value is `false`. This property takes precedence over the `--acceptLicense` option, which can also be passed in to the application with the `openam-configurator-tool-14.1.3.30.jar` file. ## Examples The following example shows a configuration file to install a server with separate configuration and identity datastores: ```properties # Server properties, AM_ENC_KEY="" means generate random key SERVER_URL=https://am.example.com:8443 DEPLOYMENT_URI=/am BASE_DIR=$HOME/am locale=en_US PLATFORM_LOCALE=en_US AM_ENC_KEY= ADMIN_PWD=Ch4ng31t COOKIE_DOMAIN=am.example.com ACCEPT_LICENSES=true # External configuration data store DATA_STORE=dirServer DIRECTORY_SSL=SSL DIRECTORY_SERVER=ds.example.com DIRECTORY_PORT=1636 DIRECTORY_ADMIN_PORT=4444 ROOT_SUFFIX=ou=am-config DS_DIRMGRDN=uid=am-config,ou=admins,ou=am-config DS_DIRMGRPASSWD=Ch4ng31t # External DS-based user data store USERSTORE_TYPE=LDAPv3ForOpenDS USERSTORE_SSL=SSL #USERSTORE_DOMAINNAME=ad.example.com USERSTORE_HOST=ds.example.com USERSTORE_PORT=1636 USERSTORE_SUFFIX=ou=identities USERSTORE_MGRDN=uid=am-identity-bind-account,ou=admins,ou=identities USERSTORE_PASSWD=Ch4ng31t # Uncomment to specify the site for the first server in a site configuration #LB_SITE_NAME=lb #LB_PRIMARY_URL=http://lb.example.com:80/am ``` The following example shows a configuration file to install the second server in a site configuration. ```properties # Server properties, AM_ENC_KEY from first server SERVER_URL=https://server2.example.com:8443 DEPLOYMENT_URI=/am BASE_DIR=$HOME/am locale=en_US PLATFORM_LOCALE=en_US AM_ENC_KEY=O6QWwHPO4os+zEz3Nqn/2daAYWyiFE32 ADMIN_PWD=Ch4ng31t AMLDAPUSERPASSWD=Ch4ng31t COOKIE_DOMAIN=am.example.com ACCEPT_LICENSES=true # External configuration data store DATA_STORE=dirServer DIRECTORY_SSL=SSL DIRECTORY_SERVER=ds.example.com DIRECTORY_PORT=1636 DIRECTORY_ADMIN_PORT=4444 ROOT_SUFFIX=ou=am-config DS_DIRMGRDN=uid=am-config,ou=admins,ou=am-config DS_DIRMGRPASSWD=Ch4ng31t # External DS-based user data store USERSTORE_TYPE=LDAPv3ForOpenDS USERSTORE_SSL=SSL #USERSTORE_DOMAINNAME=ad.example.com USERSTORE_HOST=ds.example.com USERSTORE_PORT=1636 USERSTORE_SUFFIX=ou=identities USERSTORE_MGRDN=uid=am-identity-bind-account,ou=admins,ou=identities USERSTORE_PASSWD=Ch4ng31t # Site properties LB_SITE_NAME=lb LB_PRIMARY_URL=https://lb.example.com:8443/am ``` The following example shows a configuration file to upgrade an AM server: ```properties SERVER_URL=https://am.example.com:8443 DEPLOYMENT_URI=/am ACCEPT_LICENSES=true ``` The following example uses a configuration file with the `--acceptLicense` option on the command line. ```bash $ java \ -jar openam-configurator-tool-14.1.3.30.jar \ -f config.file \ --acceptLicense ```