README

Introduction/Notes
==================

This modules was inspired and based on the work of David Schmitt
The immerda project group adapted and improved this module. 
Mainly we made it using the new native puppet nagios commands
as well we made it more modular to fit for multidistro usage.

In it's current form, this module can be used on CentOS and Debian.

Basic Icinga (http://www.icinga.org/) was support added for Debian (see below).

Overview
========

To use the nagios resources, activate storeconfigs on the puppetmaster.


Monitor
-------

On one node the "nagios" class has to be included. By default this installs
apache using the "apache" module. To use lighttpd instead, include
"nagios::lighttpd", or, if the web server is not to be managed by puppet,
include "nagios::headless".


Hosts
-----

On a node which shall be monitored with nagios, include the "nagios::target".
This just creates a host declaration for this hosts "$fqdn".
Set the $nagios_parent variable in the node scope for enabling the reachability
features of nagios. If a node needs more customisation, use the
native "@@nagios_host" type directly (the double-ampersand declares the object
as an exported resource).

To monitor hosts not managed by puppet, add "nagios_host" objects to the
monitoring node. The required parameters are "alias", "address" and "use". If
you don't specify a proper nagios template with the "use" parameter, some extra
parameters are needed. You may look up the nagios documentation for this.


Services
--------

Services can be monitored by using the "nagios::service" component.

The simplest form is:

    nagios::service { 'check_http':
        check_command => 'http_port!80',
    }

The intention being obviously to put such declarations into a component defining
a service, thereby being automatically applied together with all instances of
the service.

Obviously, the check command must either be defined using nagios_command objects
(some are supplied in nagios::defaults::commands) or in the nagios configuration
files directly.

NRPE Services 
-------------

NRPE Services can be defines as i.e.:

    nagios::service { 'CPU Usage': use_nrpe => 'true', 
	check_command => "check_cpu", 
	nrpe_args => "-t 60"
    }


Caveats
=======


Consistency/Validation/Verification
-----------------------------------

After convergance of the configuration, the system is obviously consistent.
That is, all defined services are monitored. The problem is though, that it is
neither automatically valid - it is not guaranteed that all components declare a
nagios::service - and even if the configuration is valid it definitly is
unverified, since that is always a judgment call for an external observer.


Removal of nagios objects
-------------------------

This module does not automatically purge nagios objects such as hosts and
services that become absent from the manifests. One must set ensure => absent
to guarantee the removal of nagios objects from the configuration as desired.


Templates not supported using native types
------------------------------------------

Templates of hosts and services cannot yet be defined using native types. In
this module, they are provided using a file resource by the class
nagios::defaults::templates

See : http://projects.reductivelabs.com/issues/1180


Variables
=========

Options to change the behavior of the nagios module:

- nagios_allow_external_cmd: Set to true, if you'd like to ensure that your http
                             daemon can write to the external command file. You 
                             may also need to flip "check_external_commands" in
                             "nagios.cfg" to enable this functionality.


Icinga Support
==============
Use $nagios_use_icinga = 'true' to configure the Icinga fork instead of Nagios. 

Issues
------
Right now puppet will complain "err: Could not run Puppet configuration client: 
Could not find init script for 'icinga'" on the first attempt to install icinga. 
Please copy the icinga init script from this module to /etc/init.d:
  cp files/configs/Debian/icinga/icinga-init-script /etc/init.d/icinga

Todo
----
- Fix the issues above 

PNP4Nagios integration
======================
Currently, there are no pnp4nagios debian packages - you need to install pnp4nagios 
from source. See http://docs.pnp4nagios.org/pnp-0.6/start for installation notes.
The configuration is based on a self-built pnp4nagios debian package, so it might 
be better to package it, so you don't have trouble with /usr vs. /usr/local i.e.

You need to turn on "process_performance_data=1" in your nagios/icinga.cfg
Integration in the nagios/icinga webinterface is configured by including either the 
nagios::pnp4nagios or the nagios::pnp4nagios::popup class, the later one includes 
fancy popups when you hoover over the extra service action image.
For hosts you need to use the host-pnp definition, for services the srv-pnp def.
i.e. 

    @@nagios_service { "ping_example_node":
        use => "generic-service,srv-pnp",
        ...

    nagios_host { 'example_node':
            use => 'generic-host,host-pnp',
            ...


Examples
========

Usage example:

node nagios {

    include nagios::apache
    include nagios::defaults

	# Declare another nagios command
	nagios::command { http_port: command_line
=> '/usr/lib/nagios/plugins/check_http -p $ARG1$ -H $HOSTADDRESS$ -I
$HOSTADDRESS$'

	# Declare unmanaged hosts
	nagios_host {
        	'router01.mydomain.com':
                	alias => 'router01',
                    notes => 'MyDomain Gateway',
                    address => "10.0.0.1",
                    use => 'generic-host';
        	"router02.mydomain.com":
                    alias => 'router02',
                	address => '192.168.0.1',
                	parents => 'router01',
                    use => 'generic-host';
	}

}


node target {

	# Monitor this host
	$nagios_parents = 'router01'
	include nagios::target

	# monitor a service
	$apache2_port = 8080
	include apache2

	# This actually does this somewhere:
	#nagios::service { "http_${apache2_port}":
	#       check_command => "http_port!${apache2_port}"
	#}

}

TODO
====

- Provide a default http vhost
- Add facility to deploy nagios plugins
- Add more useful commands and services
- When Puppet will support them, supply nagios templates using native types


License
=======

Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
See the file LICENSE in the top directory for the full license.