configurator.jar

Install or upgrade AM using a configuration file.

configurator.jar { options }

Description

This executable .jar file, openam-configurator-tool-14.1.3.29.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.29.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.29.jar file.

Examples

The following example shows a configuration file to install a server with separate configuration and identity datastores:

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

# 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:

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.

$ java \
 -jar openam-configurator-tool-14.1.3.29.jar \
 -f config.file \
 --acceptLicense

PingAM