Configuration¶

General
ST2 ChatOps Configuration
Authentication
Advanced Options
Locale
Reference

General ¶

err-stackstorm configuration is found in Errbot’s config.py file.

Note

If you followed the Errbot setup documentation this file will have been created by downloading a template. If this file has not already been created, please create it following the Errbot’s instructions.

Here’s a sample err-stackstorm configuration:

STACKSTORM = {
    "auth_url": "https://your.stackstorm.com/auth/v1",
    "api_url": "https://your.stackstorm.com/api/v1",
    "stream_url": "https://your.stackstorm.com/stream/v1",
    "route_key": "errbot",
    "plugin_prefix": "st2",
    "verify_cert": True,
    "secrets_store": "cleartext",
    "session_ttl": 3600,
    "user_token_ttl": 86400,
    "api_auth": {
        "user": {
            "name": "my_username",
            "password": "my_password",
        },
        "token": "<User token>",
        "apikey": "<API Key>"
    },
    "rbac_auth": {
        "standalone": {},
    },
    "timer_update": 900, #  Unit: second.  Interval to check the user token is still valid.
}

ST2 ChatOps Configuration ¶

StackStorm’s ChatOps pack has to be installed and a notify rule file added to the pack.

The notify rule must be placed in /<st2>/packs/chatops/rules. You can find the rule file necessary for err-stackstorm here. Just copy-and-paste this file and save it as notify_errbot.yaml.

Edit the /<st2>/packs/chatops/actions/post_message.yaml file and replace chatops with errbot:

route:
  default: "errbot"

Note

See Route Key below for information on customising the route.

Authentication ¶

err-stackstorm must have valid credentials to use StackStorm’s API. Stackstorm’s authentication is possible with:

Username and password
User token
API key

See Stackstorm’s Authentication docs for more details on how to generate credentials.

Username/Password ¶

Using a username and password will allow err-stackstorm to renew the user token once it expires.

Note

If you specify both username/password and a User Token, the User Token will be used and the username/password will be ignored.

User Token ¶

To avoid using the username/password pair in a configuration file, it’s possible to supply a User Token as generated by StackStorm when a username/password is authenticated successfully.

If using an User Token err-stackstorm will no longer have access to the Stackstorm’s API once it expires.

Note

When the token expires, a new one must be generated and updated in config.py which in turn requires Errbot to be restarted. This form of authentication is the least practical for production environments.

API Key ¶

API Key support has been included since StackStorm v2.0.

When an API Key is provided, all other authentication settings are ignored and the API Key is used.

If using an API Key, err-stackstorm will no longer have access to the Stackstorm’s API once it expires.

Note

It is considered a mistake to supply a token or username/password pair when using the API Key.

Secrets Store ¶

The secrets store is used by err-stackstorm to cache StackStorm API credentials. The available backends are:

cleartext

Cleartext ¶

The cleartext store maintains the cache in memory and does not encrypt the contents to disk. It does not protect the stored secrets in memory.

Advanced Options ¶

Route Key ¶

The route key is used by err-stackstorm to inform StackStorm where to send result notifications for action-aliases. StackStorm sends notification events via the stream interface that are marked with the route key. Err-stackstorm filters these events using the route key and will handle any events that match its configured route key.

By altering the route key, it is possible to have multiple instances of err-stackstorm that are connected to the same StackStorm instance. This would allow for configurations where StackStorm is available on multiple chat backends.

Example ¶

A StackStorm instance has 2 err-stackstorm instances. The first err-stackstorm instance uses the errbot-slack route key while the second instance uses the errbot-discord route key. Both instances have the same plugin prefix and expose the same action-aliases. This would mean the command !st2 pack list could be run on discord and the result notification would be routed to the errbot-discord err-stackstorm instance.

Plugin Prefix ¶

By default the plugin prefix is set to st2. The plugin prefix serves to prevent action-aliases collisions with errbot’s native plugins commands. It is possible to customise the plugin prefix to use a more appropriate naming scheme for the environment err-stackstorm is running.

Aside from cosmetic value, customising the plugin prefix can allow for multiple err-stackstorm instances to occupy the same chat channel. This would be achieved by setting a unique plugin-prefix per instance.

Note

Always use strings that do not conflict with existing errbot commands.

