From 0e2619133e2584d67b77c03fda231357a74a73f1 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Fri, 11 Mar 2022 18:42:16 +0100 Subject: [PATCH] Improve README, put configuration files for Icinga into separate folder --- README.md | 136 +++++++++++++++++---------------- icinga2/synology-command.conf | 35 +++++++++ icinga2/synology-host.conf | 11 +++ icinga2/synology-services.conf | 15 ++++ 4 files changed, 133 insertions(+), 64 deletions(-) create mode 100644 icinga2/synology-command.conf create mode 100644 icinga2/synology-host.conf create mode 100644 icinga2/synology-services.conf diff --git a/README.md b/README.md index 5d901d5..6295244 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,45 @@ # check_synology [![Release](https://img.shields.io/github/release/wernerfred/check_synology.svg)](https://github.com/wernerfred/check_synology/releases) -This plugin uses ```snmpv3``` with ```MD5``` + ```AES``` to check a lot of different values on your Synology DiskStation. -This check plugin is based on ```easysnmp```, you can install it on your system with ```pip install easysnmp```. -Note that ```easysnmp``` needs ```net-snmp```, so you might also need to install ```libsnmp-dev``` and -```snmp-mibs-downloader``` on your system, like ```apt install --yes libsnmp-dev```. +## About -Usage: -``` -> python3 check_synology.py -h -usage: check_synology.py hostname username authkey privkey {mode} [-h] [-w W] [-c C] [-p PORT] +A monitoring plugin for checking different values on a Synology DiskStation, +compatible with Nagios and Icinga. + +The plugin was tested successfully with DS215j, DS216+ and DS718+ models. +For communication, it uses `snmpv3` with `MD5` + `AES`. + +If you want to add a missing check or another value, you are most welcome to +submit a patch / pull request. As a reference for discovering the right +MIBs / OIDs, please have a look at the official [Synology DiskStation MIB Guide]. + + +## Setup + +`check_synology` is based on the [easysnmp] SNMP library, which is a binding to +the [Net-SNMP package]. You might need to install the corresponding packages on +your operating system. + +An example to invoke the installation on a Debian-based system is: +```shell +apt install --yes libsnmp-dev snmp-mibs-downloader +pip install git+https://github.com/wernerfred/check_synology ``` -Example check: + +## Usage +```shell +check_synology --help ``` -> python3 check_synology.py hostname snmp_user auth_key priv_key load -OK - load average: 1.48, 1.71, 1.74 | load1=1.48c load5=1.71c load15=1.74c + +```shell +check_synology +usage: check_synology [-h] [-w W] [-c C] [-p PORT] hostname username authkey privkey {load,memory,disk,storage,update,status} ``` -Available modes: +A custom port can be specified by using `-p`. The default value is `161`. + +### Available modes | mode | description | warning/critical | | :-----: | -------------------------------------------------------------------------- | ----------------------------------- | @@ -29,68 +50,50 @@ Available modes: | update | Shows the current DSM version and if DSM update is available | set w/c to any int this triggers:
warning if available and critical
if other than un-/available | | status | Shows model, s/n, temp and status of system, fan, cpu fan and power supply | if temp higher than w/c in °C | -Note: A custom port can be specified by using ```-p```. The port defaults to 161. -Example ```CheckCommand``` for use with ```icinga2```: -``` -object CheckCommand "check_synology" { - command = ["/usr/bin/python3", PluginDir + "/check_synology.py" ] - - arguments = { - "--host" = { - skip_key = true - order = 0 - value = "$synology_host$" - } - "--username" = { - skip_key = true - order = 1 - value = "$synology_snmp_user$" - } - "--authkey" = { - skip_key = true - order = 2 - value = "$synology_snmp_authkey$" - } - "--privkey" = { - skip_key = true - order = 3 - value = "$synology_snmp_privkey$" - } - "--mode" = { - skip_key = true - order = 4 - value = "$synology_mode$" - } - "-w" = "$synology_warning$" - "-c" = "$synology_critical$" - } -} -``` -Example ```Service``` for use with ```icinga2```: + +## Example check +```shell +check_synology hostname snmp_user auth_key priv_key load +OK - load average: 1.48, 1.71, 1.74 | load1=1.48c load5=1.71c load15=1.74c ``` -apply Service "syno-load" { - import "generic-service" - check_command = "check_synology" - vars.synology_mode = "load" - vars.synology_host = "$address$" - - vars.synology_warning = "$synology_load_w$" - vars.synology_critical = "$synology_load_c$" +## Icinga 2 integration - assign where host.vars.os == "DSM" -} +For integrating the check program into Icinga 2, you can use the configuration files +in the ``icinga2`` subdirectory. You can easily acquire the files using: +```shell +wget https://raw.githubusercontent.com/wernerfred/check_synology/master/icinga2/synology-command.conf +wget https://raw.githubusercontent.com/wernerfred/check_synology/master/icinga2/synology-services.conf +wget https://raw.githubusercontent.com/wernerfred/check_synology/master/icinga2/synology-host.conf ``` -Make sure to set ```synology_snmp_user```, ```synology_snmp_autkey``` and ```synology_snmp_privkey``` (e.g. in the host config file). +In order to put the `check_synology` program at the right location aligned with the +definition within `synology-command.conf`, regardless where it has been installed +on your system, use: + +```shell +ln -s $(which check_synology) /usr/lib/nagios/plugins/check_synology +``` -If you want to add a missing check or another value to be added than you can use the [official Synology MIB Guide](https://global.download.synology.com/download/Document/MIBGuide/Synology_DiskStation_MIB_Guide.pdf) as a hint for the right MIBs / OIDs and start a pull-request. -This plugin was tested successfully with DS215j, DS216+ and DS718+. +## Development -Note: As of version 0.2 and higher only python3 is supported. Version 0.1 was the last python2 compatible release. +For setting up a development sandbox, you might want to follow this walkthrough. + +Acquire sources: +```shell +git clone https://github.com/wernerfred/check_synology +cd check_synology +``` + +Install program in development mode into a Python virtual environment: +```shell +python3 -m venv .venv +source .venv/bin/activate +pip install --editable=. +``` ## Contributors ✨ @@ -114,3 +117,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! + + +[easysnmp]: https://pypi.org/project/easysnmp/ +[Net-SNMP package]: http://www.net-snmp.org/ +[Synology DiskStation MIB Guide]: https://global.download.synology.com/download/Document/MIBGuide/Synology_DiskStation_MIB_Guide.pdf diff --git a/icinga2/synology-command.conf b/icinga2/synology-command.conf new file mode 100644 index 0000000..4671b60 --- /dev/null +++ b/icinga2/synology-command.conf @@ -0,0 +1,35 @@ +// `check_synology` `CheckCommand` definition for Icinga 2 + +object CheckCommand "check_synology" { + command = [ PluginDir + "/check_synology" ] + + arguments = { + "--host" = { + skip_key = true + order = 0 + value = "$synology_host$" + } + "--username" = { + skip_key = true + order = 1 + value = "$synology_snmp_user$" + } + "--authkey" = { + skip_key = true + order = 2 + value = "$synology_snmp_authkey$" + } + "--privkey" = { + skip_key = true + order = 3 + value = "$synology_snmp_privkey$" + } + "--mode" = { + skip_key = true + order = 4 + value = "$synology_mode$" + } + "-w" = "$synology_warning$" + "-c" = "$synology_critical$" + } +} diff --git a/icinga2/synology-host.conf b/icinga2/synology-host.conf new file mode 100644 index 0000000..66cfd40 --- /dev/null +++ b/icinga2/synology-host.conf @@ -0,0 +1,11 @@ +// `check_synology` example host configuration snippet for Icinga 2 + +object Host "foo.example.org" { + + // Configuration section for `check_synology` + vars.synology_host = "192.168.178.111" + vars.synology_snmp_user = "nagios" + vars.synology_snmp_authkey = "secret" + vars.synology_snmp_privkey = "secret" + +} diff --git a/icinga2/synology-services.conf b/icinga2/synology-services.conf new file mode 100644 index 0000000..779a39d --- /dev/null +++ b/icinga2/synology-services.conf @@ -0,0 +1,15 @@ +// `check_synology` example service configuration snippet for Icinga 2 + +apply Service "syno-load" { + import "generic-service" + + check_command = "check_synology" + + vars.synology_mode = "load" + vars.synology_host = "$address$" + + vars.synology_warning = "$synology_load_w$" + vars.synology_critical = "$synology_load_c$" + + assign where host.vars.os == "DSM" +}