![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 9e1da5019dac5796937d6787a15ae9e729805c03..e3fe4c8c192f6d9a1bb272de2910160a449a4cf3 100644 (file)
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" >
<book>
<title>Nagios Plug-in Developer Guidelines</title>
</affiliation>
</author>
+ <author>
+ <firstname>Ton</firstname>
+ <surname>Voon</surname>
+ <affiliation>
+ <address><email>tonvoon@users.sourceforge.net</email></address>
+ </affiliation>
+ </author>
+
+ <author>
+ <firstname>Jeremy T</firstname>
+ <surname>Bouse</surname>
+ <affiliation>
+ <address><email>undrgrid@users.sourceforge.net</email></address>
+ </affiliation>
+ </author>
</authorgroup>
<pubdate>2002</pubdate>
<revhistory>
<revision>
- <revnumber>0.4</revnumber>
- <date>2 May 2002</date>
+ <revnumber>$Revision$</revnumber>
+ <date>$Date$</date>
</revision>
</revhistory>
<copyright>
- <year>2000 2001 2002</year>
- <holder>Karl DeBisschop, Ethan Galstad,
- Hugo Gayosso, Stanley Hopcroft, Subhendu Ghosh</holder>
+ <year>2000 - 2004</year>
+ <holder>Nagios Plugins Development Team</holder>
</copyright>
</bookinfo>
the plug-in developers and encourage the standarization of the
different kind of plug-ins: C, shell, perl, python, etc.</para>
- <para>Nagios Plug-in Development Guidelines Copyright (C) 2000 2001
- 2002
- Karl DeBisschop, Ethan Galstad, Hugo Gayosso, Stanley Hopcroft,
- Subhendu Ghosh</para>
+ <para>Nagios Plug-in Development Guidelines Copyright (C) 2000-2003
+ (Karl DeBisschop, Ethan Galstad, Stanley Hopcroft, Subhendu Ghosh, Ton Voon, Jeremy T. Bouse)</para>
<para>Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and this
<literallayout>
gnu make 3.79
automake 1.6
- autoconf 2.52
+ autoconf 2.54
gettext 0.11.5
</literallayout>
<section id="PlugOutput"><title>Plugin Output for Nagios</title>
<para>You should always print something to STDOUT that tells if the
- service is working or why its failing. Try to keep the output short -
+ service is working or why it is failing. Try to keep the output short -
probably less that 80 characters. Remember that you ideally would like
the entire output to appear in a pager message, which will get chopped
off after a certain length.</para>
when it notifies contacts about potential problems. If you print
multiple lines, you're out of luck. Remember, keep it short and
to the point.</para>
+
+ <para>Output should be in the format:</para>
+ <literallayout>
+ METRIC STATUS: Information text
+ </literallayout>
+ <para>However, note that this is not a requirement of the API, so you cannot depend on this
+ being an accurate reflection of the status of the service - the status should always
+ be determined by the return code.</para>
</section>
<section><title>Verbose output</title>
-v options for additional verbosity, up to a maximum of 3. The standard
type of output should be:</para>
- <table id="verbose_levels"><title>Verbose output levels</title>
+ <table id="verboselevels"><title>Verbose output levels</title>
<tgroup cols="2">
<thead>
<row>
</thead>
<tbody>
<row>
- <entry align=center><para>0</para></entry>
+ <entry align="center"><para>0</para></entry>
<entry><para>Single line, minimal output. Summary</para></entry>
</row>
<row>
- <entry align=center><para>1</para></entry>
+ <entry align="center"><para>1</para></entry>
<entry><para>Single line, additional information (eg list processes that fail)</para></entry>
</row>
<row>
- <entry align=center><para>2</para></entry>
+ <entry align="center"><para>2</para></entry>
<entry><para>Multi line, configuration debug output (eg ps command used)</para></entry>
</row>
<row>
- <entry align=center><para>3</para></entry>
+ <entry align="center"><para>3</para></entry>
<entry><para>Lots of detail for plugin problem diagnosis</para></entry>
</row>
</tbody>
</thead>
<tbody>
<row>
- <entry align=center><para>0</para></entry>
- <entry valign=middle><para>OK</para></entry>
+ <entry align="center"><para>0</para></entry>
+ <entry valign="middle"><para>OK</para></entry>
<entry><para>The plugin was able to check the service and it
appeared to be functioning properly</para></entry>
</row>
<row>
- <entry align=center><para>1</para></entry>
- <entry valign=middle><para>Warning</para></entry>
+ <entry align="center"><para>1</para></entry>
+ <entry valign="middle"><para>Warning</para></entry>
<entry><para>The plugin was able to check the service, but it
appeared to be above some "warning" threshold or did not appear
to be working properly</para></entry>
</row>
<row>
- <entry align=center><para>2</para></entry>
- <entry valign=middle><para>Critical</para></entry>
+ <entry align="center"><para>2</para></entry>
+ <entry valign="middle"><para>Critical</para></entry>
<entry><para>The plugin detected that either the service was not
running or it was above some "critical" threshold</para></entry>
</row>
<row>
- <entry align=center><para>3</para></entry>
- <entry valign=middle><para>Unknown</para></entry>
+ <entry align="center"><para>3</para></entry>
+ <entry valign="middle"><para>Unknown</para></entry>
<entry><para>Invalid command line arguments were supplied to the
plugin or the plugin was unable to check the status of the given
hosts/service</para></entry>
</section>
+ <section id="thresholdformat"><title>Threshold range format</title>
+ <para>Thresholds ranges define the warning and critical levels for plugins to
+ alert on. The theory is that the plugin will do some sort of check which returns
+ back a numerical value, or metric, which is then compared to the warning and
+ critical thresholds.
+ This is the generalised format for threshold ranges:</para>
+
+ <literallayout>
+ [@]start:end
+ </literallayout>
+
+ <para>Notes:</para>
+ <orderedlist>
+ <listitem><para>start > end</para>
+ </listitem>
+ <listitem><para>start and ":" is not required if start=0</para>
+ </listitem>
+ <listitem><para>if range is of format "start:" and end is not specified,
+ assume end is infinity</para>
+ </listitem>
+ <listitem><para>to specify negative infinity, use "~"</para>
+ </listitem>
+ <listitem><para>alert is raised if metric is outside start and end range
+ (inclusive of endpoints)</para>
+ </listitem>
+ <listitem><para>if range starts with "@", then alert if inside this range
+ (inclusive of endpoints)</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Note: Not all plugins are coded to expect ranges in this format. It is
+ planned for a future release to
+ provide standard libraries to parse and compare metrics against ranges. There
+ will also be some work in providing multiple metrics.</para>
+ </section>
+
<section><title>Performance data</title>
<para>Performance data is defined by Nagios as "everything after the | of the plugin output" -
please refer to Nagios documentation for information on capturing this data to logfiles.
This is the expected format:</para>
<literallayout>
- 'label'=value[UOM];[crit];[warn][;[max];[min]]
+ 'label'=value[UOM];[warn];[crit];[min];[max]
</literallayout>
<para>Notes:</para>
</listitem>
<listitem><para>to specify a quote character, use two single quotes</para>
</listitem>
- <listitem><para>crit or warn may be null (if the threshold is not defined)</para>
+ <listitem><para>warn, crit, min or max may be null (for example, if the threshold is
+ not defined or min and max do not apply). Trailing unfilled semicolons can be
+ dropped</para>
</listitem>
- <listitem><para>max and min are optional. Holds maximum values for the
- particular UOM (not required if UOM=%)</para>
+ <listitem><para>min and max are not required if UOM=%</para>
</listitem>
- <listitem><para>value, crit, warn, max and min in class [-0-9.]. Must all be the
+ <listitem><para>value, min and max in class [-0-9.]. Must all be the
same UOM</para>
</listitem>
+ <listitem><para>warn and crit are in the range format (see
+ <xref linkend="thresholdformat">). Must be the same UOM</para>
+ </listitem>
<listitem><para>UOM (unit of measurement) is one of:</para>
<orderedlist>
<listitem><para>no unit specified - assume a number (int or float)
<para>It is up to third party programs to convert the Nagios plugins
performance data into graphs.</para>
</section>
+
+ <section><title>Translations</title>
+ <para>If possible, use translation tools for all output. Currently, most of the core C plugins
+ use gettext for translation. General guidelines are:</para>
+
+ <orderedlist>
+ <listitem><para>short help is not translated</para></listitem>
+ <listitem><para>long help has options in English language, but text translated</para></listitem>
+ <listitem><para>"Copyright" kept in English</para></listitem>
+ <listitem><para>copyright holder names kept in original text</para></listitem>
+ </orderedlist>
+ </section>
</section>
<section id="SysCmdAuxFiles"><title>System Commands and Auxiliary Files</title>
<orderedlist>
<listitem><para> Do not use BEGIN and END blocks since they will be called
- the first time and when Nagios shuts down with Embedded Perl (ePN). In
+ only once (when Nagios starts and shuts down) with Embedded Perl (ePN). In
particular, do not use BEGIN blocks to initialize variables.</para>
</listitem>
<listitem><para>To use utils.pm, you need to provide a full path to the
- module in order for it to work with ePN.</para>
+ module in order for it to work.</para>
<literallayout>
e.g.
variable. </para>
- <para>Explicitly initialize each varialable in use. Otherwise with
- caching enabled, the plugin will not be recompilied each time, and
+ <para>Explicitly initialize each variable in use. Otherwise with
+ caching enabled, the plugin will not be recompiled each time, and
therefore Perl will not reinitialize all the variables. All old
variable values will still be in effect.</para>
</listitem>
- <listitem><para>Do not use < DATA > (these simply do not compile under ePN).</para>
+ <listitem><para>Do not use >DATA< handles (these simply do not compile under ePN).</para>
</listitem>
- <listitem><para>Do not use named subroutines</para>
+ <listitem><para>Do not use global variables in named subroutines. This is bad practise anyway, but with ePN the
+ compiler will report an error "<global_var> will not stay shared ..". Values used by
+ subroutines should be passed in the argument list.</para>
</listitem>
<listitem><para>If writing to a file (perhaps recording
performance data) explicitly close close it. The plugin never
- calls <emphasis role=strong>exit</emphasis>; that is caught by
+ calls <emphasis role="strong">exit</emphasis>; that is caught by
p1.pl, so output streams are never closed.</para>
</listitem>
<listitem><para>As in <xref linkend="runtime"> all plugins need
to monitor their runtime, specially if they are using network
- resources. Use of the <emphasis>alarm</emphasis> is recommended.
+ resources. Use of the <emphasis>alarm</emphasis> is recommended
+ noting that some Perl modules (eg LWP) manage timers, so that an alarm
+ set by a plugin using such a module is overwritten by the module.
+ (workarounds are cunning (TM) or using the module timer)
Plugins may import a default time out ($TIMEOUT) from utils.pm.
</para>
</listitem>
<para>The option -v or --verbose should be present in all plugins.
The user should be allowed to specify -v multiple times to increase
- the verbosity level, as described in <xref linkend="verbose_levels">.</para>
+ the verbosity level, as described in <xref linkend="verboselevels">.</para>
</section>
<section>
<section><title>Comments</title>
<para>You should use /* */ for comments and not // as some compilers
do not handle the latter form.</para>
+ <para>There should not be any named credits in the source code - contributors
+ should be added
+ into the AUTHORS file instead. The only exception to this is if a routine
+ has been copied from another source.</para>
</section>
<section><title>CVS comments</title>
</varlistentry>
</variablelist>
</para>
+ <para>If the change is due to a contribution, please quote the contributor's name
+ and, if applicable, add the SourceForge Tracker number. Don't forget to
+update the AUTHORS file.</para>
</section>
</section>
<ulink url="http://sourceforge.net/tracker/?group_id=29880&atid=397599">SourceForge's
tracker system for Nagiosplug patches</ulink>
and be announced to the nagiosplug-devel mailing list.</para>
+
+ <para>Submission of a patch implies that the submmitter acknowledges that they
+ are the author of the code (or have permission from the author to release the code)
+ and agree that the code can be released under the GPL. The copyright for the changes will
+ then revert to the Nagios Plugin Development Team - this is required so that any copyright
+ infringements can be investigated quickly without contacting a huge list of copyright holders.
+ Credit will always be given for any patches through a THANKS file in the distribution.</para>
</section>
- <section id="New_plugins"><title>New plugins</title>
+ <section id="Newplugins"><title>New plugins</title>
<para>If you would like others to use your plugins and have it included in
the standard distribution, please include patches for the relevant
configuration files, in particular "configure.in". Otherwise submitted
</section>
+<section id="UsingSourceforge"><title>Using Sourceforge</title>
+<table id="Projectmemberaccess"><title>Project Member Access</title>
+ <tgroup cols="9">
+ <thead>
+ <row>
+ <entry><para>Member type</para></entry>
+ <entry><para>CVS Access</para></entry>
+ <entry><para>Shell Access</para></entry>
+ <entry><para>Release Tech</para></entry>
+ <entry><para>Tracker Manager</para></entry>
+ <entry><para>Task Manager</para></entry>
+ <entry><para>Forums</para></entry>
+ <entry><para>Doc Manager</para></entry>
+ <entry><para>News</para></entry>
+ <entry><para>Screenshots</para></entry>
+ <entry><para>Notes</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Translator</para></entry>
+ <entry><para>Yes</para></entry>
+ <entry><para>Yes</para></entry>
+ <entry><para>No</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>Add developer to CVSROOT/avail for translation files</para></entry>
+ </row>
+ <row>
+ <entry><para>Developer</para></entry>
+ <entry><para>Yes</para></entry>
+ <entry><para>Yes</para></entry>
+ <entry><para>No</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>A&T</para></entry>
+ <entry><para>Moderator</para></entry>
+ <entry><para>Editor</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>-</para></entry>
+ <entry><para>Need to set tracker access individually. Add developer to CVSROOT/avail for all files</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+<para>Add all members to the nagiosplug-team mailing list</para>
+</section>
</article>
</book>