ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: Installing and using Amster in AM

Last updated Jan 11, 2023

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing and using Amster in AM.

Frequently asked questions

Q. Do I need to upgrade Amster when I upgrade AM?

A. Yes, you should always upgrade Amster to the corresponding version when you upgrade AM. This is stated in the release notes: What's New.

Q. Are there any known issues with installing Amster?

A. No, there are no known issues to be aware of when installing Amster. See What Is Amster? for further information.

Q. Are there any known issues with installing AM using Amster?

A. Yes, you should be aware of the following known install issues:

You should also refer to Install Amster for further information.

Q. How do I connect to Amster?

A. You can either connect interactively or by using a private key pair (RSA or ECDSA key files) as described in Connect to AM.

Secure cookies

If you have enabled secure cookies, you should be aware of the following (this applies to both interactive and private key connections):

Private key connections

If you choose to use the private key connection (non-interactive), you should be aware of the following:

  • You should use self-signed certificates and either import them into the JVM's cacerts keystore on the Amster client or run the amster command specifying the truststore containing the certificate and its type.
  • AM 6.x: If you use the default RSA key, you must delete the following from authorized_keys to connect locally if AM is not listening on localhost: from=",::1" This is a known issue: OPENAM-11134 (Amster: Remove the 'from' option in authorized_keys), which is resolved in AM 7.

Q. Can I install the transport key into keystore.jks?

A. No you must install it into the keystore.jceks as stated in the documentation: Create Transport Keys to Export Configuration Data. The transport key needs to be a symmetric key, which cannot be stored in JKS keystores.

Q. How can I troubleshoot my SSL connection if it fails?

A. If you experience an issue connecting to the AM instance over HTTPS, you can use one of the following options to help you troubleshoot:

  • Run Amster with the following debug options: $ ./amster -d -Djavax.net.debug=all
  • Use the following openssl command to provide information about the SSL connection as well as attempt a SSL handshake: $ openssl s_client -connect [hostname:port] -showcerts

Q. How do I view and set AM server defaults using Amster?

A. You should use the DefaultXX entities to view and set server defaults. For example, if you want to read the default server advanced properties, you would use the following command:

am> read DefaultAdvancedProperties --global

See How do I update property values in AM (All versions) using Amster? for a worked example on setting default server security properties.

If you want to configure settings for specific servers, you should use the corresponding entity without the Default prefix. For example, the AdvancedProperties entity is the equivalent of the DefaultAdvancedProperties entity for specific servers. See Entity Reference for further information.

Q. How do I make changes to configuration using Amster read and update commands?

A. You can use Amster read and update commands to update configuration in AM. See How do I update property values in AM (All versions) using Amster? for further information.

Q. Is there any best practice advice or examples for exporting and importing via Amster

A. The Amster Amster User guide provides information and command-line usage examples for exporting and importing configuration data. See Amster Export Configuration and Amster Import Configuration for example commands and options.

Additionally, you should follow these guidelines to avoid common issues:

Known issues

Q. Can I import encrypted passwords?

A. No, you should import passwords in plain text. Providing AM is correctly configured and you have the required transport key installed, the password will then be encrypted. Subsequent exports will include the encrypted password.

See Create Transport Keys to Export Configuration Data for further information.

Q. How do I use variables with Amster?

A. You can use the following types of variables with Amster:

Amster expressions

You can use expressions, which support property value substitution in configuration files as detailed in Using Configuration Expressions in Exported Configuration Files.

Shell variables

Shell variables can be made available as Java® system properties by using the -D parameter as demonstrated in Scripting.

Amster also supports shell redirection, which allows you to use here documents. For example:

#!/bin/sh export_path=/tmp/export amster <<-EOF connect -k amster_rsa https://am.example.com:8443/am export-config --path $export_path EOF

Groovy variables

The Amster shell provides support for Groovy variable assignment. See groovysh — the Groovy command -like shell - variables for further information.

Q. Are variables preserved as placeholders when you do an export?

A. No. Any variables in your configuration are output as values in the export. If you update the exported configuration to include variables, they will be overwritten on the next export.

Q. How do I prevent variable values (such as credentials) being output to the command line?

A. The underlying Groovy shell (groovysh) used by Amster provides support for quiet mode. You can suppress the output of variable values by adding -q to your command. This will not suppress the output of useful information.

Q. Can I execute Amster via a shell script without user intervention?

A. Yes, you can call a script directly from the command line by running Amster followed by the script you want Amster to load, for example:

$ ./amster myScript.amster

Where myScript.amster is the script that contains the Amster commands.


Here is an example of a simple script that installs AM and then quits once complete (no user interaction):

install-openam --serverUrl https://am.example.com:8443/am --adminPwd password --policyAgentPwd agentPassword --cookieDomain .example.com --cfgDir /home/openam --acceptLicense :exit

Q. Can I use Amster commands within Groovy functions or inside a loop context?

A. You can by using the eval(String) function. See Scripting for example uses.

Resolved RFE: OPENAM-11197 (Amster not usable inside groovy functions or not scriptable with loops ).

See Also

How do I enable debug mode for troubleshooting Amster (All versions)?

502 Bad Gateway error when an Amster (All versions) command fails

Using Amster in AM

Amster User guide

Related Training


Related Issue Tracker IDs

OPENAM-11807 (Amster - Delegated administration for Subrealm Configuration)

OPENAM-11773 (amster throws missleading error '502 bad gateway')

OPENAM-11457 (When importing session.json with amster --clean a failure occurs and sesson.json is not imported)

OPENAM-11379 (Have the amster exported JSON ordered)

Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.