Note

The documentation you're currently reading is for version 2.3.0. Click here to view documentation for the latest stable version.

Quick Start

Got BWC installed? Let’s give it a try. This guide will walk you through BWC basics and help you build and run a simple automation: a rule that triggers an action on an external event.

Explore BWC with CLI

The best way to explore BWC is to use CLI. Start by firing a few commands:

st2 --version

# Get help. It's a lot. Explore.
st2 -h

# Authenticate and export the token. Make sure ST2_AUTH_URL and
# ST2_API_URL are set correctly (http vs https, endpoint, and etc).
# Replace the username and password in the example below appropriately.
export ST2_AUTH_TOKEN=`st2 auth -t -p 'pass123' admin`

# List the actions from a 'core' pack
st2 action list --pack=core
st2 trigger list
st2 rule list

# Run a local shell command
st2 run core.local -- date -R

# See the execution results
st2 execution list

# Fire a shell comand on remote hosts. Requires passwordless SSH configured.
st2 run core.remote hosts='localhost' -- uname -a

The installation deploys the CLI along with the BWC services. CLI can be used to access BWC service remotely. All BWC operations are also available via REST API, Python, and JavaScript bindings. Check the CLI and Python Client reference for details.

BWC ships with WebUI. You can access it at https://hostname.

Authenticate

If authentication is enabled, obtain authentication token with st2 auth <username>, and supply the token to each st2 command using the --token or -t parameter. For convenience, keep the credential in the CLI config file, or set the environment variable ST2_AUTH_TOKEN. When using environment variable, make sure that ST2_API_URL and ST2_AUTH_URL are set appropriately. The doc section on authentication usage contains additional notes. A nice shortcut for now is:

export ST2_AUTH_TOKEN=`st2 auth -t -p 'pass123' admin`

Work with Actions

BWC comes with several generic actions out of the box. The catalog of actions can be easily extended by getting actions from the community or consuming your existing scripts (more on that later). Browse the catalog with st2 action list. Action is referred to by ref as pack.action_name (e.g. core.local). Learn about an action by doing st2 action get <action>, or, st2 run <action> --h (--help): the command shows the description along with action parameters so that you know how to run it from the CLI or use it in rules and workflows.

# List all the actions in the library
st2 action list

# Get action metadata
st2 action get core.http

# Display action details and parameters.
st2 run core.http --help

To run the action from the CLI, do st2 run <action> key=value positional arguments.

# Run a local command
st2 run core.local -- uname -a

# HTTP REST call to st2 action endpoint
st2 run -j core.http url="https://docs.stackstorm.com" method="GET"

Use the core.remote action to run Linux commands on multiple hosts via SSH. This assumes that passwordless SSH access is configured for the hosts, as described in Configure SSH section.

st2 run core.remote hosts='abc.example.com, cde.example.com' username='mysshuser' -- ls -l

Note

For core.local and core.remote actions, we use -- to separate action parameters to ensure that options keys, like -l or -a are properly passed to the action. Alternatively, core.local and core.remote actions take the cmd parameter to pass crazily complex commands.

When specifying a command using the command line tool, you also need to escape all the variables, otherwise the variables will get interpolated locally by a shell. Variables are escaped using a backslash (\) - e.g. \$user.

# Using `--` to separate arguments
st2 run core.local -- ls -al

# Equivalent using `cmd` parameter
st2 run core.local cmd="ls -al"

# Crazily complex command passed with `cmd`
st2 run core.remote hosts='localhost' cmd="for u in bob phill luke; do echo \"Logins by \$u per day:\"; grep \$u /var/log/secure | grep opened | awk '{print \$1 \"-\" \$2}' | uniq -c | sort; done;"

Check the action execution history and details of action executions with st2 execution command:

# List of executions (recent at the bottom)
st2 execution list

# Get execution by ID
st2 execution get <execution_id>

# Get only the last 5 executions
st2 execution list -n 5

That’s it. You have learned to run BWC‘s actions. Now let’s stitch events and actions togethe with rules.

Define a Rule

BWC uses rules to fire actions or workflows when events happen. Events are typically monitored by sensors. When a sensor catches an event, it fires a trigger. Trigger trips the rule, the rule checks the criteria and if it matches, it runs an action. Easy enough. Let’s look at an example.

