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.

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/am

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

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.

PingAM

First steps