Name
configurator.jar — install or upgrade OpenAM using a configuration file
Synopsis
configurator.jar
{options}
Description
This executable .jar file, , lets you perform silent installation, configuring a deployed OpenAM server by applying settings from a configuration file.
Options
The following options are supported.
-f | --file
configuration-file
-
Configure a deployed OpenAM web application archive using the specified configuration file. Installation and upgrade configuration files are described in the sections below.
-? | --help
-
Display the usage message.
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 ofADMIN_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 valuedirServer
means an external directory server, such as OpenDJ, or Sun Java System Directory Server. If you set this todirServer
, 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 toSSL
. - 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 toSSL
. - USERSTORE_DOMAINNAME
-
If
USERSTORE_TYPE
isLDAPv3ForADDC
, you set this to the Active Directory Domain Name, such asad.example.com
, and then set only theUSERSTORE_SSL
,USERSTORE_MGRDN
, andUSERSTORE_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 theDATA_STORE
parameter is set toembedded
. Use the otherDS_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
Upgrade 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.
Upgrade Properties
- SERVER_URL
-
URL to the web container where OpenAM runs, such as
http://openam.example.com:8080
- DEPLOYMENT_URI
-
URI where OpenAM is deployed on the web container, such as
/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