Untitled :: Amster

Release Notes

Amster is a lightweight command-line interface, ideal for use in DevOps processes, such as continuous integration and deployment.

Read these release notes before you install Amster. The information contained in these release notes cover prerequisites for installation, known issues and improvements to the software, changes and deprecated functionality, and other important information.

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

What’s New

This page covers new features and improvements in Amster.

Amster 7.1.4 is the latest minor release targeted for AM 7.1 deployments. Download Amster 7.1.4 from the ForgeRock Backstage website.

Amster 7.1.4

No new features were added in Amster 7.1.4

Use this Amster version with the corresponding version of AM.

Amster 7.1.3

No new features were added in Amster 7.1.3

Use this Amster version with the corresponding version of AM.

Amster 7.1.2

No new features were added in Amster 7.1.2

Use this Amster version with the corresponding version of AM.

Amster 7.1.1

No new features were added in Amster 7.1.1

Use this Amster version with the corresponding version of AM.

Amster 7.1

Support for AM 7.1 or Later Only

Amster 7.1 supports exporting and importing configuration from AM 7.1.

If you have a previous version of Amster:
1. Perform a fresh installation of Amster 7.1.
  
  For more information, see Install Amster.
2. Migrate any Amster Groovy scripts from the previous Amster installation.
  
  Take into account any changes in functionality.
3. Convert any JSON configuration files that were exported from AM 5 or later.
  
  The AM 7.1 ZIP file includes a configuration file upgrade tool. For more information on converting configuration files for import into AM 7.1, see the README.md file in the Config-Upgrader-7.1.0.zip file.
4. Test the new Amster installation.
5. Delete the previous Amster installation.

Before you install

This page covers software and hardware prerequisites for installing and running Amster.

ForgeRock supports customers using the versions specified here. Other versions and alternative environments might work as well. When opening a support ticket for an issue, however, make sure you can also reproduce the problem on a combination covered here.

Supported host operating systems
Operating System	Versions
Red Hat Enterprise Linux, Centos	7, 8
Amazon Linux	2018.03, 2
SuSE	12, 15
Ubuntu	18.04 LTS, 20.04 LTS, 22.04
Windows Server	2016, 2019

Supported Java versions
Vendor	Versions⁽¹⁾
OpenJDK, including OpenJDK-based distributions: AdoptOpenJDK/Eclipse Temurin Java Development Kit (Adoptium) Amazon Corretto Azul Zulu Red Hat OpenJDK ForgeRock tests most extensively with AdoptOpenJDK/Eclipse Temurin. ForgeRock recommends using the HotSpot JVM.	11, 17
Oracle Java	11, 17

⁽¹⁾ Always use a JVM with the latest security fixes.

Special requests

If you have a special request regarding support for a combination not listed here, contact ForgeRock at info@forgerock.com.

Changes to Existing Functionality

This page covers critical and important changes to existing functionality.

This section lists changes made to existing functionality in Amster.

Amster 7.1.3

No changes have been made to existing functionality in Amster 7.1.3.

Amster 7.1.2

No changes have been made to existing functionality in Amster 7.1.2.

Amster 7.1.1

No changes have been made to existing functionality in Amster 7.1.1.

Amster 7.1

No changes have been made to existing functionality in Amster 7.1.

Fixes, Limitations, and Known Issues

Key Fixes

The following issues are fixed in this release. For details, see the OpenAM issue tracker.

Amster 7.1.4

OPENAM-19592: Unable to use Amster on an M1 MacBook

Amster 7.1.3

OPENAM-18715: Amster 7.1.1 cannot execute multi-line commands from a script while creating realm using :load option

Amster 7.1.2

No new issues have been fixed in this release.

Amster 7.1.1

OPENAM-17519 Amster 7 package contains outdated elements

Amster 7.1

OPENAM-17020: Amster import fails after removing identity store and setting User Profile to ignore
OPENAM-17072: eval(String) function in Amster shell results in MissingMethodException

