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 (\) 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 http://openam.example.com:8080/openam -k /home/forgerock/am/amster_rsa
  :exit

$ ./amster samples/myScript.amster
Amster OpenAM Shell (7.0.2 build 95de0e129b, JVM: 1.8.0_151)
Type ':help' or ':h' for help.
--------------------------------------------------------------------------------
  am>:load samples/myScript.amster
===> true

Tip

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\"}'")

Note

Amster includes a number of example scripts in the /path/to/amster/samples directory. For more information, see "Amster Sample Scripts".

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:/Library/Frameworks/Python.framework/Versions/3.6/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/munki:/opt/X11/bin:/Users/ForgeRock/tools/maven/bin, SHELL:/bin/bash, JAVA_HOME:/Library/Java/JavaVirtualMachines/jdk1.8.0_92.jdk/Contents/Home/, 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/openam

am> 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(TM) SE Runtime Environment, AM_URL:http://openam.example.com:8080/openam, sun.boot.library.path:/Library/Java/JavaVirtualMachines/jdk1.8.0_92.jdk/Contents/Home/jre/lib, java.vm.version:25.92-b14, gopherProxySet:false, java.vm.vendor:Oracle Corporation, java.vendor.url:http://java.oracle.com/, 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
http://openam.example.com:8080/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:http://openam.example.com:8080/openam, smtpPort:1342, amsterKey:/root/openam/amster_rsa, exportPath:/root/am-config, myShell:/bin/bash]
Read a different version of :