Enhance and write better documentation

README.md

@@ -1,17 +1,52 @@
 # Manubulon SNMP Plugins
 
-## General information
+#### Table of Contents
+
+1. [About](#about)
+2. [License](#license)
+3. [Support](#support)
+4. [Requirements](#requirements)
+5. [Installation](#installation)
+6. [Configuration](#configuration)
+7. [FAQ](#faq)
+8. [Thanks](#thanks)
+9. [Contributing](#contributing)
+
+## About
 
 Manubulon SNMP plugins is a set of Icinga/Nagios plugins
-to check hosts/devices using the SNMP protocol. Check
-[http://nagios.manubulon.com](http://nagios.manubulon.com) for more details.
+to check hosts/devices using the SNMP protocol.
+
+### Plugin Overview
+
+Plugin                        | Description
+------------------------------|----------------------------------------
+check\_snmp\_storage          | Storage checks (disks, swap, memory, etc.)
+check\_snmp\_int              | Interface states, usage on hosts, switches, routers, etc.
+check\_snmp\_process          | Running processes, their number, used CPU and memory.
+check\_snmp\_load             | Load/CPU checks
+check\_snmp\_mem              | Memory and swap usage
+check\_snmp\_env              | Environmental status of fan, temp, power supplies.
+check\_snmp\_vrrp             | Interface state of a VRRP cluster
+check\_snmp\_cpfw             | Checkpoint Firewall-1 status
+check\_snmp\_win              | Windows services
+check\_snmp\_css              | CSS service states
+check\_snmp\_nsbox            | Nsbox VHost and diode status
+check\_snmp\_boostedge        | Boostedge services
+check\_snmp\_linkproof\_ndr   | Linkproof NHR
+
+## License
+
+These plugins are licensed under the terms of the GNU General Public License.
+You will find a copy of this license in the LICENSE file included in the source package.
 
-This is a fork using a [cvs2git import](http://sourceforge.net/projects/nagios-snmp/develop) which includes community patches.
+## Support
 
-The original project was last active in 2007 so this project
-helps collect all patches and feature requests.
+Join the [Icinga community channels](https://www.icinga.com/about/get-involved/) for questions.
 
-Feel free to use & distribute it under the original license.
+If you want to help maintain this project, just contact
+me on [twitter](https://twitter.com/dnsmichi) and I'll
+happily grant commit access.
 
 ## Requirements
 
@@ -25,41 +60,30 @@ Feel free to use & distribute it under the original license.
   [Crypt::Rijndael](http://search.cpan.org/~leont/Crypt-Rijndael-1.13/Rijndael.pm) and
   [Digest::HMAC](http://search.cpan.org/~gaas/Digest-HMAC-1.03/lib/Digest/HMAC.pm)
 
-Distribution-specific packages:
-* Debian/Ubuntu: `libnet-snmp-perl` and `libcrypt-des-perl libcrypt-rijndael-perl libdigest-hmac-perl`
-* RHEL/CentOS: `perl-Net-SNMP perl-Getopt-Long` and `perl-Crypt-DES perl-Crypt-Rijndael perl-Digest-HMAC`
+## Installation
 
-Perl, default directory and temp files location can be changed using the install.sh script.
+Detailed installation instructions can be found [here](doc/02-Installation.md).
 
-`utils.pm` from `Monitoring::Plugin::Perl` is no longer required.
+## Configuration
 
-## Documentation
+Proceed [here](doc/03-Configuration.md) to get details on the configuration with Icinga 2, Icinga 1.x, etc.
 
-The original documentation and sourcecode is located at
-[http://nagios.manubulon.com](http://nagios.manubulon.com).
-A website copy was added underneath the `doc/` directory.
+## FAQ
 
-## Support
-
-You may create [GitHub issues](https://github.com/dnsmichi/manubulon-snmp)
-as well. I do have a lot of things on my plate so best is to send in a tested (!) patch at the same time.
-
-If you want to help maintain this project, just contact
-me on [twitter](https://twitter.com/dnsmichi) and I'll
-happily grant commit access.
 
-You may head over to [monitoring-portal.org community](http://www.monitoring-portal.org)
-for questions and feedback.
+## Thanks
 
-The original support tracker is still located on [sourceforge](https://sourceforge.net/p/nagios-snmp/feature-requests/).
+Patrick Proy for creating and maintaining the original plugins.
 
-## Development
+## Contributing
 
-Fork this repository on Github and send in a PR.
+Fork this repository on GitHub and send in a PR.
 
 There's a `.perltidyrc` file in the main repository tree. If you are uncertain about the coding style,
 create your patch and then run:
 
-    $ perltidy -b plugins/*.pl
+```
+$ perltidy -b plugins/*.pl
+```
 
 This requires the `perltidy` module being installed.

doc/01-About.md

@@ -0,0 +1,30 @@
+# About Manubulon SNMP Plugins <a href="manubulon-snmp-plugins-about"></a>
+
+Manubulon SNMP plugins is a set of Icinga/Nagios plugins
+to check hosts/devices using the SNMP protocol.
+
+Please find more insights in the following chapters:
+
+* [Installation](02-Installation.md)
+* [Configuration](03-Configuration.md)
+* [Plugins](04-Plugins.md)
+
+
+
+## History <a href="manubulon-snmp-plugins-about-history"></a>
+
+These plugins have been written by Patrick Proy several years ago.
+
+Many community members still use them, but development and patches
+stopped.
+
+I've used these plugins in my previous job, and decided to fork them
+into this repository. Many patches have been applied, and put into
+official releases for packagers.
+
+This is reflected by moving each plugin into a v2.x version although
+there are not so many changes.
+
+I don't have a test system/hardware nor do much with these plugins these days.
+Still this repository allows community members to send in their patches
+and discuss bugs and feature requests.

doc/02-Installation.md

@@ -0,0 +1,56 @@
+# Manubulon SNMP Plugins Installation <a href="manubulon-snmp-plugins-installation"></a>
+
+The plugins rely on the `Net::SNMP` Perl library for fetching
+data from SNMP enabled hosts.
+
+## Prerequisites <a href="manubulon-snmp-plugins-installation-required-prerequisites"></a>
+
+### RHEL/CentOS EPEL Repository <a href="manubulon-snmp-plugins-installation-epel"></a>
+
+RHEL/CentOS requires the EPEL repository:
+
+```
+yum -y install epel-release
+yum makecache
+```
+
+If you are using RHEL you need enable the `optional` repository and then install
+the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
+
+## Perl Dependencies <a href="manubulon-snmp-plugins-installation-perl-dependencies"></a>
+
+Debian/Ubuntu:
+
+```
+apt-get -y install libnet-snmp-perl libcrypt-des-perl libcrypt-rijndael-perl libdigest-hmac-perl
+```
+
+RHEL/CentOS/Fedora:
+
+```
+yum -y install perl-Net-SNMP perl-Getopt-Long perl-Crypt-DES perl-Crypt-Rijndael perl-Digest-HMAC
+```
+
+## Plugin Setup <a href="manubulon-snmp-plugins-installation-plugins"></a>
+
+Debian/Ubuntu:
+
+```
+install -o root -g root -m750 plugins/*.pl /usr/lib/nagios/plugins/
+```
+RHEL/CentOS/Fedora:
+
+```
+install -o root -g root -m750 plugins/*.pl /usr/lib64/nagios/plugins/
+```
+
+Proceed with inspecting the plugins `--help` parameter in [this chapter](04-Plugins.md).
+
+Next up: Integrate the plugins into your monitoring by adding [configuration](03-Configuration.md).
+
+## Advanced Hints <a href="manubulon-snmp-plugins-installation-advanced"></a>
+
+Perl, default directory and temp files location can be changed using the install.sh script.
+
+`utils.pm` from `Monitoring::Plugin::Perl` is no longer required.
+

doc/03-Configuration.md

@@ -0,0 +1,104 @@
+# Manubulon SNMP Plugins Configuration <a href="manubulon-snmp-plugins-configuration"></a>
+
+Each plugin requires a command definition which defines the command line parameters
+and arguments passed from service checks.
+
+* [Icinga 2](03-Configuration.md#manubulon-snmp-plugins-configuration-icinga-2) integration
+* [Icinga 1.x/Naemon/Nagios](03-Configuration.md#manubulon-snmp-plugins-configuration-icinga-1) integration
+
+## Icinga 2 <a href="manubulon-snmp-plugins-configuration-icinga-2"></a>
+
+The Icinga 2 Template Library (ITL) already provides many [CheckCommand definitions](https://www.icinga.com/docs/icinga2/latest/doc/10-icinga-template-library/#plugin-check-commands-for-manubulon-snmp)
+out of the box. This enables you to just use the CheckCommand object and focus
+on your service apply rules.
+
+### Icinga 2: Best Practices <a href="manubulon-snmp-plugins-configuration-icinga-2-best-practices"></a>
+
+Best practice is to store the credentials in a separate constant:
+
+```
+vim /etc/icinga2/constants.conf
+
+const ManubulonSnmpCommunity = "icingasnmpro"
+```
+
+Define a generic SNMP service template and set common attributes.
+
+```
+template Service "snmp-template" {
+  vars.snmp_community = ManubulonSnmpCommunity
+}
+```
+### Icinga 2: Apply Rules <a href="manubulon-snmp-plugins-configuration-icinga-2-apply"></a>
+
+
+Define service apply rules like this:
+
+```
+apply Service "snmp-memory" {
+  import "snmp-template"
+  check_command = "snmp-memory"
+
+  vars.snmp_warn = "50,0"
+  vars.snmp_crit = "80,0"
+
+  assign where "snmp" in host.groups
+}
+
+apply Service "snmp-storage /var" {
+  import "snmp-template"
+  check_command = "snmp-storage"
+
+  vars.snmp_warn = "50"
+  vars.snmp_crit = "80"
+  vars.snmp_storage_name = "/var"
+
+  assign where "snmp" in host.groups
+}
+
+apply Service "snmp-storage" {
+  import "snmp-template"
+  check_command = "snmp-storage"
+
+  vars.snmp_warn = "50"
+  vars.snmp_crit = "80"
+
+  assign where "snmp" in host.groups
+}
+```
+
+### Icinga 2: Apply For Rules <a href="manubulon-snmp-plugins-configuration-icinga-2-apply-for"></a>
+
+A more complex example using apply for rules is to store the
+monitored storage disks on the host. This allows to generate
+service objects in a more efficient way.
+
+```
+object Host "snmp-host" {
+  check_command = "hostalive"
+
+  vars.snmp_storage["/"] = {
+    snmp_warn = "80"
+    snmp_crit = "90"
+  }
+  vars.snmp_storage["/var"] = {
+    snmp_warn = "60"
+    snmp_crit = "90"
+  }
+}
+
+apply Service "snmp-storage-" for (storage_name => config in host.vars.snmp_storage) {
+  import "snmp-template"
+
+  display_name = "Storage: " + storage_name
+
+  vars += config
+  vars.snmp_storage_name = storage_name
+}
+```
+
+
+## Icinga 1.x/Naemon/Nagios <a href="manubulon-snmp-plugins-configuration-icinga-1"></a>
+
+You need to write a check command definition and use that in your service definitions.
+Please refer to [this documentation](http://nagios.manubulon.com/index_commands.html).