FAQ: Installing and using Amster in AM

FAQ

Last updated Dec 19, 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?
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. 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 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: 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:

Amster 6.5: The Amster Configuration Upgrader tool is not included in AM 6.5 as noted in the release notes: Release Notes › Important Changes to Existing Functionality. See How do I upgrade Amster configuration files when upgrading to AM 6.5? for further information on upgrading AM 6.5.
Amster 5.x and 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/OpenAM.
Amster 5.5 and later: The configuration store password must match the amadmin password if you are using an external configuration store: OPENAM-11469 (Amster install forces the admin and external config store password to be the same).
Amster 5: You cannot install AM using Amster if you have an external configuration store and SSL (LDAPS) connection: OPENAM-11890 (Amster - Installing AM with External Config Store and SSL connection (LDAPS) fails). When you trying to install AM with this setup, the install will fail while trying to create the demo user:
```
04/03/2018 13:17:49:653 PM BST: Creating demo user.
AMSetupServlet.processRequest: errorMessage:Initialization error. Unable to perform any operation.
   at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.newIdRepoException(DJLDAPv3Repo.java:2488)
   at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.createConnection(DJLDAPv3Repo.java:2547)
```
This issue is resolved in Amster 5.5.
Amster 5: You cannot create an external configuration store or user store via Amster: OPENAM-10664 (Amster does not support configuration of an external user store) and OPENAM-10689 (Installing AM using Amster failed when using an external data store ). These issues are resolved in Amster 5.5.

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:

If you have enabled secure cookies, 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/OpenAM (All versions) fails with valid username/password after enabling 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 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:

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: User Guide › 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 User Guide › Importing Configuration Data for further information.

Known issues

Configuration data cannot be imported if you have a site configured. See Only url, secondaryURLs and _id are valid in write error when importing configuration data via Amster in AM (All versions) for further information and the solution.
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 has been 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 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):

Amster 6 and later: you can use expressions, which support property value substitution in configuration files as detailed in User Guide › Using Configuration Expressions in Exported Configuration Files.
Amster 5.x: you can use variables when importing configuration data using the import-config command as described in User Guide › Using Variables in Exported Configuration Files. Variables are deprecated in Amster 6.

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