Action Runners

An action runner is the execution environment for user-implemented actions. StackStorm comes with pre-canned action runners such as a remote runner and shell runner which provide for user-implemented actions to be run remotely (via SSH) and locally. The objective is to allow the Action author to concentrate only on the implementation of the action itself rather than setting up the environment.

Quick Reference

Here is a quick reference of the most used runner parameters. To see additional details for each runner, see the appropriate section down below.

Runner	local-shell-cmd	local-shell-script	winrm-cmd	winrm-ps-cmd	winrm-ps-script
Command	`cmd`		`cmd`	`cmd`
Destination
Credentials			`username`	`username`	`username`
			`password`	`password`	`password`

			`host`	`host`	`host`
			`port`	`port`	`port`


Access	`sudo`	`sudo`
Access	`sudo_password`	`sudo_password`
Connection

			`scheme`	`scheme`	`scheme`
			`transport`	`transport`	`transport`
			`verify_ssl_cert`	`verify_ssl_cert`	`verify_ssl_cert`
Common Flags	`cwd`	`cwd`	`cwd`	`cwd`	`cwd`
	`env`	`env`	`env`	`env`	`env`
	`kwarg_op`	`kwarg_op`	`kwarg_op`	`kwarg_op`	`kwarg_op`
	`timeout`	`timeout`	`timeout`	`timeout`	`timeout`
Debug		`content_version`
Debug		`debug`

Exit Codes

Normally the exit code of a runner is defined by the exit code of the script or command executed. All runners return timeout exit code (-9) if the command or script did not complete its execution within the specified timeout.

Local Command Runner (local-shell-cmd)

This is the local runner. This runner executes a Linux command on the host where StackStorm is running.

Note

stdout and stderr attributes in the runner result object have the last \n or \r or \r\n characters removed if present. This is done so you can re-use the result of common commands that include a trailing line break of carriage return, such as uptime, whoami, etc., in other actions and workflows. If you have an action which requires a trailing line break character to be present, you can add it explicitly to the result, e.g. echo -e 'test\n' (this will result into two line break characters and only one of them will be stripped/removed from the result).

Runner Parameters

cmd (string) - Arbitrary Linux command to be executed on the host.
cwd (string) - Working directory where the command will be executed in
env (object) - Environment variables which will be available to the command(e.g. key1=val1,key2=val2)
kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-“.
sudo (boolean) - The command will be executed with sudo.
sudo_password (string) - Sudo password. To be used when passwordless sudo is not allowed.
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.

Local script runner (local-shell-script)

This is the local runner. Actions are implemented as scripts. They are executed on the host where StackStorm is running. The last newline character is stripped from stdout and stderr fields in the output.

Runner Parameters

debug (boolean) - Enable runner debug mode.
content_version (string) - Git revision of the pack content to use for this action execution (git commit sha / tag / branch). Only applies to packs which are git repositories.
cwd (string) - Working directory where the script will be executed in
env (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)
kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-“.
sudo (boolean) - The command will be executed with sudo.
sudo_password (string) - Sudo password. To be used when passwordless sudo is not allowed.
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.

Remote Command Runner (remote-shell-cmd)

This is a remote runner. This runner executes a Linux command on one or more remote hosts provided by the user. The last newline character is stripped from stdout and stderr fields in the output.

Note

By default StackStorm uses passwordless sudo for to execute commands on local and remote systems, using the system user (by default stanley). In addition to passwordless sudo, local and remote runners also support password protected sudo via the sudo_password runner parameter.

With the remote runner, the sudo password is passed to the sudo command as a command line argument. This means it has some security implications - if bash history is enabled for the system user, the sudo password will be saved in bash history and any system user with access to that user bash history file will be able to view it.

Runner Parameters

bastion_host (string) - The host SSH connections will be proxied through. Note: This connection is made using the same parameters as the final connection.
cmd (string) - Arbitrary Linux command to be executed on the remote host(s).
cwd (string) - Working directory where the script will be executed in
dir (string) - The working directory where the script will be copied to on the remote host.
env (object) - Environment variables which will be available to the command(e.g. key1=val1,key2=val2)
hosts (string) - A comma delimited string of a list of hosts where the remote command will be executed. For example: example1.com,example2.com,example3.com:5555
kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-“.
parallel (boolean) - Default to parallel execution.
passphrase (string) - Passphrase for the private key, if needed.
password (string) - Password used to log in. If not provided, private key from the config file is used.
port (integer) - SSH port. If not specified as part of the hosts list, default port will be used (22).
private_key (string) - Private key material or path to the private key file on disk used to log in.
sudo (boolean) - The remote command will be executed with sudo.
sudo_password (string) - Sudo password. To be used when passwordless sudo is not allowed.
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
username (string) - Username used to log-in. If not provided, default username from config is used.

Note

If a value you specify for the private_key parameter is a path to the private key file, you need to make sure that the user under which action runner process is running (stanley by default) has read access to this key file. This private key file also needs be deployed and present in the same location on all the servers where action runner component is running.

