FAQ

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?
Q. Are there any known issues with installing Amster?
Q. Are there any known issues with installing AM using Amster?
Q. How do I connect to Amster?
Q. Can I install the transport key into keystore.jks?
Q. How can I troubleshoot my SSL connection if it fails?
Q. How do I view and set AM server defaults using Amster?
Q. Is there any best practice advice or examples for exporting and importing via Amster?
Q. Can I import encrypted passwords?
Q. How do I use variables with Amster?
Q. Are variables preserved as placeholders when you do an export?
Q. How do I prevent variable values (such as credentials) being output to the command line?
Q. Can I execute Amster via a shell script without user intervention?
Q. Can I use Amster commands within Groovy functions or inside a loop context?

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:

Amster 6.5 and later: The Amster Configuration Upgrader tool is not included in AM 6.5 and later as noted in the release notes: Amster 6.5 Important Changes to Existing Functionality. See How do I upgrade Amster configuration files when upgrading to AM 6.5.x or 7? for further information on upgrading AM 6.5 and later.
Amster 6: You can only install a single instance of AM using Amster: OPENAM-10667 (Amster should be able to add second instance of AM to existing one). This issue is fixed in AM 6.5; if you want to install multiple instances in a site in earlier versions, you should use the configurator.jar tool and refer to FAQ: Configuring AM.

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):

You must connect to Amster using a secured HTTPS connection, otherwise the connection will succeed but subsequent commands will fail. This is a similar issue to Login to AM (All versions) fails with valid username/password after enabling Secure cookies.
If AM is listening on HTTP and you want to do an export, you may need to temporarily disable secure cookies, take the export and then re-enable secure cookies.

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="127.0.0.0/24,::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:

File permissions for the folder and files containing the exported configuration are set appropriately to allow Amster to read the files. Currently, Amster reports a success if it does not have appropriate file permissions: OPENAM-12455 (If file permissions do not allow Amster to read config files it does not handle it).
Configuration data is being exported from and imported to the same AM instance. You will encounter an error if you export from one server and then try to import the configuration on a different server, unless the configuration is correctly manipulated for this purpose or imported as part of a process to clone an AM Instance: Cloning an Access Management Instance.
Custom authentication modules are installed and registered before you attempt an import. See How do I import Service configurations in AM (All versions) using Amster when there are custom modules? for further information.
Authentication chains do not have the same names as authentication modules.
Special characters in names and passwords in Amster shell variables are escaped as required by the Groovy language. See Import Configuration Data for further information.

Known issues

Configuration data cannot be imported if you have a site configured in pre-AM 6.5.3. See Only url, secondaryURLs and _id are valid in write error when importing configuration data via Amster in AM 6.0.x, 6.5.0.x, 6.5.1 and 6.5.2.x for further information and the solution. This is resolved in AM 6.5.3 and later.
Configuration data cannot be exported for REST STS instances: OPENAM-11671 (Amster exports are missing several services)
You may see the following error in your logs when you import via Amster: ERROR: Invalid server property org.forgerock.amster.com.iplanet.am.lbcookie.value com.sun.identity.common.configuration.UnknownPropertyNameException: Unidentified property, org.forgerock.amster.com.iplanet.am.lbcookie.value. This error doesn't cause the import to fail and can be ignored. See OPENAM-13590 (Document or Improve Amster for org.forgerock.amster.com.iplanet.am.lbcookie.value ) for further information. This issue is fixed in AM 6.5.

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
Shell variables
Groovy variables

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.

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)