Limitations

The following important issues remained open at the time release 7.1 became available:

No support for load balanced deployments

Amster cannot connect to a load balancer URL. You must connect Amster directly to a single AM instance. Using a load balancer could send sequential commands to different AM instances, and could result in concurrency issues when writing to the underlying configuration store.
Bulk import to external application stores with affinity

If affinity is enabled for an external application data store, bulk import intermittently fails with errors similar to the following:

/Resource path 'http////////eea87a38e3ca476fa93a3669375ada3a' contains empty path elements

Before using Amster for a bulk import to an application store, disable data store affinity, or remove the load balancer from the application store deployment. You can re-enable affinity when the import has completed.
Importing resources containing slash characters can fail

Some Access Management resources have names that can contain slash characters (/), for example policy names, application names, and SAML v2.0 entities. These slash characters can cause unexpected behavior and failures in Amster when importing into Access Management instances running on Apache Tomcat.

To work around this issue, configure Apache Tomcat to allow encoded slash characters by updating the CATALINA_OPTS environment variable. For example:

On Unix/Linux systems:
```
$ export CATALINA_OPTS= \
  "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
$ startup.sh
```
On Windows systems:
```
C:\> set CATALINA_OPTS= ^
  "-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true"
C:\> startup.bat
```
It is strongly recommended that you do not enable org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH when running AM in production as it introduces a security risk on Apache Tomcat.

For more information, see How do I safely enable the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH setting in AM/OpenAM (All Versions)? in the ForgeRock Knowledge Base.

[INFO] Messages Showing On SuSE On Amster Start Up

Running Amster on SuSE may produce [INFO] messages, for example:

# ./amster
[INFO] Unable to bind key for unsupported operation: up-history
[INFO] Unable to bind key for unsupported operation: down-history
[INFO] Unable to bind key for unsupported operation: up-history
[INFO] Unable to bind key for unsupported operation: down-history
OpenAM Shell (version build build, JVM: version)
Type ':help' or ':h' for help.
-----------------------------------------------------
am>

These messages are caused by the keyboard mappings configured in the /etc/inputrc file and can safely be ignored, as they do not affect functionality.

Known Issues

Amster 7.1

Amster 7.1.4

OPENAM-21278: Amster doesn’t use the system console correctly for interactive mode
OPENAM-21277: Running Amster in debug mode doesn’t work on Windows
OPENAM-21180: Amster should set file encoding to UTF-8 internally
OPENAM-19668: Amster export-config shows errors for Google components
OPENAM-19666: Amster gets stuck if you input a line that ends with a colon character (:)
OPENAM-19580: Amster export-config returns default values instead of empty values
OPENAM-19529: Amster doesn’t export non-global service schema defaults
OPENAM-19216: Amster Entity Reference: Incorrect Site update schema
OPENAM-18963: Amster can’t import WS-Federation metadata
OPENAM-18715: Amster can’t create a realm if the script has many lines
OPENAM-17909: Exported SAML metadata doesn’t include the KeyDescriptor if there is no entity-specific secretID
OPENAM-17743: Amster sms.transport.key causes performance issues if it’s left in the keystore
OPENAM-14478: Running Amster with JDK 11 shows warnings such as Illegal reflective access by org.codehaus.groovy.vmplugin.v7.Java7$1

Documentation Updates

The following table tracks changes to the documentation set following the release of Amster 7.1:

Documentation Change Log
Date	Description
2023-07-11	Release of Amster 7.1.4
2022-10-13	Release of Amster 7.1.3 In addition to updates to these release notes, the following change was made to the documentation: Described how to check for errors when running in scripts.
2022-03-15	Release of Amster 7.1.2
2021-12-06	Release of Amster 7.1.1
2021-05-12	Release of Amster 7.1.

Getting support

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock’s support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.

ForgeRock publishes comprehensive documentation online:

The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

While many articles are visible to everyone, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.
ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.