Name

configurator.jar — install or upgrade OpenAM using a configuration file

Synopsis

configurator.jar {options}

Installation Configuration File

Base your configuration on the sampleconfiguration file delivered with OpenAM, and using the hints in this section, or the comments included in the file.

Server Properties

These properties pertain to the OpenAM server instance.

SERVER_URL

URL to the web container where you want OpenAM to run, such as http://openam.example.com:8080

DEPLOYMENT_URI

URI where you want to deploy OpenAM on the web container, such as /openam

BASE_DIR

Configuration directory where OpenAM stores files and embedded configuration directory servers, such as $HOME/openam

locale

The user locale, such as en_GB

PLATFORM_LOCALE

The locale of the OpenAM 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 OpenAM generates a random password encryption key that you can later view in OpenAM console under Configuration > Servers and Sites > Server Name > Security.

ADMIN_PWD

Password of the OpenAM administrator user amadmin, which must be at least 8 characters in length and must match that of other servers in a multiserver deployment

AMLDAPUSERPASSWD

Password of the default policy agent UrlAccessAgent, which must be at least 8 characters in length and must not be the same as the value of ADMIN_PWD

COOKIE_DOMAIN

Name of the trusted DNS domain OpenAM returns to a browser when it grants a session ID to a user, such as .example.com

Configuration Store Properties

These properties pertain to the directory server where OpenAM stores its configuration.

DATA_STORE

Type of the configuration data store. The value embedded means set up OpenAM with an embedded, OpenDJ based configuration store. The value dirServer means an external directory server, such as OpenDJ, or Sun Java System Directory Server. If you set this to dirServer, and the configuration store contains the configuration of other OpenAM 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 OpenDJ 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 cn=Directory Manager

DS_DIRMGRPASSWD

Password for the directory manager of the configuration store

User Data Store Properties

These properties pertain to the directory server where OpenAM stores user profiles. If you do not include these properties, or you leave these properties commented out, then OpenAM 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 Application Mode

  • 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 cn=Directory Manager

USERSTORE_PASSWD

Password for the directory manager of the user data store

Site Properties

These properties pertain when you configure multiple OpenAM servers in a site deployment, where a load balancer spreads request across multiple servers. Use the DS_EMB_REPL* and existingserverid properties only for the second and subsequent servers in a site configuration.

LB_SITE_NAME

The name of the OpenAM site

LB_PRIMARY_URL

The load balancer URL for the site, such as http://lb.example.com:80/openam.

LB_SESSION_HA_SFO

Whether to enable session persistence and failover for the site. Default: false

DS_EMB_REPL_FLAG

Enable use of the embedded configuration store by setting this parameter to embReplFlag, only if the DATA_STORE parameter is set to embedded. Use the other DS_EMB_REPL* parameters in this section to set up configuration store data replication.

DS_EMB_REPL_REPLPORT1

Replication port number for the new OpenAM server you are installing, such as 58989

DS_EMB_REPL_HOST2

Host name of an existing OpenAM server housing the configuration store directory server with which to replicate, such as openam1.example.com

DS_EMB_REPL_ADMINPORT2

Administration port number for the configuration store directory server used by the existing OpenAM server, such as 4444

DS_EMB_REPL_REPLPORT2

Replication port number for the configuration store directory server used by the existing OpenAM server, such as 50899

existingserverid

Full URL of the existing OpenAM server, such as http://server1.example.com:8080/openam

Examples

The following example shows a configuration file to install a server with an external user data store.

# Server properties, AM_ENC_KEY="" means generate random key
SERVER_URL=http://openam.example.com:8080
DEPLOYMENT_URI=/openam
BASE_DIR=$HOME/openam
locale=en_US
PLATFORM_LOCALE=en_US
AM_ENC_KEY=
ADMIN_PWD=change3me
AMLDAPUSERPASSWD=secret12
COOKIE_DOMAIN=.example.com

# Embedded configuration data store
DATA_STORE=embedded
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=openam.example.com
DIRECTORY_PORT=50389
DIRECTORY_ADMIN_PORT=4444
DIRECTORY_JMX_PORT=1689
ROOT_SUFFIX=o=openam
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=chang3me

# External OpenDJ based user data store
USERSTORE_TYPE=LDAPv3ForOpenDS
USERSTORE_SSL=SIMPLE
#USERSTORE_DOMAINNAME=ad.example.com 
USERSTORE_HOST=opendj.example.com
USERSTORE_PORT=389
USERSTORE_SUFFIX=dc=example,dc=com
USERSTORE_MGRDN=cn=Directory Manager
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=http://server2.example.com:8080
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=.example.com

# Embedded configuration data store
DATA_STORE=embedded
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=server2.example.com
DIRECTORY_PORT=50389
DIRECTORY_ADMIN_PORT=4444
DIRECTORY_JMX_PORT=1689
ROOT_SUFFIX=o=openam
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=chang3me

# External OpenDJ based user data store
USERSTORE_TYPE=LDAPv3ForOpenDS
USERSTORE_SSL=SIMPLE
#USERSTORE_DOMAINNAME=ad.example.com 
USERSTORE_HOST=opendj.example.com
USERSTORE_PORT=389
USERSTORE_SUFFIX=dc=example,dc=com
USERSTORE_MGRDN=cn=Directory Manager
USERSTORE_PASSWD=secret12

# Site properties
LB_SITE_NAME=lb
LB_PRIMARY_URL=http://lb.example.com:80/openam
DS_EMB_REPL_FLAG=embReplFlag
DS_EMB_REPL_REPLPORT1=58989
DS_EMB_REPL_HOST2=server1.example.com
DS_EMB_REPL_ADMINPORT2=4444
DS_EMB_REPL_REPLPORT2=50889
existingserverid=http://server1.example.com:8080/openam

The following example shows a configuration file to upgrade an OpenAM server.

SERVER_URL=https://openam.example.com:8080
DEPLOYMENT_URI=/openam