Import configuration data

Amster can import configuration data to an AM instance. Import configuration data by using the import-config command.

A successful import overwrites any configuration that already exists in the target AM instance.

Before importing configuration data to an AM instance, consider the following points:

  • You must connect to the AM instance where you will import the configuration data after starting the Amster command-line interface. For information, refer to Connect to AM.

  • You must ensure that the configuration data you are trying to import is compatible with the version of AM you have deployed.

    For example, do not try to import configuration data exported from an AM 5 instance into an AM 6.5 instance.

  • AM validates that external data stores are configured and available when creating connections to them, including when importing using Amster.

    You must ensure that each external datastore configured in the source instance has an equivalent datastore available and running before importing Amster configuration into the destination AM instance.

  • When importing a full set of configuration data from an instance of AM, specify the --clean option to remove configuration settings from the target instance.

    The --clean option removes the following items from the target AM instance:

    • Realms, other than the Top Level Realm.

    • Authentication chains and modules.

    • Server and site settings, other than the current server.

    • Services.

    • Secret ID Mappings and secret definitions.

    • Scripts.

    • Audit settings.

    • Policies, policy sets and resource types.

    • Identity store configuration.

    • Agents, and agent groups.

    Do not use the --clean option if you are only importing a partial Amster export.

    The target AM instance may not have the settings required to start up and operate if you do not replace the deleted settings by importing a complete set of configuration.

  • By default, Amster configures the value of the property as the value of the server ID.

    To override the default during import, prefix the new value with override-server-id: in the configuration files. For example:

    "" : "override-server-id:myLBCookieValue"
  • To import encrypted password values in the configuration files you must install the transport key used to encrypt the data. For more information, refer to Create transport keys to export configuration data.

  • You must ensure that any special characters in names and passwords in Amster shell variables are escaped as required by the Groovy language.

    For example, the dollar $ character is a special character in Groovy. The following are two possible ways of escaping the $ character:"/pa$$word/"'pa\\$\\$word'

    Note that you cannot use variables, such as ${varname}, or configuration expressions, such as &{varname} if you convert a double-quoted string into a single-quoted string.

    Refer to the Groovy documentation for more information on escaping special characters in strings.


am> import-config --path Path [options]
--path Path

The path containing configuration files to import.

Specify a directory to import from all correctly-formatted JSON files within that directory and recurse through each sub-directory, or specify an individual JSON file.


--failOnError [true|false]

If specified, the import process halts if an error occurs.

Default: false

--clean [true|false]

If specified, all configuration data is removed from the target AM instance before the import is performed.

Only set this option to true when importing a full set of configuration files into a new AM instance. Otherwise, the target instance may not function correctly.

Default: false


Before trying the following examples, start the Amster command-line interface, and connect to the AM instance where you will import the configuration data.

For information on connecting to AM instances, refer to Connect to AM.

This example cleans all configuration from the target AM instance before importing a full set of configuration data, but will not halt the import if an error occurs.

am> import-config --path /tmp/myExportedConfigFiles --clean true --failOnError false
Cleaning global settings
Deleting JSON: Global JSON Handler
Deleting Scripting: 9de3eb62-f131-4fac-a294-7bd170fd4acb
Deleting Scripting: 7e3d7067-d50f-4674-8c76-a3e13a810c33
Deleting Scripting: c827d2b4-3608-4693-868e-bbcf86bd87c7
Global settings cleaned
Importing directory /tmp/myExportedConfigFiles
Import completed successfully
Copyright © 2010-2024 ForgeRock, all rights reserved.