--- title: configurator.jar description: Install or upgrade AM using a configuration file. component: pingam version: 7.3 page_id: pingam:reference:man-configurator-jar-1 canonical_url: https://docs.pingidentity.com/pingam/8/am-reference/man-configurator-jar-1.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Administration", "Install", "Configuration"] superseded_by: https://docs.pingidentity.com/pingam/8/am-reference/man-configurator-jar-1.html section_ids: man-configurator-jar-1-desc: Description man-configurator-jar-1-options: Options man-configurator-jar-1-config: Installation configuration file man-configurator-jar-1-upgrade: Upgrade Configuration File 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.28.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 screen 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 `http://openam.example.com:8080`. * DEPLOYMENT_URI URI where you want to deploy AM on the web container, such as `/openam`. * BASE_DIR Configuration directory where AM stores files and embedded configuration directory server, such as `$HOME/openam`. * 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 multi-server 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 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 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 that was 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 screen 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.28.jar file. Configuration Store Properties These properties pertain to the directory server where AM stores its configuration. * DATA_STORE Type of the configuration data store. The value `embedded` means set up AM with an embedded, DS configuration store. The value `dirServer` means an external directory server, such as ForgeRock Directory Services, or Oracle Directory Server Enterprise Edition. If you set this to `dirServer`, and the configuration store contains the configuration of other AM servers, then the server is added to the existing multiserver installation. * DIRECTORY_SSL To use LDAP without SSL, set this to `SIMPLE`. To use LDAP with SSL, set this to `SSL`. * DIRECTORY_SERVER Fully qualified domain name of the configuration store directory server host, such as `opendj.example.com`. * DIRECTORY_PORT LDAP or LDAPS port number for the configuration store directory server, such as 389 or 636. * DIRECTORY_ADMIN_PORT Administration port number for the configuration store directory server, such as 4444. * DIRECTORY_JMX_PORT Java Management eXtension port number, such as `1689`, used with the DS embedded configuration store. * ROOT_SUFFIX Root suffix distinguished name (DN) for the configuration store, such as `o=openam`. * DS_DIRMGRDN Distinguished name of the directory manager of the configuration store, such as `uid=admin`. * DS_DIRMGRPASSWD Password for the directory manager of the configuration store. User Data Store Properties These properties pertain to the directory server where AM stores user profiles. If you do not 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. Valid values include the following. * `LDAPv3ForOpenDS`: ForgeRock 0penDJ or Sun OpenDS * `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).) * `LDAPv3ForODSEE`: Sun Java System Directory Server * `LDAPv3ForTivoli`: IBM Tivoli Directory Server * USERSTORE_SSL To use LDAP without SSL, set this to `SIMPLE`. To use LDAP with SSL, set this to `SSL`. * 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, do not use. * USERSTORE_HOST Fully qualified domain name of the user data store directory server, such as `opendj.example.com`. * USERSTORE_PORT Port number of the user data store. Default for LDAP is 389, and for LDAP over SSL is 636. * USERSTORE_SUFFIX Root suffix distinguished name for the user data in the directory, such as `dc=example,dc=com`. * USERSTORE_MGRDN Distinguished name of the directory manager of the user data store, such as `uid=admin`. * USERSTORE_PASSWD Password for the directory manager of the user data store. 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 `http://lb.example.com:80/openam`. ## 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 `http://openam.example.com:8080` * DEPLOYMENT_URI URI where AM is deployed on the web container, such as `/openam` * ACCEPT_LICENSES Optional boolean property that can be set to always auto-accept the software license agreement and suppress displaying the license acceptance screen 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.28.jar file. ## Examples The following example shows a configuration file to install a server with an external configuration and identity data stores: ```properties # Server properties, AM_ENC_KEY="" means generate random key SERVER_URL=https://openam.example.com:8443 DEPLOYMENT_URI=/openam BASE_DIR=$HOME/openam locale=en_US PLATFORM_LOCALE=en_US AM_ENC_KEY= ADMIN_PWD=change3me COOKIE_DOMAIN=openam.example.com ACCEPT_LICENSES=true # External configuration data store DATA_STORE=dirServer DIRECTORY_SSL=SSL DIRECTORY_SERVER=opendj.example.com DIRECTORY_PORT=1636 DIRECTORY_ADMIN_PORT=4444 DIRECTORY_JMX_PORT=1689 ROOT_SUFFIX=o=openam DS_DIRMGRDN=uid=admin DS_DIRMGRPASSWD=chang3me # External DS-based user data store USERSTORE_TYPE=LDAPv3ForOpenDS USERSTORE_SSL=SSL #USERSTORE_DOMAINNAME=ad.example.com USERSTORE_HOST=opendj.example.com USERSTORE_PORT=1636 USERSTORE_SUFFIX=dc=example,dc=com USERSTORE_MGRDN=uid=admin USERSTORE_PASSWD=secret12 # 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/openam ``` 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=/openam BASE_DIR=$HOME/openam locale=en_US PLATFORM_LOCALE=en_US AM_ENC_KEY=O6QWwHPO4os+zEz3Nqn/2daAYWyiFE32 ADMIN_PWD=change3me AMLDAPUSERPASSWD=secret12 COOKIE_DOMAIN=openam.example.com ACCEPT_LICENSES=true # External configuration data store DATA_STORE=dirServer DIRECTORY_SSL=SSL DIRECTORY_SERVER=opendj.example.com DIRECTORY_PORT=1636 DIRECTORY_ADMIN_PORT=4444 DIRECTORY_JMX_PORT=1689 ROOT_SUFFIX=o=openam DS_DIRMGRDN=uid=admin DS_DIRMGRPASSWD=chang3me # External DS-based user data store USERSTORE_TYPE=LDAPv3ForOpenDS USERSTORE_SSL=SSL #USERSTORE_DOMAINNAME=ad.example.com USERSTORE_HOST=opendj.example.com USERSTORE_PORT=1636 USERSTORE_SUFFIX=dc=example,dc=com USERSTORE_MGRDN=uid=admin USERSTORE_PASSWD=secret12 # Site properties LB_SITE_NAME=lb LB_PRIMARY_URL=http://lb.example.com:80/openam ``` The following example shows a configuration file to upgrade an AM server: ```properties SERVER_URL=https://openam.example.com:8443 DEPLOYMENT_URI=/openam 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.28.jar \ -f config.file \ --acceptLicense ```