In addition to that, if you utilize path to the private key file functionality, you are strongly encouraged to disable local runner in the config. If you don’t do that, any StackStorm user which has access to core.local action will be able to read this key and this can pose a security risk.

Remote script runner (remote-shell-script)

This is a remote runner. Actions are implemented as scripts. They run on one or more remote hosts provided by the user. The last newline character is stripped from stdout and stderr fields in the output.

Runner Parameters

bastion_host (string) - The host SSH connections will be proxied through. Note: This connection is made using the same parameters as the final connection.
cwd (string) - Working directory where the script will be executed in.
dir (string) - The working directory where the script will be copied to on the remote host.
env (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)
hosts (string) - A comma delimited string of a list of hosts where the remote command will be executed. For example: example1.com,example2.com,example3.com:5555
kwarg_op (string) - Operator to use in front of keyword args i.e. “–” or “-“.
parallel (boolean) - Default to parallel execution.
passphrase (string) - Passphrase for the private key, if needed.
password (string) - Password used to log in. If not provided, private key from the config file is used.
port (integer) - SSH port. If not specified as part of the hosts list, default port will be used (22).
private_key (string) - Private key material to log in. Note: This needs to be actual private key data and NOT path.
sudo (boolean) - The remote command will be executed with sudo.
sudo_password (string) - Sudo password. To be used when passwordless sudo is not allowed.
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
username (string) - Username used to log-in. If not provided, default username from config is used.

Note

If a value you specify for the private_key parameter is a path to the private key file, you need to make sure that the user under which action runner process is running (stanley by default) has read access to this key file. This private key file also needs be deployed and present in the same location on all the servers where action runner component is running.

In addition to that, if you utilize path to the private key file functionality, you are strongly encouraged to disable local runner in the config. If you don’t do that, any StackStorm user which has access to core.local action will be able to read this key and this can pose a security risk.

Windows Command Runner (windows-cmd)

Note

Windows runners are DEPRECATED as of version 2.9. These runners are replaced by WinRM Runners which use a native Python implementation of the WinRM protocol. Please migrate all existing actions over to these new runners. Any new code should prefer WinRM Runners over the Windows Runners.

The legacy Windows runners will be REMOVED in version 3.1.

The Windows command runner allows you to run the command-line interpreter (cmd) and PowerShell commands on Windows hosts.

For more information on enabling and setting up the Windows runner, please see the following section - Windows Runners Configuration.

Runner Parameters

username (string) - Username used to log-in.
cmd (string) - Arbitrary command to be executed on the remote host.
host (string) - Host to execute the command on
password (string) - Password used to log in.
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.

Windows Script Runner (windows-script)

Note

Windows runners are DEPRECATED as of version 2.9. These runners are replaced by WinRM Runners which use a native Python implementation of the WinRM protocol. Please migrate all existing actions over to these new runners. Any new code should prefer WinRM Runners over the Windows Runners.

The legacy Windows runners will be REMOVED in version 3.1.

Windows script runner allows you to run PowerShell scripts on Windows hosts.

For more information on enabling and setting up the Windows runner, please see the following section - Windows Runners Configuration.

Runner Parameters

username (string) - Username used to log-in.
host (string) - Host to execute the command on
password (string) - Password used to log in.
share (string) - Name of the Windows share where script files are uploaded
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.

WinRM Command Runner (winrm-cmd)

The WinRM command runner allows you to run the command-line interpreter (cmd) commands on Windows hosts using the WinRM protocol.

For more information on enabling and setting up the WinRM runner, please see the following section - WinRM Runners Configuration.

Runner Parameters

cmd (string) - Arbitrary Command Prompt command to be executed on the remote host.
cwd (string) - Working directory where the command will be executed in
env (object) - Environment variables which will be available to the command (e.g. key1=val1,key2=val2)
host (string) - A host where the command will be run
kwarg_op (string) - Operator to use in front of keyword args i.e. “-” or “/”.
password (string) - Password used to log in.
port (integer) - WinRM port to connect on. If using port 5985 scheme must be “http”
scheme (string) - Scheme to use in the WinRM URL. If using scheme “http” port must be 5985
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
transport (string) - The type of transport that WinRM will use to communicate. See https://github.com/diyan/pywinrm#valid-transport-options
username (string) - Username used to log-in.
verify_ssl_cert (boolean) - Certificate for HTTPS request is verified by default using requests CA bundle which comes from Mozilla. Verification using a custom CA bundle is not yet supported. Set to False to skip verification.

WinRM PowerShell Command Runner (winrm-ps-cmd)

The WinRM PowerShell command runner allows you to run the PowerShell commands on Windows hosts using the WinRM protocol.

For more information on enabling and setting up the WinRM runner, please see the following section - WinRM Runners Configuration.

Runner Parameters

