A brief guide to writing Nagios plugins
=======================================

What plugins are for
--------------------

Nagios runs /host/ and /service/ checks using plugins.  Host checks are
designed to check if the host is OK, service checks do the same for individual
services on that host.  As the Nagios administrator / plugin author, you get
to define exactly what "host", "service" and "OK" mean here.

The result of each check is a status code (one of OK, WARNING, CRITICAL, or
(rarely) UNKNOWN), and a single line of status text.

The status code is used by Nagios (in combination with the Nagios
configuration) to decide when to raise an alert, when to contact people, etc.
The status text is unused by Nagios, except that it is displayed on the Nagios
user interface for human consumption, and is (depending on configuration) sent
out in notification emails etc.

For example:

  code      text
  OK        http OK, got status 200 in 0.173 sec
  WARNING   http WARNING, got status 200 in 7.336 sec
  CRITICAL  http CRITICAL, got status 500 in 0.249 sec

Plugin specification
--------------------

Plugins are executables - binaries, shell scripts, whatever - which are
invoked as follows:

 - uid/gid: as per Nagios (or the nrpe daemon) - usually the "nagios" user

 - arguments: as per the Nagios / nrpe configuration.  You get to define what
   options / arguments your plugin accepts, and the Nagios administrator gets
   to define what options / arguments are passed to your plugin.

 - stdin is /dev/null (or closed?).  Basically, don't read from stdin.

 - stderr is /dev/null (?).  Basically, assume that in normal running,
   standard error is lost.

When your plugin executes, it should write its status text to stdout (with a
terminating newline), and its exit status should be as follows:

  0 for OK
  1 for WARNING
  2 for CRITICAL
  3 for UNKNOWN

Other guidelines
----------------

Your plugin should execute quickly.  The Nagios configuration will specify the
maximum time that a plugin is allowed to run - typically 10 seconds.

In particular, if your plugin needs (for example) to make some expensive
database queries in order to determine its result, you might want to have that
computation performed external to the plugin, save its results somewhere, then
have the plugin read those pre-computed results, which should be a lot quicker
- at the expense of being potentially out of date.

Although Nagios only expects one line of output text, you might like to
provide the ability for more detailed output - for example, provide a
"--verbose" option (only to be used by humans running the plugin by hand, not
when invoked by Nagios), causing extract diagnostic output to be produced.