configurator.jar

Install or upgrade AM using a configuration file.

configurator.jar {options}

Description

This executable .jar file, openam-configurator-tool-14.1.3.19.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 console, 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.19.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[1]

  • 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.19.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.19.jar \
 -f config.file \
 --acceptLicense

[1] Formerly known as Active Directory Application Mode (ADAM).

Read a different version of :