justinegeffen/mattermost-plugin-nagios

A Mattermost plugin to interact with Nagios Core

Mattermost Nagios Plugin

Maintainers: @amwolff & @DanielSz50

A Nagios plugin for Mattermost. Supports Nagios Core >= 4.4.x.

Table of contents

• About
  • Screenshots
    • Getting logs
    • Receiving system monitoring reports
    • Receiving notifications about changes to the configuration
  • Audience
  • Important notice
• Installing the plugin
• Configuring the plugin
  • Configuring the configuration files watcher
    • Running the watcher as a systemd service
      • Preparing the systemd service unit file
      • Starting the watcher
• Updating the plugin
• Using the plugin
  • Slash commands overview
  • Slash commands documentation
    • nagios
      • get-logs
        • host
        • service
    • set-logs-limit
    • set-logs-start-time
    • subscribe
    • unsubscribe
    • set-report-frequency
• Contributing
  • Developing the watcher
  • Reporting security vulnerabilities

About

This plugin allows you to

• get logs from specific systems without leaving the Mattermost
  • get alerts and notifications instantly delivered, resembling the showlog.cgi UI
• receive system monitoring reports on a subscribed channel
  • be frequently informed which hosts and services have an abnormal state
• receive notifications about changes to the configuration on a subscribed channel
  • anytime a change has been made to Nagios configuration, receive a diff between the old and the new version

Ultimately, this will make you or your team more productive and make the experience with Nagios smoother.

Screenshots

Getting logs

Receiving system monitoring reports

Receiving notifications about changes to the configuration

Audience

This guide is for Mattermost System Admins setting up the Nagios plugin and Mattermost users who want information about the plugin functionality.

Important notice

If you are a Nagios admin/user and think there is something this plugin lacks or something that it does could be done the other way around, let us know! We are trying to develop this plugin based on users' needs. If there is a certain feature you or your team needs, open up an issue, and explain your needs. We will be happy to help.

Installing the plugin

1. Download the latest stable version of the plugin from the releases page
2. In Mattermost, go to System Console → Plugins → Management
3. Upload the plugin in the Upload Plugin section
4. Configure the plugin before you enable it ⬇️

Configuring the plugin

1. Enter the URL for your Nagios instance
   1. In Mattermost, go to System Console → Plugins → Nagios
   2. Set the Nagios URL
      1. Remember to add http:// or https:// at the beginning!
      2. Example: https://nagios.fedoraproject.org
2. Click Save to save the settings
3. In Mattermost, go to System Console → Plugins → Management and click Enable underneath the Nagios plugin
4. The plugin is now ready to use! ㊗️

Configuring the configuration files watcher

This step is optional, although highly recommended.

1. Regenerate the token for the configuration files watcher
   1. In Mattermost, go to System Console → Plugins → Nagios
   2. Click Regenerate to regenerate the token
   3. Copy the token (you are going to use it later)
2. Click Save to save the settings
3. Switch to the machine where Nagios is running (preferably)
   1. Download the latest stable version of the watcher from the releases page
   2. Move the watcher: chmod +x watcher1.0.1.linux-amd64 && sudo mv watcher1.0.1.linux-amd64 /usr/local/bin/watcher
   3. You will most probably want to run the watcher as a systemd service ⬇️

Running the watcher as a systemd service

Preparing the systemd service unit file

Adjust dir (default if not set: /usr/local/nagios/etc/), url, and token flags to your setup.

sudo bash -c 'cat << EOF > /etc/systemd/system/mattermost-plugin-nagios-watcher.service
[Unit]
Description=Nagios configuration files monitoring service
After=network.target

[Service]
Restart=on-failure
ExecStart=/usr/local/bin/watcher -dir /nagios/configuration/files/directory -url https://mattermost.server.address/plugins/nagios -token TheTokenFromStep1

[Install]
WantedBy=multi-user.target
EOF'

Starting the watcher

systemctl daemon-reload
systemctl enable mattermost-plugin-nagios-watcher.service
systemctl start  mattermost-plugin-nagios-watcher.service

Updating the plugin

To update the plugin repeat the Installing the plugin step.

Using the plugin

Interaction with the plugin involves using slash commands.

Slash commands overview

• nagios
  • get-logs <alerts|notifications>
    • [host|service <host name|service description>]
  • set-logs-limit <count>
  • set-logs-start-time <seconds>
  • subscribe <report|configuration-changes>
  • unsubscribe <report|configuration-changes>
  • set-report-frequency <minutes>

Slash commands documentation

nagios

nagios

This is the root command.

get-logs

get-logs <alerts|notifications> [<host|service> <host name|service description>]

This action allows you to get alerts or notifications.

Example: /nagios get-logs alerts

host

get-logs <alerts|notifications> host <host name>

This optional parameter allows you to get alerts or notifications from a specific host.

Example: /nagios get-logs alerts host bvmhost-p09-02.iad2.fedoraproject.org

service

get-logs <alerts|notifications> service <service description>

This optional parameter allows you to get alerts or notifications from a specific service.

Example: /nagios get-logs alerts service Swap-Is-Low

set-logs-limit

set-logs-limit <count>

This action allows you to limit the number of logs get-logs fetches.

Example: /nagios set-logs-limit 10

set-logs-start-time

set-logs-start-time <seconds>

This action allows you to specify the age of the oldest log get-logs fetches.

Example: /nagios set-logs-start-time 3600

subscribe

subscribe <report|configuration-changes>

This action allows you to subscribe to system monitoring reports or configuration changes on the current channel.

Example: /nagios subscribe report

unsubscribe

unsubscribe <report|configuration-changes>

This action allows you to unsubscribe from system monitoring reports or configuration changes on the current channel.

Example: /nagios unsubscribe configuration-changes

set-report-frequency

set-report-frequency <minutes>

This action allows you to set the frequency of system monitoring reports.

Example: /nagios set-report-frequency 60

Contributing

This repository uses the mattermost-plugin-starter-template. Therefore, developing this plugin is roughly the same as it is with every plugin using the template. All the necessary steps to develop are in the template's repository.

Developing the watcher

To build the watcher, you can use the following command:

env GOOS=linux GOARCH=amd64 go build -o dist/watcherX.Y.Z.linux-amd64 -a -v cmd/watcher/main.go

Of course, you can build the watcher for other operating systems and architectures too.

Reporting security vulnerabilities

You can report security vulnerabilities to @amwolff or @danielsz50 at the Community Server. Please adhere to the Responsible Disclosure Policy.