Amster is a standalone client that does not require any other component from the ForgeRock Identity Platform to run. See the following list of prerequisites for installation:

The ForgeRock BackStage website hosts downloadable versions of Amster. For each release of AM you can download Amster as a .zip file.

After you download the .zip file, create a new directory for Amster and unzip the .zip file:

$ mkdir /amster
$ unzip ~/Downloads/Amster-5.0.0.zip -d amster

The following files and directories are extracted:

Once Amster is extracted, run the amster command to start the client:

$ cd /path/to/amster
$ ./amster
OpenAM Shell (14.0.0 build 73b1bc9327, JVM: 1.8.0_101)
Type ':help' or ':h' for help.
------------------------------------------------------------------------------
am>

The version of Amster is included in the first line of output, as well as the version of the running JDK.

To exit the client, run the :exit or :q commands:

am> :exit
$ 

To get a list of the commands available to the client, run the :help command:

am> :help
For information about Groovy, visit:
   http://groovy-lang.org

Available commands:
   connect         (am  ) Connect to an OpenAM instance
   create          (c   ) Create an OpenAM entity
   read            (r   ) Read an OpenAM entity
   update          (u   ) Update an OpenAM entity
   delete          (d   ) Delete an OpenAM entity
   query           (q   ) Query an OpenAM entity
   action          (a   ) Perform action an OpenAM entity
   import-config   (i   ) Import configuration into OpenAM
   export-config   (x   ) Export configuration from OpenAM
   replace         (rep ) Replace all matching text
   install-openam  (inst) Install OpenAM
   :help           (:h  ) Display this help message
   ?               (:?  ) Alias to: :help
   :exit           (:x  ) Exit the shell
   :quit           (:q  ) Alias to: :exit
   :load           (:l  ) Load a file or URL into the buffer
   .               (:.  ) Alias to: :load

For help on a specific command type:
   :help command

To show help information available for a particular command, run :help command. For example:

am> :help connect
usage: connect [options] <baseurl>
Options:

  -i, --interactive
  If specified you will be prompted for credentials. Defaults to private
  key authentication.

  -k, --private-key
  Path to a private key file or directory containing one of amster_rsa,
  id_rsa or id_ecdsa. Defaults to {USER_HOME}/.ssh.

Connect to the OpenAM instance at the given URL.
Example:

  connect -i https://am.example.com/openam

$ ./amster -d
   Listening for transport dt_socket at address: 6006
    DEBUG [org.codehaus.groovy.tools.shell.BufferManager] Created new buffer with index: 0
    DEBUG [org.codehaus.groovy.tools.shell.BufferManager] Buffers reset
    DEBUG [org.codehaus.groovy.tools.shell.Parser] Using parser flavor: rigid
    ...

Amster can connect to an AM instance using interactive login or using RSA or ECDSA key files, either over HTTP or HTTPS protocols. If you use self-signed certificates for AM, you must either:

To import and export encrypted password values in the configuration files you must generate a transport key, and install it in the keystore of each AM instance that you will be transporting passwords between.

The transport key must be stored in the default AM keystore, located at /path/to/openam/openam/keystore.jceks, and should have a key alias of sms.transport.key.

The presence of the transport key causes additional fields containing encrypted password values to appear in the exported configuration files. These additional fields have a -encrypted suffix, as shown below:

"authenticatorPushDeviceSettingsEncryptionKeystorePassword" : null,
"authenticatorPushDeviceSettingsEncryptionKeystorePassword-encrypted" :
"AAAAA0FFUwIQ1WDDMsxGoZMiRHhDQ+ywUfTMdGtYqEsvZZLV9W8ygfHi/5kBWjMpyg=="

Without a transport key present, all password fields are set to null in the exported configuration files, regardless of their actual value in the configuration.

To decrypt and import configuration files that contain encrypted passwords, you must install the same transport key used to encrypt it into the keystore of the target AM instance.

Amster can export configuration data from an AM instance. Export configuration data by using the export-config command.

The exported configuration data is written to a number of JSON-formatted files. The files are arranged in a hierarchy of global and realm configuration data.

To export encrypted password values in the configuration files you must generate and install a transport key. See Section 3.1, "Creating Transport Keys".

Usage:

am> export-config --path Path [options]

Options:

am> export-config --path /tmp/myExportedConfigFiles --failOnError true
Export completed successfully

am> export-config --path /tmp/myExportedConfigFiles --realms '/mySubRealm' --realmEntities 'DataStoreModule Scripts OAuth2Provider' --globalEntities ' '
Export completed successfully

