.. -*- mode: rst -*-

.. _server-plugins-generators-nagiosgen:

=========
NagiosGen
=========

This page describes the installation and use of the `NagiosGen`_ plugin.

.. _NagiosGen: http://trac.mcs.anl.gov/projects/bcfg2/browser/src/lib/Server/Plugins/NagiosGen.py

Update ``/etc/bcfg2.conf``, adding NagiosGen to plugins::

    plugins = Base,Bundler,Cfg,...,NagiosGen

Create the NagiosGen directory::

    $ mkdir /var/lib/bcfg2/NagiosGen

Create default host, and group specs in:

``/var/lib/bcfg2/NagiosGen/default-host.cfg``::

    define host{
            name                            default
            check_command                   check-host-alive
            check_interval                  5
            check_period                    24x7
            contact_groups                  admins
            event_handler_enabled           1
            failure_prediction_enabled      1
            flap_detection_enabled          1
            initial_state                   o
            max_check_attempts              10
            notification_interval           0
            notification_options            d,u,r
            notification_period             workhours
            notifications_enabled           1
            process_perf_data               0
            register                        0
            retain_nonstatus_information    1
            retain_status_information       1
            retry_interval                  1
            }

``/var/lib/bcfg2/NagiosGen/default-group.cfg``::

    define service{
            name                            default-service
            active_checks_enabled           1
            passive_checks_enabled          1
            obsess_over_service             0
            check_freshness                 0
            notifications_enabled           1
            event_handler_enabled           1
            flap_detection_enabled          1
            process_perf_data               0
            retain_status_information       1
            retain_nonstatus_information    1
            is_volatile                     0

            check_period                    24x7
            max_check_attempts              4
            check_interval                  5
            retry_interval                  1
            contact_groups                  admins
            notification_options            w,u,c,r
            notification_interval           0
            notification_period             workhours
            }

Create group configuration files (Named identical to Bcfg2 groups) and
add services, and commands specific to the hostgroup (Bcfg2 group) in

``/var/lib/bcfg2/NagiosGen/base-group.cfg``::

    define hostgroup{
            hostgroup_name  base
            alias           base
            notes           Notes
    }

    define service{
            service_description             NTP
            check_command                   check_ntp!
            use                             default-service
            hostgroup_name                  base
            }

    define command{
            command_name    check_ssh
            command_line    $USER1$/check_ssh $ARG1$ $HOSTADDRESS$
            }

    define service{
            service_description             SSH
            check_command                   check_ssh!
            use                             default-service
            hostgroup_name                  base
            }

``/var/lib/bcfg2/NagiosGen/web-server-group.cfg``::

    define hostgroup{
            hostgroup_name  web-server
            alias           Port 80 Web Servers
            notes           UC/ANL Teragrid Web Servers Running on Port 80
    }

    define command{
            command_name    check_http_80
            command_line    $USER1$/check_http $HOSTADDRESS$
            }

    define service{
            service_description             HTTP:80
            check_command                   check_http_80!
            use                             default-service
            hostgroup_name                  web-server
            }

Create a nagios Bcfg2 bundle ``/var/lib/bcfg2/Bundler/nagios.xml``

.. code-block:: xml

    <Bundle name='nagios' version='2.0'>
      <Path name='/etc/nagiosgen.status'/>
      <Group name='rh'>
        <Group name='nagios-server'>
          <Path name='/etc/nagios/nagiosgen.cfg'/>
          <Package name='libtool-libs'/>
          <Package name='nagios'/>
          <Package name='nagios-www'/>
          <Service name='nagios'/>
        </Group>
      </Group>
      <Group name='debian-lenny'>
        <Group name='nagios-server'>
          <Path name='/etc/nagios3/nagiosgen.cfg'
                      altsrc='/etc/nagios/nagiosgen.cfg'/>
          <Package name='nagios3'/>
          <Package name='nagios3-common'/>
          <Package name='nagios3-doc'/>
          <Package name='nagios-images'/>
          <Service name='nagios3'/>
        </Group>
      </Group>
    </Bundle>

Assign clients to nagios groups in
``/var/lib/bcfg2/Metadata/groups.xml``

.. code-block:: xml

    <Group name='nagios'>
      <Bundle name='nagios'/>
    </Group>

    <Group name='nagios-server'>
      <Bundle name='nagios'/>
    </Group>

Update nagios configuration file to use ``nagiosgen.cfg``::

    cfg_file=/etc/nagios/nagiosgen.cfg

Note that some of these files are built on demand, each time a client
in group "nagios-server" checks in with the Bcfg2 server. Local nagios
instances can be configured to use the NagiosGen directory in the Bcfg2
repository directly.

Fine-Grained Configuration
==========================

NagiosGen can be configured in excruciating detail by editing
``NagiosGen/config.xml``, which will let you set individual Nagios
options for hosts or groups.  E.g.:

.. code-block:: xml

    <NagiosGen>
       <Group name="datacenter-2">
          <Option name="parents">dc-2-switch</Option>
       </Group>
       <Group name="non-production">
          <Option name="notification_period">workhours</Option>
          <Option name="notification_options">d</Option>
       </Group>
       <Client name="foo.example.com">
          <Option name="max_check_attempts">10</Option>
       </Client>
    </NagiosGen>

Obviously the sort of fine-grained control you get from this overlaps
to some degree with Nagios' own templating, so use it wisely and in
moderation.

``NagiosGen/config.xml`` replaces the files
``Properties/NagiosGen.xml`` and ``NagiosGen/parents.xml`` in older
versions of Bcfg2; your old configs can be migrated using the
``nagiosgen-convert.py`` tool.  The plugin does contain a
backwards-compatibility layer for those older config files, but
``NagiosGen/config.xml`` must exist (even if empty) for the plugin to
function.