========================
Integration with Nagios®
========================

.. index:: Nagios

How to integrate |Product| with Nagios®
=======================================

Introduction
------------

Nagios® is a powerful tool to easily monitor IT networks and servers. It
can alert on reachability issues, software or hardware problems. But it
is much harder to alert on "End User Response Time". With the help of
the SNMP module of |Product|, you can add new checks on Nagios®
(and compatible softwares) to perform this and other advanced checks.

The script has been rewritten in |Product| 4.1 to reflect MIB changes.

Most of the command line interface has been kept and it now make use of Nagios®'s
performance data [#nagios_perf_data]_ to ease integration with other tools
(for example it allow graphing particular metrics [#pnp4nagios]_). The summary has also been
modified to give a better explanation.

.. [#nagios_perf_data] https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/3/en/perfdata.html
.. [#pnp4nagios] https://docs.pnp4nagios.org/

Prerequisites
-------------

|Product| side
~~~~~~~~~~~~~~~

SNMP access of BCA and BCN is disabled for the ``Free`` and ``Express``
versions of |Product|.

To request BCA or BCN status, you should create at least one BCA or BCN.

The SNMP daemon can be enabled via the `Nodes Management` page or via pulsar
(see the :ref:`snmp` section).

Nagios® Side
~~~~~~~~~~~~

A Nagios® script can be downloaded :download:`here <../snmp/nagios.py>`.

Your Nagios® installation must meet the following requirements:

- Nagios® v3+
- Python v2.4+
- Net-SNMP commands like ``snmpwalk`` [#net_snmp]_ (the script will warn you of
  missing commands)
- Our :download:`MIB <../snmp/PERFORMANCEVISION-MIB.txt>` installed (the script will
  also warn you if it can not find it)
- Script must be executable by Nagios® (``chmod +x``)
- Network access from Nagios® server to the datastore for SNMP protocol (UDP port 161)

.. [#net_snmp] http://net-snmp.sourceforge.net/download.html

Command-line usage
------------------

Help
~~~~

The ``-h`` or ``--help`` parameters will give a brief overview of the script functions.

Examples
~~~~~~~~

To request the `http` BCA on the datastore `10.0.0.1`.
The `public` community will be used (which is the default).

.. code-block:: bash

   $ check_pv     -H  10.0.0.1    -a http          -C public
   $ check_pv --host  10.0.0.1 --bca http --community public
   http BCA is CRIT | bcaDTTClt=35 ...


To request the BCN for the `/Local` and `/Internet` zones.

.. code-block:: bash

  $ check_pv     -H 10.0.0.1    -n '/Local - /Internet'
  $ check_pv --host 10.0.0.1 --bcn '/Local - /Internet'
  /Local <-> /Internet BCN is CRIT | bcnThrBwRatWarnBtoA=0 ...


To request the BCN for the `/Local` and `/Internet` zones from the `10.0.0.1` capture.

.. code-block:: bash

   $ check_pv -H 10.0.0.1 -n '/Local - /Internet (10.0.0.1)'
   /Local <-> /Internet BCN is CRIT | bcnThrBwRatWarnBtoA=0 ...


To request the BCN status from the `/Local` zone to `/Internet` zone.

.. code-block:: bash

   $ check_pv -H 10.0.0.1 -n '/Local - /Internet' --bcnatob
   /Local -> /Internet BCN is OK | bcnThrBwRatWarnBtoA=0 ...


To request the BCN status from the `/Internet` zone to `/Local` zone.

.. code-block:: bash

   $ check_pv -H 10.0.0.1 -n '/Local - /Internet' --bcnbtoa
   /Local <- /Internet BCN is CRIT | bcnThrBwRatWarnBtoA=0 ...

To find out the name of your BCA or BCN, you should be able to use the following
command:

.. code-block:: bash

   $ snmpwalk -m PERFORMANCEVISION-MIB -v 2c -c public 10.0.0.1 bcaName
   PERFORMANCEVISION-MIB::bcaName.121 = STRING: SalesForce
   ...

   $ snmpwalk -m PERFORMANCEVISION-MIB -v 2c -c public 10.0.0.1 bcnName
   PERFORMANCEVISION-MIB::bcnName.1 = STRING: /PV_Net/Local - /Internet
   ...



Nagios® configuration example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Your Nagios® configuration could declare the following commands
(supposing the script is stored in Nagios®'s plugin directory and is named ``check_pv``):

.. code-block:: text

   define command {
     command_name bca_check
     command_line /usr/lib/nagios/plugins/check_pv -H "$HOSTADDRESS$" -a $ARG1$
   }

   define command {
     command_name bcn_check
     command_line /usr/lib/nagios/plugins/check_pv -H "$HOSTADDRESS$" -n $ARG1$
   }

   define command {
     command_name bcn_check_atob
     command_line /usr/lib/nagios/plugins/check_pv -H "$HOSTADDRESS$" -n $ARG1$ --bcnatob
   }

   define command {
     command_name bcn_check_btoa
     command_line /usr/lib/nagios/plugins/check_pv -H "$HOSTADDRESS$" -n $ARG1$ --bcnbtoa
   }

The following host would match the previous example:

.. code-block:: text

   define host {
     host_name myhost
     alias myhost
     address 10.0.0.1
     use generic-host
   }

And the following services will check for BCA and BCN:

.. code-block:: text

   # http BCA check
   define service {
     name bca_http
     service_description bca_http
     use generic-service
     check_command bca_check!"http"
     host_name myhost
     # check_interval 15
     # retry_interval 5
   }

   # /Local /Internet BCN checks
   define service {
     name bcn_local_internet_both
     service_description bcn_local_internet_both
     use generic-service
     check_command bcn_check!"/Local - /Internet"
     host_name myhost
     # check_interval 15
     # retry_interval 5
   }

   define service {
     name bcn_local_internet_a
     service_description bcn_local_internet_a
     use generic-service
     check_command bcn_check_atob!"/Local - /Internet"
     host_name myhost
     # check_interval 15
     # retry_interval 5
   }

   define service {
     name bcn_local_internet_b
     service_description bcn_local_internet_b
     use generic-service
     check_command bcn_check_btoa!"/Local - /Internet"
     host_name myhost
     # check_interval 15
     # retry_interval 5
   }

.. gofigure:: ../img/screenshots/nagios/nagios_core.png

   Nagios® Core running some checks