Amster can import configuration data to an AM instance. Import configuration data by using the import-config command.

To import encrypted password values in the configuration files you must install the transport key used to encrypt the data. See Section 3.1, "Creating Transport Keys".

Usage:

am> import-config --path Path [options]

Options:

am> import-config --path /tmp/myExportedConfigFiles --failOnError true
Importing directory /tmp/myExportedConfigFiles
...
Import completed successfully

am> import-config --path /tmp/myExportedConfigFiles  --clean true
Cleaning global settings
Deleting JSON: Global JSON Handler
Deleting Scripting: 9de3eb62-f131-4fac-a294-7bd170fd4acb
Deleting Scripting: 7e3d7067-d50f-4674-8c76-a3e13a810c33
Deleting Scripting: c827d2b4-3608-4693-868e-bbcf86bd87c7
Global settings cleaned
Importing directory /tmp/myExportedConfigFiles
...
Import completed successfully

Amster supports the use of variables in the configuration files. The values for the variables can be set from within Amster.

The syntax for a variable in the configuration files is AMSTER{myVariableName}.

The following example shows an excerpt from the configuration file for the email service, with variables inserted for a number of properties:

{
  "data" : {
    "_id" : "",
    "emailAddressAttribute" : "mail",
    "message" : null,
    "port" : AMSTER{emailServicePort},
    "password" : null,
    "from" : null,
    "hostname" : "AMSTER{emailServiceHostname}",
    "username" : "AMSTER{emailServiceUsername}",
    "sslState" : "SSL",
    "subject" : "AMSTER{emailServiceSubject}",
    "emailImplClassName" : "org.forgerock.openam.services.email.MailServerImpl",
    "_type" : {
      "_id" : "email",
      "name" : "Email Service",
      "collection" : false
    }
  }
}

