diff --git a/README.md b/README.md index 0edb23e..399ff22 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,74 @@ -# Nagios Mattermost Plugin -A plugin for Nagios to enable notifications to Mattermost Open Source Chat. +Nagios Mattermost Plugin +======================== -# Usage -Assuming you are using Nagios 4, the steps are: +A plugin for [Nagios](https://www.nagios.org/) and compatible software (e.g. [Icinga](https://www.icinga.org/)) to enable notifications to a [Mattermost](http://www.mattermost.org/) server. -1. Copy _mattermost.py_ to /usr/local/nagios/libexec. +## Plugin Usage -2. Create a new incoming webhook integration, and use the URL for the webhook in the next step. +Run `./mattermost.py --help` for full usage information. -3. Create the notification command: +## Mattermost Configuration - define command { - command_name notify-service-by-mattermost - command_line /usr/local/nagios/libexec/mattermost.py --url [URL] --channel [CHANNEL] --hostalias "$HOSTNAME$" --notificationtype "$NOTIFICATIONTYPE$" --servicedesc "$SERVICEDESC$" --servicestate "$SERVICESTATE$" --serviceoutput "$SERVICEOUTPUT$" - } +1. *Incoming Webhooks* must be enabled for your Mattermost server. Check the **Enable Incoming Webhooks** option under **Service Settings** in the *System Console*. - define command { - command_name notify-host-by-mattermost - command_line /usr/local/nagios/libexec/mattermost.py --url [URL] --channel [CHANNEL] --hostalias "$HOSTNAME$" --notificationtype "$NOTIFICATIONTYPE$" --hoststate "$HOSTSTATE$" --hostoutput "$HOSTOUTPUT$" - } +2. To use the optional `--username` parameter you must enable overriding of usernames from webhooks. Check the **Enable Overriding Usernames from Webhooks and Slash Commands** option under **Service Settings** in the *System Console*. -4. Create the contact: +3. To use the optional `--iconurl` parameter you must enable overriding of icons from webhooks. Check the **Enable Overriding Icon from Webhooks and Slash Commands** option under **Service Settings** in the *System Console*. +## Nagios Configuration - define contact { - contact_name mattermost - alias Mattermost - service_notification_period 24x7 - host_notification_period 24x7 - service_notification_options w,u,c,r - host_notification_options d,r - service_notification_commands notify-service-by-mattermost - host_notification_commands notify-host-by-mattermost - } +The steps below are for a Nagios 4 server but should work with minimal modifications for compatible software: -5. Add the contact to a contact group: +1. Copy `mattermost.py` to `/usr/local/nagios/libexec`. +2. Create an *Incoming Webhook* integration for the approriate team and note the provided URL. - define contactgroup{ - contactgroup_name network-admins - alias Network Administrators - members email, mattermost - } +3. Create the command definitions in your Nagios configuration: + + ``` + define command { + command_name notify-service-by-mattermost + command_line /usr/local/nagios/libexec/mattermost.py --url [MATTERMOST-WEBHOOK-URL] \ + --channel [OPTIONAL-MATTERMOST-CHANNEL] \ + --notificationtype "$NOTIFICATIONTYPE$" \ + --hostalias "$HOSTNAME$" \ + --servicedesc "$SERVICEDESC$" \ + --servicestate "$SERVICESTATE$" \ + --serviceoutput "$SERVICEOUTPUT$" + } + + define command { + command_name notify-host-by-mattermost + command_line /usr/local/nagios/libexec/mattermost.py --url [MATTERMOST-WEBHOOK-URL] \ + --channel [OPTIONAL-MATTERMOST-CHANNEL] \ + --notificationtype "$NOTIFICATIONTYPE$" \ + --hostalias "$HOSTNAME$" \ + --hoststate "$HOSTSTATE$" \ + --hostoutput "$HOSTOUTPUT$" + } +``` + +4. Create the contact definition in your Nagios configuration: + + ``` + define contact { + contact_name mattermost + alias Mattermost + service_notification_period 24x7 + host_notification_period 24x7 + service_notification_options w,u,c,r + host_notification_options d,r + host_notification_commands notify-host-by-mattermost + service_notification_commands notify-service-by-mattermost + } +``` + +5. Add the contact to a contact group in your Nagios configuration: + + ``` + define contactgroup{ + contactgroup_name network-admins + alias Network Administrators + members email, mattermost + } +``` diff --git a/mattermost.py b/mattermost.py index 5159fc5..3315cc9 100755 --- a/mattermost.py +++ b/mattermost.py @@ -1,4 +1,4 @@ -#!/usr/bin/python +#!/usr/bin/python2 # Copyright (c) 2015 NDrive SA # @@ -21,34 +21,33 @@ # THE SOFTWARE. import argparse -import urllib2 import json +import urllib2 VERSION = "0.1.1E" -CONFIG = { - "icon_url": "https://slack.global.ssl.fastly.net/7bf4/img/services/nagios_128.png", #noqa - "username": "Nagios" -} - -TEMPLATE_SERVICE = "__{notificationtype}__ {hostalias}/{servicedesc} is {servicestate}\n{serviceoutput}" #noqa -TEMPLATE_HOST = "__{notificationtype}__ {hostalias} is {hoststate}\n{hostoutput}" #noqa +TEMPLATE_HOST = "__{notificationtype}__ {hostalias} is {hoststate}\n{hostoutput}" # noqa +TEMPLATE_SERVICE = "__{notificationtype}__ {hostalias}/{servicedesc} is {servicestate}\n{serviceoutput}" # noqa def parse(): - parser = argparse.ArgumentParser(description='Sends mattermost webhooks') - parser.add_argument('--url', help='Integration URL', required=True) - parser.add_argument('--hostalias', help='Host Alias', required=True) - parser.add_argument('--notificationtype', help='Notification type', + parser = argparse.ArgumentParser(description='Sends alerts to Mattermost') + parser.add_argument('--url', help='Incoming Webhook URL', required=True) + parser.add_argument('--channel', help='Channel to notify') + parser.add_argument('--username', help='Username to notify as', + default='Nagios') + parser.add_argument('--iconurl', help='URL of icon to use for username', + default='https://slack.global.ssl.fastly.net/7bf4/img/services/nagios_128.png') # noqa + parser.add_argument('--notificationtype', help='Notification Type', required=True) + parser.add_argument('--hostalias', help='Host Alias', required=True) parser.add_argument('--hoststate', help='Host State') parser.add_argument('--hostoutput', help='Host Output') parser.add_argument('--servicedesc', help='Service Description') parser.add_argument('--servicestate', help='Service State') parser.add_argument('--serviceoutput', help='Service Output') - parser.add_argument('--channel', help='Channel to notificate') parser.add_argument('--version', action='version', - version='%(prog)s {version}'.format(version=VERSION)) + version='% (prog)s {version}'.format(version=VERSION)) args = parser.parse_args() return args @@ -58,9 +57,9 @@ def encode_special_characters(text): return text -def make_data(args, config): +def make_data(args): template = TEMPLATE_SERVICE if args.servicestate else TEMPLATE_HOST - + # Emojis if args.notificationtype == "RECOVERY": EMOJI = ":white_check_mark:" @@ -72,12 +71,12 @@ def make_data(args, config): EMOJI = ":sunny:" else: EMOJI = "" - + text = EMOJI + template.format(**vars(args)) - + payload = { - "username": config["username"], - "icon_url": config["icon_url"], + "username": args.username, + "icon_url": args.iconurl, "text": encode_special_characters(text) } @@ -93,8 +92,9 @@ def request(url, data): response = urllib2.urlopen(req) return response.read() + if __name__ == "__main__": args = parse() - data = make_data(args, CONFIG) + data = make_data(args) response = request(args.url, data) print response