Install Amster

Prerequisites

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:

Amster requires a Java developer environment. Check the output of the java -version command to make sure your version is supported. For information on supported versions, refer to Before you install.
The JAVA_HOME environment variable must be set.

Install process

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. For example:

$ mkdir /path/to/amster_7.3.1
$ unzip ~/Downloads/Amster-7.3.1.zip -d amster_7.3.1

File and directory reference

The following files and directories are extracted:

bcprov-jdk15on-1.55.jar: Third-party cryptography library, by Bouncy Castle.
bcpkix-jdk15on-1.55.jar: Third-party cryptography library, by Bouncy Castle.
amster: The amster command.
README.md: Amster readme file, with quick-start information.
LICENSE: ForgeRock’s Amster terms of license.
amster-7.3.1.jar: The main Amster Java library.
/legal-notices: Directory containing legal notices relating to the Amster distribution.
/samples: Directory containing sample scripts for export, import, and others. For more information about these files, see Amster Sample Scripts.

First steps

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

$ cd /path/to/amster
$ ./amster

Amster OpenAM Shell (version build build, JVM: version)
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.

If the amster command fails to load, make sure the JAVA_HOME environment variable is set, and that your JDK version is supported. For information on supported versions, refer to Before you install.

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 run an update command on an entity that contains a large number of key/value pairs, such as DefaultAdvancedProperties, you must provide the entire JSON body, even if you only need to update a small subset of data.

A simple way to do this is to run a read command, copy and edit the output, and paste it into the body of the update command. Alternatively, you can run export-config, copy the specific entity file to an identical empty file structure, edit the file, and call import-config setting the path to the top directory of the updated file structure.

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.

  -t, --connection-timeout
        The default timeout is 10 seconds. If specified, this parameter sets
        the timeout in seconds.

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

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

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

When a command does not proceed as expected, it can sometimes be helpful to start the amster command in debug mode and try again. To activate debug mode, start the amster command using the -d flag. For example:

$ ./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
…

While in debug mode, the amster command output shows additional information, such as connection handshakes and Groovy calls.