--- title: Install Amster description: Amster is a standalone client that doesn't need any other Ping Advanced Identity Software component to run. Before you install, check the following prerequisites: component: pingam version: 8.1 page_id: pingam:amster:install-amster canonical_url: https://docs.pingidentity.com/pingam/8.1/amster/install-amster.html page_aliases: ["user-guide:amster-install.adoc"] section_ids: sec-prerequisites: Prerequisites install_process: Install process amster-firststeps: First steps --- # Install Amster ## Prerequisites Amster is a standalone client that doesn't need any other Ping Advanced Identity Software component to run. Before you install, check the following prerequisites: * Amster requires a Java developer environment. Check the output of the `java -version` command to make sure your version is supported. * The `JAVA_HOME` environment variable must be set. ## Install process The [Ping Identity Download Center](https://backstage.pingidentity.com/downloads/browse/am/featured) hosts downloadable versions of Amster. For each release of AM you can download Amster as a `.zip` file. Download `Amster-8.1.0.zip` and extract it in the file system directory where you want to run it: ``` $ unzip ~/Downloads/Amster-8.1.0.zip -d /path/to/ ``` > **Collapse: 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` > > Ping's Amster terms of license. > > * `amster-8.1.0.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. Learn more in [Amster sample scripts](usage-examples.html#amster-samples). ## 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](../entity-reference/sec-amster-entity-defaultadvancedproperties.html#sec-amster-entity-defaultadvancedproperties-global-ops-update), 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] 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. |