Sample rule: sample_rule_with_webhook.yaml :

---
    name: "sample_rule_with_webhook"
    pack: "examples"
    description: "Sample rule dumping webhook payload to a file."
    enabled: true

    trigger:
        type: "core.st2.webhook"
        parameters:
            url: "sample"

    criteria:
        trigger.body.name:
            pattern: "st2"
            type: "equals"

    action:
        ref: "core.local"
        parameters:
            cmd: "echo \"{{trigger.body}}\" >> ~/st2.webhook_sample.out"

The rule definition is a YAML file with three sections: trigger, criteria, and action. This example is setup to react on a webhook trigger and applies filtering criteria on the content of the trigger. The webhook in this example is setup to listen on the sample sub-url at https://{host}/api/v1/webhooks/sample. When a POST is made on this URL, the trigger fires. If the criteria matches, value in payload is st2 in this case, the payload will be appended to the file st2.webhook_sample.out in the home directory of the user setup to run BWC. By default, stanley is the default user and the file will be located at /home/stanley/st2.webhook_sample.out. See Rules for detailed rule anatomy.

The trigger payload is referred to with {{trigger}}. If the trigger payload is a valid JSON object, it is parsed and can be accessed like {{trigger.path.to.parameter}} (it’s Jinja template syntax).

What are the triggers available to use in rules? Just like with actions, use the CLI to browse triggers, learn what the trigger does, how to configure it, and what the payload structure is:

# List all available triggers
st2 trigger list

# Check details on Interval Timer trigger
st2 trigger get core.st2.IntervalTimer

# Check details on the Webhook trigger
st2 trigger get core.st2.webhook

Deploy a Rule

BWC can be configured to auto-load the rules or rules can be deployed with API or CLI:

# Create the rule
st2 rule create /usr/share/doc/st2/examples/rules/sample_rule_with_webhook.yaml

# List the rules
st2 rule list

# List the rules for the examples pack
st2 rule list --pack=examples

# Get the rule that was just created
st2 rule get examples.sample_rule_with_webhook

Once the rule is created, the webhook begins to listen on https://{host}/api/v1/webhooks/{url}. Fire the POST, check out the file and see that it appends the payload if the name=Joe.

# Post to the webhook
curl -k https://localhost/api/v1/webhooks/sample -d '{"foo": "bar", "name": "st2"}' -H 'Content-Type: application/json' -H 'X-Auth-Token: put_token_here'

# Check if the action got executed (this shows last action)
st2 execution list -n 1

# Check that the rule worked. By default, st2 runs as the stanley user.
sudo tail /home/stanley/st2.webhook_sample.out

# And for fun, same post with st2
st2 run core.http method=POST body='{"you": "too", "name": "st2"}' url=https://localhost/api/v1/webhooks/sample headers='x-auth-token=put_token_here,content-type=application/json' verify_ssl_cert=False

# And for even more fun, using basic authentication over https
st2 run core.http url=https://httpbin.org/basic-auth/st2/pwd username=st2 password=pwd

# Check that the rule worked. By default, st2 runs as the stanley user.
sudo tail /home/stanley/st2.webhook_sample.out

Congratulations, your first BWC rule is up and running!

Deploy Examples

Examples of rules, custom sensors, actions, and workflows are installed with BWC and located at /usr/share/doc/st2/examples. To deploy, copy them to /opt/stackstorm/packs/, setup, and reload the content:

# Copy examples to st2 content directory
sudo cp -r /usr/share/doc/st2/examples/ /opt/stackstorm/packs/

# Run setup
st2 run packs.setup_virtualenv packs=examples

# Reload stackstorm context
st2ctl reload --register-all

For more content — actions, sensors, rules — checkout StackStorm Exchange.

Datastore

While most data are retrieved as needed by BWC, you may need to store and share some common variables. Use BWC datastore service to store the values and reference them in rules and workflows as {{st2kv.system.my_parameter}}. This creates user=stanley key-value pair:

# Create a new key value pair
st2 key set user stanley

# List the key value pairs in the datastore
st2 key list

For more information on datastore, check Datastore


What’s Next?

Questions? Problems? Suggestions? Engage!