Activate development has moved to https://github.com/nzlosh/err-stackstorm
A plugin to run StackStorm actions, bringing StackStorm's chatops to Errbot.
- Installation
- Requirements
- Supported Chat Backends
- Configuration
- Setup Action-Aliases
- Webhook
- Server-Side Events
- Chatops Pack
- Troubleshooting
Installation of the err-stackstorm plugin is performed from within a running Errbot instance. Ensure Errbot is up and running before attempting to install the plugin. See the Errbot installation documentation here https://github.com/Errbotio/Errbot for instructions on how to setup Errbot on your chat back-end. These instructions assume a running instance of StackStorm is already in place. See the official StackStorm documentation for details.
- Install Errbot on the target system using standard package manager or Errbot installation method.
- Configure Errbot, see the Configuration section for help.
- Enable Errbot's internal web server, see the Webhook section for help.
- Install Chatops pack on StackStorm, see the Chatops Pack section for help.
- Connect to your chat back-end and starting interacting with your StackStorm/Errbot instance.
The below command will install the plugin.
!repos install https://github.com/fmnisme/err-stackstorm.git
The plugin has been developed and tested against the below software. For optimal operation it is recommended to use the following versions:
| plugin tag (version) | Python | Errbot | StackStorm client |
|---|---|---|---|
| 1.4 | 3.4 | 5.1.2 | 2.5 |
| 1.3 | 3.4 | 5.1.2 | 2.5 |
| 1.2 | 3.4 | 5.0 | 2.2 |
| 1.1 | 3.4 | 4.3 | 2.2 |
| 1.0 | 2.7 | 3.x | 2.1 |
Errbot provides official support for a few of major chat back-ends and many more chat back-ends are available through unofficial plugins.
| Back end | Mode value | Support type |
|---|---|---|
| Hipchat | hipchat |
Integrated |
| IRC | irc |
Integrated |
| Slack | slack |
Integrated |
| Telegram Messenger | telegram |
Integrated |
| Text | text |
Integrated |
| XMPP | xmpp |
Integrated |
| Skype | skype |
Plugin |
| Mattermost | mattermost |
Plugin |
| Rocket Chat | aoikrocketchaterrbot |
Plugin |
| Glip | Glip |
Plugin |
| Gitter | gitter |
Plugin |
| VK | VK |
Plugin |
| Discord | discord |
Plugin |
| Cisco Spark | CiscoSpark |
Plugin |
| TOX | tox |
Plugin |
| CampFire | campfire |
Plugin |
Back-end support will provide a minimum set of back-end chat functionality to the err-stackstorm plugin like connect to and authenticate with chat back-end, identify users/rooms and send_message to users/rooms. Advanced formatting may not be available on all back-ends since adaptor code is required in the err-stackstorm plugin to translate ActionAlias extra parameter on a per back-end basis.
Currently supported extra back-ends
- Slack
Edit the config.py configuration file which is used to describe how the plugin will communicate with StackStorm's API and authentication end points.
If you followed the Errbot setup documentation this file will have been created by downloading a template from the Errbot GitHub site. If this file has not already been created, please create it following the instructions at https://github.com/Errbotio/Errbot
STACKSTORM = {
'auth_url': 'https://stackstorm.example.com/auth/v1',
'api_url': 'https://stackstorm.example.com/api/v1',
'stream_url': 'https://stackstorm.example.com/stream/v1',
'verify_cert': True,
'api_auth': {
'user': {
'name': 'my_username',
'password': "my_password",
},
'token': "<User token>",
'key': '<API Key>'
},
'timer_update': 900, # Unit: second. Interval for Errbot to refresh to list of available action aliases.
}
| 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. |
api_auth.user.name |
Errbot username to authenticate with StackStorm. |
api_auth.user.password |
Errbot password to authenticate with StackStorm. |
api_auth.token |
Errbot user token to authenticate with StackStorm. Used instead of a username/password pair. |
api_auth.key |
Errbot API key to authenticate with StackStorm. Used instead of a username/password pair or user token. |
timer_update |
Unit: seconds. Default is 60. Interval for Errbot to refresh to list of available action aliases. (deprecated) |
Authentication is possible with username/password, User Token or API Key. In the case of a username and password, the plugin is requests a new User Token after it expires. In the case of a User Token or API Key, once it expires, the Errbot plugin will no longer have access to the st2 API.
The Errbot plugin must have valid credentials to use StackStorm's API. The credentials may be;
- username/password
- user token
- api key
See https://docs.stackstorm.com/authentication.html for more details.
Using a username and password will allow Errbot to renew the user token when it expires. If a User Token is supplied, it will be used in preference to username/password authentication until the token expires.
To avoid using the username/password pair in a configuration file, it's possible to supply a pre-generated User Token as generated by StackStorm. 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 method is the least ideal for production environments.
API Key support has been included since StackStorm v2.0. When an API Key is provided, it is used in preference to a User Token or username/password pair. It is considered a mistake to supply a token or username/password pair when using the API Key.
- Connect Errbot to your chat environment.
- Write an action alias in StackStorm.
- Errbot will automatically refresh its action alias list.
- Type
!st2helpin your chat program to list available StackStorm commands. - Type the desired command in your chat program, as shown in the help.
Errbot has a built in web server which is configured and enabled through the bots admin chat interface. The StackStorm plugin is written to listen for StackStorm's chatops messages and delivers them to the attached chat back-end.
To configure Errbot's web server plugin, the command below can be sent to Errbot:
!plugin config Webserver {'HOST': '0.0.0.0', 'PORT': 3141,
'SSL': {'enabled': False, 'host': '0.0.0.0', 'port': 3142, 'certificate': '', 'key': ''}}
NOTE: The variables must be adjusted to match the operating environment in which Errbot is running. See Errbot documentation for further configuration information.
The configuration above is only applied for the current runtime and will not persist after the errbot process being restarted. Making the configuration change permanent is as simple as installing a special plugin:
!repos install https://github.com/tkit/errbot-plugin-webserverconfiguration
The configuration command from above is not required prior to installing this plugin.
In production environments it may be desirable to place a reverse-proxy like nginx in front of errbot.
As of StackStorm 1.4. server-sent events (SSE) were added which allowed chatops messages to be streamed from StackStorm to a connected listener (err-stackstorm in our case). The StackStorm stream url must be supplied in the configuration so err-stackstorm knows where to establish the http connection. The SSE configuration is complementary to the webhook method and both must be enabled for full chatops support between StackStorm and Errbot.
StackStorm's chatops pack is required to be installed and a notify rule file added to the pack.
The notify rule must be placed in /<stackstorm installation>/packs/chatops/rules. The rule file
notify_errbot.yaml can be found
in this repository under
Edit the chatops/actions/post_message.yaml file to use the errbot route as it's default value.
route:
default: "errbot"
Check an instance of Errbot is running on the host
# ps faux | grep errbo[t]
root 158707 0.1 0.0 2922228 59640 pts/21 Sl+ Aug14 2:29 | \_ /opt/errbot/bin/python3 /opt/errbot/bin/errbot -c /data/errbot/etc/config.py
Check Errbot's internal web server is listening on the correct interface.
# ss -tlpn | grep 158707
LISTEN 0 128 *:8888 *:* users:(("errbot",158707,21))
OR
# netstat -tlpn | grep 158707
tcp 0 0 0.0.0.0:8888 0.0.0.0:* LISTEN 158707/python3
From the errbot machine perform a curl to the StackStorm endpoint:
curl http://<stackstorm_host>/api/v1/rules
To test if the username/password pair, user token or api key supplied in the configuration is valid.
In the examples below, the username for the bot is errbot.:
A successful username / password authentication is shown below:
$ st2 auth errbot
Password:
+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| user | errbot |
| token | 10342978da134ae5bbb7dc94d2ba9c08 |
| expiry | 2017-09-29T14:31:20.799212Z |
+----------+----------------------------------+
If the username and password are valid and correctly entered in errbot's configuration file, errbot will be authorised to interact with StackStorm's API/Stream end points.
Test the errbot user token from the configuration using the st2 command. Make
sure no environment variables are set that could provide a valid token or api key already.
$ st2 action-alias list -t 10342978da134ae5bbb7dc94d2ba9c08
+-----------------------------------+------------+---------------------------------------+---------+
| ref | pack | description | enabled |
+-----------------------------------+------------+---------------------------------------+---------+
| packs.pack_get | packs | Get information about installed | True |
| | | StackStorm pack. | |
| packs.pack_install | packs | Install/upgrade StackStorm packs. | True |
| packs.pack_search | packs | Search for packs in StackStorm | True |
| | | Exchange and other directories. | |
| packs.pack_show | packs | Show information about the pack from | True |
+-----------------------------------+------------+---------------------------------------+---------+
If a list of action aliases are shown, the token is valid.
Confirm the api key has been created and still registered with StackStorm by using it with the st2 command.
$ st2 apikey list --api-key ZzVk3DEBZ4FiZmMEmDBkM2x5ZmM5jWZkZWZjZjZmMZEwYzQwZD2iYzUyM2RhYTkTNMYmNDYNODIOOTYwMzE20A
+--------------------------+--------+-------------------------------------------+
| id | user | metadata |
+--------------------------+--------+-------------------------------------------+
| 586e6deadbeef66deadbeef6 | errbot | {u'used_by': u'errbot api access'} |
+--------------------------+--------+-------------------------------------------+
How to test if the bot is connected to the chat back-end is dependant on the back-end. The simplest way is to send a message to the bot user account requesting the built in help.
E.g. Using a slack client the following command would be used
/msg @bot_name !help.
The bot should respond with its help text.
bot [11:01 AM]
_All commands_
*Backup*
_Backup related commands._
• *.backup* - Backup everything.
*ChatRoom*
_This is a basic implementation of a chatroom_
• *.room join* - Join (creating it first if needed) a chatroom.
• *.room occupants* - List the occupants in a given chatroom.
• *.room invite* - Invite one or more people into a chatroom.
• *.room topic* - Get or set the topic for a room.
Err-stackstorm requires the chatops pack to be installed. To confirm it is installed, use the st2 cli.
$ st2 pack list
+-------------------+-------------------+--------------------------------+---------+----------------------+
| ref | name | description | version | author |
+-------------------+-------------------+--------------------------------+---------+----------------------+
| chatops | chatops | Chatops integration pack | 0.2.0 | Kirill Enykeev |
Confirm the notify_errbot.yaml is inside the chatops/rules directory
$ cat /opt/stackstorm/packs/chatops/rules/notify_errbot.yaml
---
name: "notify-errbot"
pack: "chatops"
enabled: true
description: "Notification rule to send results of action executions to stream for chatops"
trigger:
type: "core.st2.generic.notifytrigger"
criteria:
trigger.route:
pattern: "errbot"
type: "equals"
action:
ref: chatops.post_result
parameters:
channel: "{{ trigger.data.source_channel }}"
user: "{{ trigger.data.user }}"
execution_id: "{{ trigger.execution_id }}"
The rule should be available via the st2 command st2 rule get chatops.notify-errbot
+-------------+--------------------------------------------------------------+
| Property | Value |
+-------------+--------------------------------------------------------------+
| id | 5a6b1abc5b3a0f0f5bcd54e7 |
| uid | rule:chatops:notify-errbot |
| ref | chatops.notify-errbot |
| pack | chatops |
| name | notify-errbot |
| description | Notification rule to send results of action executions to |
| | stream for chatops |
| enabled | True |
| action | { |
| | "ref": "chatops.post_result", |
| | "parameters": { |
| | "user": "{{trigger.data.user}}", |
| | "execution_id": "{{trigger.execution_id}}", |
| | "channel": "{{trigger.data.source_channel}}" |
| | } |
| | } |
| criteria | { |
| | "trigger.route": { |
| | "pattern": "errbot", |
| | "type": "equals" |
| | } |
| | } |
| tags | |
| trigger | { |
| | "type": "core.st2.generic.notifytrigger", |
| | "ref": "core.st2.generic.notifytrigger", |
| | "parameters": {} |
| | } |
| type | { |
| | "ref": "standard", |
| | "parameters": {} |
| | } |
+-------------+--------------------------------------------------------------+
From the errbot host connect to the StackStorm stream endpoint and watch for events emitted as actions are executed by StackStorm.
curl -s -v -H 'Accept: text/event-stream' -H 'X-Auth-Token: 10342978da134ae5bbb7dc94d2ba9c08' http://<stackstorm_host>/stream/v1
To see the events in the log, the debug level BOT_LOG_LEVEL = logging.DEBUG will need to be added to errbot's configuration file config.py.
If events are configured correctly, logs will be shown like this (st2.announcement__errbot)
17:04:12 DEBUG root Dispatching st2.announcement__errbot event, 990 bytes...
17:04:12 DEBUG lib.st2pluginapi *** Errbot announcement event detected! ***
st2.announcement__errbot event, 990 bytes
If the announcement event is showing as
2018-01-26 15:51:55,246 DEBUG sseclient Dispatching st2.announcement__chatops event, 508 bytes...
This indicates that the route wasn't set to errbot, see the Install Chatops section.