Example ¶

In the case of multiple instances of a StackStorm and err-stackstorm pair, say 1 per data centre or 1 per region, it would be possible to assign a unique plugin prefix per instance. Let’s say there were 2 pairs with the plugin-prefix of dc1 and dc2. Both bots could occupy #automation channel and users could trigger the pack list action-alias in data centre #1 by calling !dc1 pack list or get available action-aliases from data centre #2 by calling !dc2help.

Session TTL ¶

The session time to live is an internal timeout for err-stackstorm. It is used to set the maximum lifetime an err-stackstorm session is permitted to exist. Once the session expires the user will need to re-authenticate before being able to execute action-alias commands. An err-stackstorm session ttl should be equal to or less than the user token ttl.

When session time to live expires, err-stackstorm will report to the user that the session is no longer valid and they should reauthenticate.

User Token TTL ¶

The user token ttl is used to set the maximum life time a StackStorm User Token will be permitted to exist. Once the user token has expired the user will need to re-authenticate before being able to execute action-alias commnds.

When a user token time to live expires, err-stackstorm will report it as an error communicating with the StackStorm API. It would be more user-friendly to ensure the session ttl expires before the user token ttl.

Note

The user token ttl _must be_ equal to or lower than the StackStorm API https://docs.stackstorm.com/authentication.html?highlight=ttl#usage. By default StackStorm’s token ttl is set to 24 hours, but the value can be increased through st2.conf. If user_token_ttl is greater than the StackStorm API token ttl value, err-stackstorm will fail to fetch a valid API token and not function correctly.

Locale ¶

Errbot uses the system’s locale for handling text. If you’re getting unicode errors like this:

UnicodeEncodeError: 'ascii' codec can't encode character '\xe9' in position 83: ordinal not in range(128)

Make sure the systems locale is configured for unicode encoding. In the example below, the machine has been set to English (en) New Zealand (NZ) with utf-8 encoding (.UTF8).

# locale
LANG=en_NZ.UTF8
LANGUAGE=
LC_CTYPE="en_NZ.UTF8"
LC_NUMERIC="en_NZ.UTF8"
LC_TIME="en_NZ.UTF8"
LC_COLLATE="en_NZ.UTF8"
LC_MONETARY="en_NZ.UTF8"
LC_MESSAGES="en_NZ.UTF8"
LC_PAPER="en_NZ.UTF8"
LC_NAME="en_NZ.UTF8"
LC_ADDRESS="en_NZ.UTF8"
LC_TELEPHONE="en_NZ.UTF8"
LC_MEASUREMENT="en_NZ.UTF8"
LC_IDENTIFICATION="en_NZ.UTF8"
LC_ALL=en_NZ.UTF8

Reference ¶

Option Description

auth_url StackStorm’s authentication url end point. Used to authenticate credentials against StackStorm.

api_url StackStorm’s API url end point. Used to execute action aliases received from the chat back-end.

stream_url StackStorm’s Stream url end point. Used to received ChatOps notifications.

verify_cert Default is True. Verify the SSL certificate is valid when using https end points. Applies to all end points.

route_key Default is errbot. The name of the route to bot will listen for and submit action-alias executions with.

plugin_prefix Default is st2. Text used to prefix action-alias commands with to avoid name collisions between StackStorm Action-Aliases and Errbot plugin commands.

api_auth.user.name Errbot’s username to authenticate with StackStorm.

api_auth.user.password Errbot’s password to authenticate with StackStorm.

api_auth.token Errbot’s user token to authenticate with StackStorm. Used instead of a username/password pair.

api_auth.apikey Errbot API key to authenticate with StackStorm. Used instead of a username/password pair or user token.

timer_update Unit: seconds. Default: 60. Interval for err-stackstorm to the user token is valid.

rbac_auth.standalone Standalone authentication.

rbac_auth.clientside Clientside authentication, a chat user will supply StackStorm credentials to err-stackstorm via an authentication page.

rbac_auth.clientside.url Url to the authentication web page.

session_ttl Unit: seconds. Default: 3600. The time to live for a authentication session.

user_token_ttl Unit: seconds. Default: 86400. The time to live for a StackStorm user token.

secrets_store.cleartext Use the in-memory store.