FAQ

FAQ: Installing and using Amster in AM

Last updated Oct 12, 2018

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: Amster 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 User Guide › Getting Started with the Amster Command-line Interface 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 User Guide › Installing ForgeRock Access Management with 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 the User Guide › Connecting to ForgeRock Access Management.

Interactive connections

If you choose to use the interactive connection, you should be aware of the following:

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 have either imported 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.
  • 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).

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. Is there any best practice advice for exporting and importing via Amster?

A. The Amster User Guide provides information on exporting and importing via Amster. 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 User Guide › Creating Transport Keys for further information.

Q. How do I use variables with Amster?

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

  • Amster expressions or variables
  • Shell variables
  • Groovy variables

Amster expressions or variables

Depending on what version of Amster you are using, you can use expressions (Amster 6 and later) or variables (Amster 5.x):

Shell variables

Shell variables can be made available as Java® system properties by using the -D parameter as demonstrated in User Guide › 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  http://host1.example.com:8080/openam
        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.

Example

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

install-openam --serverUrl http://host1.example.com:8080/openam --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 as of Amster 5.5 by using the eval(String) function. See User Guide › 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

User Guide

Entity Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12398 (Memory leak in Amster Web Agent Administration)

OPENAM-12334 (Unable to create Saml2Entity using Amster)

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)

OPENAM-11197 (Amster not usable inside groovy functions or not scriptable with loops )

OPENAM-10816 (Amster - SAML2 Entity fails to import)



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.
Loading...