Skip to content

Latest commit

 

History

History
144 lines (93 loc) · 8.63 KB

README.md

File metadata and controls

144 lines (93 loc) · 8.63 KB
Raw

ZoneBot - A ZoneMinder Slack Bot

This is a Slack Bot that monitors one or more Slack channels for commands and interacts with a ZoneMinder system to report events and obtain information.

There are two parts to the project

  1. A script that is invoked by ZoneMinder whenever an event/alarm is detected (zonebot-alert). This will post a message with the most significant frame of the event to a specified Slack channel. ZoneBot posting an event
  2. A bot that listens in a Slack channel for commands from approved users and passes them along to the ZoneMinder server. Screen cast of basic features

The primary use for this bot is to allow access to some parts of a ZoneMinder system that is behind a firewall, without having to expose the actual system to the Internet. Making a ZoneMinder system available to the Internet has several requirements (static IP, secure system) that may not be feasible for all users.

By providing a bot that can interact with both ZoneMinder and Slack, remote access to and notification from ZoneMinder is possible, without needing a static IP. The security and authentication provided by the Slack environment is used to control access to the script, and the bot also has a permissions section in it's configuration that controls which users are allowed which actions.

Installation

Easiest : Using pip

The easiest method of installation is via pip as the package is available from the Python Package Index

> pip install zonebot

This will create a script called zonebot in your path ("which zonebot" will tell you exactly where) that you can run.

Download source and build

You can download the source from GitHub and build it yourself if you would like.

  1. Download the release you want from https://github.com/rjclark/zoneminder-slack-bot/releases
  2. Extract it
  3. Run python setup.py build install

Clone the source and build

You can also clone the source from GitHub if you would like to build the very latest version. This is not guaranteed to work. The unreleased source code from GitHub could be in the middle of development and running it directly is not recommended.

  1. Clone this repository https://github.com/rjclark/zoneminder-slack-bot
  2. Run python setup.py build install

Configuration

Bot Configuration

Also installed is a sample configuration file called zonebot-example-config.cfg. You can copy this to your preferred location for config files and edit it to put in your Slack API token and the ID of your bot user

The example configuration file is installed into the Python package directory on your system, which can be somewhat difficult to find. The latest version of the file is always available from the GitHub repository if needed.

To configure the bot, you will need several pieces of information

  1. Your Slack API token. This can be found by
    1. Going to the Slack Bot user page and creating a new bot user. You will have a chance to get the API token here
    2. Going to the page for your existing bot user.
  2. The User ID of your bot user. This can be found by:
    1. Running the script zonebot-getid distributed with this package and providing the name of the Slack bot user and you Slack API token as command line options. For example:
> zonebot-getid  -a "your-slack-token" -b zoneminder
> User ID for bot 'zoneminder' is AA22BB44C

Once you have those, make a copy of the config file and add the Slack API token and user ID of the bot, You will also want to edit the Permissions section.

NOTE: The default config file allows only read permission to the ZoneMinder system.

ZoneMinder Configuration

If you want ZoneMinder events posted to Slack as they occur, you must define a ZoneMinder filter that invokes the zonebot-alert script. The script gets all required configuration information from the same config file as the bot.

Defining a ZoneMinder filter

Config File Locations

The default config file can be placed in any of these locations (checked in this order)

  • Any file specified by the -c/--config command line option
  • $XDG_CONFIG_HOME/zonebot/zonebot.conf if the XDG_CONFIG_HOME environment variable is defined
  • ${DIR}/zonebot/zonebot.conf for any directory in the XDG_CONFIG_DIRS environment variable
  • ~/.config/zonebot/zonebot.conf
  • /etc/zonebot/zonebot.conf
  • /etc/default/zonebot

Reporting Problems

  1. The best way to report problems is to log a report on the GitHub Issues page https://github.com/rjclark/zoneminder-slack-bot/issues for this project.
  2. If you do not have a GItHub account, you can also contact me via email: clark@exiter.com

Building and Contributing

If you wish to contribute, pull requests against the GitHub repository, master branch, are welcomed.

Build Status Coverage Status PyPI version Dependency Status Code Health

Requirements and Tools

If you are new to the concept of building either a Python application or a Slack bot, I encourage you to review the excellent posting over at Full Stack Python called How to Build Your First Slack Bot with Python. This document will provide a summary of the requirements and steps necessary, but it assumes a basica familiarity with the tools and environment that the linked article covers in some depth.

This list of tools from the First Slack Bot blog is all that is needed to build this bot.

It is also useful to have the Slack API docs handy while you're building this tutorial.

Setup

  1. Use virtualenv and pip to create a development
> virtualenv venv
> source venv/bin/activate
    (or . venv/bin/activate.fish of you use the fish shell)

> venv/bin/pip install install -r requirements.txt

  1. Obtain a Slack API token (and optionally create a dedicated bot user for the API token) from Slack

  2. Since the API token needs to remain secret, you should set it as an environment variable rather than putting it into any source file.

> export SLACK_BOT_TOKEN='your slack token pasted here'

  1. Run utils/get_bot_id.py to get the number ID of the bot (as opposed to the name you gave the bot user. This is also our first real test of the API token

  2. Put the bot ID into an environment variable as well.

> export BOT_ID='bot id returned by script'

Later on the BOT_ID and SLACK_API_TOKEN (along with a lot of the other config options) will be loaded from a config file. This is to make running the script as a daemon less of a hassle.