cmd (string) - Arbitrary PowerShell command to be executed on the remote host.
cwd (string) - Working directory where the command will be executed in
env (object) - Environment variables which will be available to the command (e.g. key1=val1,key2=val2)
host (string) - A host where the command will be run
kwarg_op (string) - Operator to use in front of keyword args i.e. “-” or “/”.
password (string) - Password used to log in.
port (integer) - WinRM port to connect on. If using port 5985 scheme must be “http”
scheme (string) - Scheme to use in the WinRM URL. If using scheme “http” port must be 5985
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
transport (string) - The type of transport that WinRM will use to communicate. See https://github.com/diyan/pywinrm#valid-transport-options
username (string) - Username used to log-in.
verify_ssl_cert (boolean) - Certificate for HTTPS request is verified by default using requests CA bundle which comes from Mozilla. Verification using a custom CA bundle is not yet supported. Set to False to skip verification.

WinRM PowerShell Script Runner (winrm-ps-script)

WinRM PowerShell script runner allows you to run PowerShell scripts on Windows hosts. To specify what script to execute, use the entry_point option in the Action metadata file.

For more information on enabling and setting up the WinRM runner, please see the following section - WinRM Runners Configuration.

Runner Parameters

cwd (string) - Working directory where the command will be executed in
env (object) - Environment variables which will be available to the command (e.g. key1=val1,key2=val2)
host (string) - A host where the command will be run
kwarg_op (string) - Operator to use in front of keyword args i.e. “-” or “/”.
password (string) - Password used to log in.
port (integer) - WinRM port to connect on. If using port 5985 scheme must be “http”
scheme (string) - Scheme to use in the WinRM URL. If using scheme “http” port must be 5985
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
transport (string) - The type of transport that WinRM will use to communicate. See https://github.com/diyan/pywinrm#valid-transport-options
username (string) - Username used to log-in.
verify_ssl_cert (boolean) - Certificate for HTTPS request is verified by default using requests CA bundle which comes from Mozilla. Verification using a custom CA bundle is not yet supported. Set to False to skip verification.

HTTP Runner (http-request)

HTTP runner works by performing HTTP request to the provided URL.

Runner Parameters

allow_redirects (boolean) - Set to True if POST/PUT/DELETE redirect following is allowed.
cookies (object) - Optional cookies to send with the request.
headers (object) - HTTP headers for the request.
http_proxy (string) - URL of HTTP proxy to use (e.g. http://10.10.1.10:3128).
https_proxy (string) - URL of HTTPS proxy to use (e.g. http://10.10.1.10:3128).
password (string) - Password required by basic authentication.
url (string) - URL to the HTTP endpoint.
username (string) - Username required by basic authentication.
verify_ssl_cert (boolean) - Certificate for HTTPS request is verified by default using requests CA bundle which comes from Mozilla. Verification using a custom CA bundle is not yet supported. Set to False to skip verification.
url_hosts_blacklist (array) - Optional list of hosts (network locations) to blacklist (e.g. example.com, 127.0.0.1, ::1, etc.). If action will try to access that endpoint, an exception will be thrown and action will be marked as failed.
url_hosts_whitelist (array) - Optional list of hosts (network locations) to whitelist (e.g. example.com, 127.0.0.1, ::1, etc.). If specified, actions will only be able to hit hosts on this whitelist.

Keep in mind that other parameters such as body, method, headers, etc. are defined as part of the core.http action.

Runner Result

The result object from this runner contains the following keys:

status_code (integer) - Response status code (e.g. 200, 404, etc.)
body (string/object) - Response body. If the response body contains JSON and the response Content-Type header is application/json, the body will be automatically parsed as JSON.
parsed (boolean) - Flag which indicates if the response body has been parsed.
headers - Response headers.

Python Runner (python-script)

This is a Python runner. Actions are implemented as Python classes with a run method. They run locally on the machine where st2actionrunner is running.

Python runner actions return an execution status (success, failure) by returning a tuple from the Python action class run() method. The first item in this tuple is a boolean flag indicating success/failure and the second one is the result. However, execution status is optional i.e. the return value from action runner can either be a tuple of success status and result or just the result object.

Runner Parameters

debug (boolean) - Enable runner debug mode.
content_version (string) - Git revision of the pack content to use for this action execution (git commit sha / tag / branch). Only applies to packs which are git repositories.
env (object) - Environment variables which will be available to the script.
timeout (integer) - Action timeout in seconds. Action will get killed if it doesn’t finish in timeout seconds.
log_level (string) - Default log level for Python runner actions.

Runner Result

The return value from this action runner is a tuple consisting of a boolean flag indicating success/failure and the second one is the result:

status (boolean) - Flag indicating action’s success, i.e. Succeeded status is True/False. Note: This is an optional flag.
result (object) - result returned by the action based on success or failure.

The status flag allows users to return a result from a failing action. When the status flag is not used the only way for action to be considered as failed is to throw an exception or exit with a non-zero exit code.

ActionChain Runner (action-chain)

ActionChain is a no-frills linear workflow, providing a simple chain of action invocations. For more information, please refer to the Workflows and ActionChain section of documentation.

Runner Parameters

display_published (boolean) - Intermediate published variables will be stored and displayed.
skip_notify (array) - List of tasks to skip notifications for.