Scripting

You can create script files containing a series of commands and variable declarations, which can be loaded and executed within Amster.

Start each separate command or variable declaration on a new line. Use the backslash (kbd:[\]) character to represent line continuations.

For example, the following script installs an AM instance, and then exits the Amster command-line interface:

install-openam \
 --serverUrl https://openam.example.com:8443/openam \
 --authorizedKey /var/amster/authorized_keys \
 --cookieDomain .example.com \
 --adminPwd forgerock \
 --cfgStoreHost opendj.example.com \
 --cfgStoreDirMgrPwd password  \
 --cfgStoreAdminPort 1389  \
 --cfgStore dirServer \
 --cfgDir /root/openam \
 --userStoreDirMgrPwd password \
 --userStoreHost opendj.example.com \
 --userStoreType LDAPv3ForOpenDS \
 --userStorePort 1389 \
 --userStoreRootSuffix dc=openam,dc=forgerock,dc=org \
 --acceptLicense
 :exit

To load and execute the commands within a script, use the :load command, as follows:

am> :load myScript.amster

You can specify more than one script to load. Scripts are loaded and executed in the order they are specified. If a command in a script fails, execution continues with the next command.

You can also invoke scripts by passing them as a parameter to the amster command.

For example:

$ vi samples/myScript.amster
  connect https://openam.example.com:8443/openam -k /home/forgerock/am/amster_rsa
  :exit
$ ./amster samples/myScript.amster

Amster OpenAM Shell (version build build, JVM: version)
Type ':help' or ':h' for help.
--------------------------------------------------------------------------------
am> :load samples/myScript.amster

===> true

The Amster shell supports an eval(String) function, which evaluates any Amster command expressed as a string. For example, the function is required within looping structures:

for (i = 0; i < 4; i++) {
    eval("create DataStoreModule --realm / --body '{\"_id\":\"myDataStore$i\"}'")
 }

You must also use the eval(String) function when using Amster commands in conditional structures:

dbStatus = databaseName
    ? 'Found'
    : eval("create DataStoreModule --realm / --body '{\"_id\":\"myDataStore\"}'")

Amster includes a number of sample scripts in the /path/to/amster/samples directory.

Check for errors when running in scripts

There is no way to exit with a non-zero status code when an amster command produces a result other than success.

To monitor amster command errors, send the command output to a file, then search that file for success or failure conditions.

For example:

$ ./amster samples/myScript.amster >> myOutputfile.txt

Note that error and success messages can change between versions, so any scripts that rely on these messages should be reviewed during upgrades.

Using Variables in Amster Scripts

When scripting Amster tasks, it is often useful to use variables. An example would be storing the AM connection string in a variable, the value of which is swapped among environments.

You can define variables in the Amster Groovy shell directly, or you can import them to the shell if they are defined as Java properties or as operating system environment variables:

Amster shell variables

Define Amster shell variables using the standard camel case notation for naming variables in Groovy. For example:

am> **smtpPort = "1342"**
===> 1342

You can define maps as shell variables, but Amster commands cannot access the contents of the map directly. Assign key values to Amster shell variables so that commands can use them. For example:

am> myMap= [ AM_URL: "https://openam.example.com:8443/openam", AMSTER_KEY: "/opt/openam/id_rsa" ]
===> [AM_URL:https://openam.example.com:8443/openam, AMSTER_KEY:/opt/openam/id_rsa]
am> myAM= myMap.AM_URL
===> https://openam.example.com:8443/openam
am> myKey= myMap.AMSTER_KEY
===> /opt/openam/id_rsa
am> connect -k myKey myAM

Operating system environment variables

Import environment variables into the Amster shell using Groovy syntax.

The following commands are examples of operations you can perform in a Groovy shell. For more information, refer to the Groovy documentation.

To see all the environment variables available for import from a Unix shell, run the following command:

am> System.getenv()
===> [PATH:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin,
         SHELL:/bin/bash, JAVA_HOME:/path/to/jvm, TERM:xterm-256color,
         USER:ForgeRock, LANG:en_GB.UTF-8, PWD:/Users/ForgeRock/amster……]

To assign the value of an environment variable to an Amster shell variable, run the following command:

am> myShell=System.getenv("SHELL")
===> /bin/bash

To assign all the environment variables to a map and then list them, run the following commands:

am> ENV=System.getenv()
===> [SHELL:/bin/bash, USER:ForgeRock, LANG:en_GB.UTF-8, PWD:/Users/ForgeRock/amster,
      AMURL:https://openam.example.com:8443/openam, CFGDIR:/opt/openam……]
am> ENV.each { println it }
SHELL:/bin/bash
USER:ForgeRock
LANG:en_GB.UTF-8
PWD:/Users/ForgeRock/amster
AMURL:https://openam.example.com:8443/openam
CFGDIR:/opt/openam
……

Amster commands cannot access the contents of a map directly; you must assign key values to Amster shell variables before commands can use them. For example:

am> myAM = ENV.AMURL
===> https://openam.example.com:8443/openam
am> myCfgDir = ENV.CFGDIR
===> /opt/openamam> install-openam --serverURL myAM --adminPWd forgerock --cfgDir myCfgDir --acceptLicense

The following is an example of an Amster script that assigns the value of environment variables to Amster shell variables:

myAM = System.getenv("AMURL")
myCfgDir = System.getenv("CFGDIR")
install-openam --serverURL myAM --adminPWd forgerock --cfgDir myCfgDir --acceptLicense
:exit

Java system properties

You can pass environment variables to the Amster shell when executing the amster command with the -D parameter.

For example, you could create the following bash script to call the amster command:

#!/bin/bash
amUrl="https://openam.example.com:8443/openam"
amsterKey="/root/openam/amster_rsa"
configPath="/root/am-config"
./amster export-config.amster -D AM_URL=${amUrl} -D AMSTER_KEY=${amsterKey} \
-D AM_CONFIG_PATH=${configPath}

To see all properties available from the Java runtime, run the following command:

am> System.getProperties()
===> [java.runtime.name:Java™ SE Runtime Environment, AM_URL:https://openam.example.com:8443/openam,
      java.vm.version:_version_, gopherProxySet:false, …, path.separator::, …]

To import the Java variables into the Groovy shell, run the following command:

am> amUrl = System.getProperty("AM_URL")
===> https://openam.example.com:8443/openam
am> amsterKey = System.getProperty("AMSTER_KEY")
===> /root/openam/amster_rsa
am> exportPath = System.getProperty("AM_CONFIG_PATH")
===> /root/am-config

You can use the variables in an Amster script by importing them in Groovy first. For example:

amUrl = System.getProperty("AM_URL")
amsterKey = System.getProperty("AMSTER_KEY")
exportPath = System.getProperty("AM_CONFIG_PATH")

connect amUrl -k amsterKey
export-config --path exportPath --failOnError
:exit

To see all the environment variables defined in the Amster shell, run the following command:

am> binding.variables.each{ println it.key println it.value }
eval
org.codehaus.groovy.runtime.MethodClosure@3f270e0a
_
/bin/bash
amUrl
https://openam.example.com:8443/openam
smtpPort
1342
amsterKey
/root/openam/amster_rsa
exportPath
/root/am-config
myShell
/bin/bash
===> [eval:org.codehaus.groovy.runtime.MethodClosure@3f270e0a, _:/bin/bash,
      amUrl:https://openam.example.com:8443/openam, smtpPort:1342,
      amsterKey:/root/openam/amster_rsa, exportPath:/root/am-config, myShell:/bin/bash]