================================================================================
monitoring-plugins for Debian
================================================================================

below is a collection of various bits of information that might be
helpful to users of monitoring-plugins in debian.

================================================================================
plugins and dependencies
================================================================================

some plugins require additional libraries and programs. to prevent you from
having to install dozens of further packages that you don't actually need,
there is no strict dependency on some of them.
see /usr/share/doc/monitoring-plugins-standard/README.Debian.plugins for details.

================================================================================
how to use plugins
================================================================================

- you can invoke the plugins with "--help" to get help how to use the plugins
- a short usage can be usually obtained by just running the check without
  arguments
- if you need more information, how to use plugins, have a look at:
  http://www.monitoring-plugins.org/doc/faq/index.html

================================================================================
predefined / shipped check commands
================================================================================

we are shipping predefined checks, to make users life easier. at the first look,
this seems really nice. providing checks for every special case (see check_http)
may end up in a unsupportable state of our package.
for example one check is testing a service on a special port, where we provide
a check command. after some time, this service changes its port after some time,
cause the developers of this software decided for any reason to do so. changing
the port in the existing check will break installations, which are using the
service with the old behavior. new users will getting confused of not using the
correct port for their shiny service.
cause of this conflict, we try to provide flexible checks, which may look
complicated at first, but giving the user more power.

a good example for using such a general approach is check_nt / check_nscp. some
3rd party sources (guessing they can traced back to one) are suggesting using
two args in some way like:

define command {
command_name	check_nt
command_line	$USER1$/check_nt -H $HOSTADDRESS$ -p 12489 -v $ARG1$ $ARG2$
}

beside specifying not the port, we are not using "$ARG2$", cause all arguments
of "$ARG2$" can just be used in "$ARG1$" without any problem.
this gives you the possibility to use every check in your service definition,
without the problem about changes in your environment. you can easily change
your service definition as soon your environment changes without breaking the
command definition.

================================================================================
different plugin packages and how to avoid installing massive dependencies
================================================================================

if you're frustrated by all the crap being brought in by monitoring-plugins (for
example if you're installing nrpe or nsca on a remote host), try the
monitoring-plugins-basic package.

================================================================================
plugins needing root privilege or capabilities(7) set
================================================================================

the check_dhcp, check_icmp and maybe others plugins require root privileges or
capabilities(7) to run, because of the low-level packet mangling that they
perform. but, in the interest of the "safe default", these plugins will not
be installed with the suid bit set.
if setcap is able set the necessary capabilities, you are fine. if the setcap
binary is not installed or not able to set the capabilities, you need to
either set the capabilities (eg. cap_net_raw+ep) for your own or provide root
privileges. You could go the lazy way and install libcap2-bin and run the
following afterwards:

# /var/lib/dpkg/info/monitoring-plugins-basic.postinst configure

there are two recommended ways about providing root priviles to your plugins
on your system:

- set the suid bit with dpkg-statoverride:

# dpkg-statoverride --update --add root nagios 4750 $plugin

where $plugin is the specific plugin you want to grant such privileges.

- use sudo to grant the permissions and modify your plugin config

of these two, the first is recommended because it's the simplest and
has the same effect as the second.
