From bdf768d1df28b80ad03aec7c1599dd9f1fefc994 Mon Sep 17 00:00:00 2001
From: "Samuel D. Leslie" <sdl@nexiom.net>
Date: Fri, 27 May 2016 16:17:05 +1000
Subject: [PATCH] Overhaul the README.md

---
 README.md | 94 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 62 insertions(+), 32 deletions(-)

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
+    }
+```