Scripts
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
|
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.
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]