configurator.jar

Install or upgrade AM using a configuration file.

configurator.jar { options }

Description

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

Examples

The following example shows a configuration file to install a server with an external configuration and identity data stores:

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

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

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.

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

Access Management 7.3.1