Note that the JSON file must still be valid once variables have been replaced with their values. For example, ensure properties that require a string surround the variable with double quotes (").

Set the value for a property in Amster as follows:

am> myVariableName="Value"
===> Value

You can also set the values for variables in Groovy script files that are executed from within Amster. For more information, see Section 3.5, "Scripting".

Attempting to import configuration files that contain variables that are not defined causes and error message similar to the following:

am> import-config --path /tmp/myExportedConfigFiles/realms/root/EmailService.json
Importing file /tmp/myExportedConfigFiles/realms/root/EmailService.json
---------------------------------------------------------------------
IMPORT ERRORS
---------------------------------------------------------------------
Failed to import /tmp/myExportedConfigFiles/realms/root/EmailService.json  :
  Found template variable "emailServicePort" in a file with no associated variable in the binding

You can create script files containing a series of commands and variable declarations, which can be loaded and executed within Amster.

Start each separate command or variable declaration on a new line. Use the backslash (\) character to represent line continuations.

For example, the following script installs an AM instance, and then exits the Amster command-line interface:

install-openam \
--serverUrl https://openam.example.com:8443/openam \
--authorizedKey /var/amster/authorized_keys \
--cookieDomain .example.com --adminPwd forgerock \
--cfgStoreDirMgrPwd password  --cfgStoreAdminPort 389  \
--policyAgentPwd Passw0rd --acceptLicense  --cfgStore dirServer \
--cfgDir /root/openam
:exit

The Amster shell supports an eval(String) function, which evaluates any Amster command expressed as a string. For example, the function is required within looping structures:

for (i = 0; i < 4; i++) {
    eval("create DataStoreModule --realm / --body '{\"_id\":\"myDataStore$i\"}'")
 }

You must also use the eval(String) function when using Amster commands in conditional structures:

dbStatus = databaseName ? 'Found' : eval("create DataStoreModule --realm / --body '{\"_id\":\"myDataStore\"}'")

To load and execute the commands within a script, use the :load command, as follows:

am> :load myScript.amster

You can specify more than one script to load. Scripts are loaded and executed in the order they are specified. If a command in a script fails, execution continues with the next command.

You can also invoke scripts by passing them in directly to Amster:

$ vi samples/myScript.amster
  connect http://openam.example.com:8080/openam -k /home/forgerock/am/amster_rsa
  :exit

$ ./amster samples/myScript.amster
Amster OpenAM Shell (14.0.0 build 95de0e129b, JVM: 1.8.0_151)
Type ':help' or ':h' for help.
--------------------------------------------------------------------------------
  am>:load samples/myScript.amster
===> true

You can also inject Bash shell variables into an Amster script by using the -D parameter. For example, pass your shell variables into the Amster script, export-config.amster:

amUrl="http://openam.example.com:8080/openam"
amsterKey="/root/openam/amster_rsa"
configPath="/root/am-config"
.amster export-config.amster -D AM_URL=${amUrl} -D AMSTER_KEYS=${amsterKey} \
   -D AM_CONFIG_PATH=${configPath}

Next, use the variables in the Amster script, export-config.amster:

amUrl = System.getProperty("AM_URL")
amsterKey = System.getProperty("AMSTER_KEY")
exportPath = System.getProperty("AM_CONFIG_PATH")

connect amUrl -k amsterKey
export-config --path exportPath --failOnError
:exit

Amster can configure a deployed AM as a single, stand-alone instance. If your environment requires a multi-server deployment, see the ForgeRock Access Management Installation Guide.

Install AM configuration with Amster by using the install-openam command:

Usage:

am> install-openam \
   --serverUrl protocol://FQDN:port/URI \
   --adminPwd amAdmin_password \
   --policyAgentPwd agent_password \
   [options]

Options:

am> install-openam \
> --serverUrl https://openam.example.com:8443/openam \
> --adminPwd forgerock \
> --policyAgentPwd forgerock01 \
> --acceptLicense

02/22/2017 05:16:20:932 AM GMT: Checking license acceptance...
02/22/2017 05:16:20:934 AM GMT: License terms accepted.
02/22/2017 05:16:20:936 AM GMT: Checking configuration directory /tomcat/openam.
02/22/2017 05:16:20:936 AM GMT: ...Success.
02/22/2017 05:16:20:936 AM GMT: Extracting OpenDJ, please wait...
02/22/2017 05:16:21:265 AM GMT: Complete
02/22/2017 05:16:21:265 AM GMT: Running OpenDJ setup
02/22/2017 05:16:21:265 AM GMT: Setup command: --cli --adminConnectorPort 4444
 --baseDN dc=openam,dc=forgerock,dc=org --rootUserDN cn=Directory Manager
 --ldapPort 50389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
 --no-prompt --doNotStart --hostname openam.example.com --noPropertiesFile
 --backendType je
%0AConfiguring+Directory+Server+.....+Done.
0A%0ATo+see+basic+server+configuration+status+and+configuration%2C+you+can+launch%
0A%2Ftomcat_b%2Fopenam%2Fopends%2Fbin%2Fstatus%0A%0A02/22/2017 05:16:24:531 AM GMT: ...Success.
02/22/2017 05:16:24:531 AM GMT: ...Success
02/22/2017 05:16:24:531 AM GMT: Installing OpenAM configuration store in /tomcat/openam/opends
...
02/22/2017 05:16:53:123 AM GMT: Configuring server instance.
02/22/2017 05:16:53:176 AM GMT: ...Done
02/22/2017 05:16:55:918 AM GMT: Creating demo user.
02/22/2017 05:16:55:942 AM GMT: ...Done
02/22/2017 05:16:55:943 AM GMT: Setting up monitoring authentication file.
Configuration complete!

am> install-openam \
> --serverUrl https://openam.example.com:8443/openam \
> --adminPwd forgerock \
> --policyAgentPwd forgerock01 \
> --acceptLicense \
> --cfgDir /tomcat/openam2

02/22/2017 05:34:32:007 AM GMT: Checking license acceptance...
02/22/2017 05:34:32:007 AM GMT: License terms accepted.
02/22/2017 05:34:32:009 AM GMT: Checking configuration directory /tomcat/openam2.
02/22/2017 05:34:32:010 AM GMT: ...Success.
02/22/2017 05:34:32:010 AM GMT: Extracting OpenDJ, please wait...
02/22/2017 05:34:32:280 AM GMT: Complete
02/22/2017 05:34:32:280 AM GMT: Running OpenDJ setup
02/22/2017 05:34:32:265 AM GMT: Setup command: --cli --adminConnectorPort 4444
--baseDN dc=openam,dc=forgerock,dc=org --rootUserDN cn=Directory Manager
--ldapPort 389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
--no-prompt --doNotStart --hostname openam.example.com --noPropertiesFile
--backendType je
%0AConfiguring+Directory+Server+.....+Done.
...
02/22/2017 05:35:03:509 AM GMT: ...Done
02/22/2017 05:35:03:509 AM GMT: Setting up monitoring authentication file.
Configuration complete!

In this section you can find examples of tasks you can do with Amster.

ssoadm service name: iPlanetAMAuthAmsterService