![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 1861e956d329523d174fd851565ea91542d3c641..1ce78ff401b67e81bd018d62c7db044c553a9474 100644 (file)
</author>
</authorgroup>
- <pubdate>2006</pubdate>
+ <pubdate>2009</pubdate>
<title>Nagios plug-in development guidelines</title>
<revhistory>
<revision>
- <revnumber>$Revision$</revnumber>
- <date>$Date$</date>
+ <revnumber>1796</revnumber>
+ <date>2007-09-24 14:51:07 -0400 (Mon, 24 Sep 2007)</date>
</revision>
</revhistory>
<copyright>
- <year>2000 - 2006</year>
+ <year>2000 - 2009</year>
<holder>Nagios Plugins Development Team</holder>
</copyright>
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-2006
+ <para>Nagios Plug-in Development Guidelines Copyright (C) 2000-2009
(Nagios Plugins Team)</para>
<para>Permission is granted to make and distribute verbatim
<para>
Nagios plugins are developed to the GNU standard, so any OS which is supported by GNU
should run the plugins. While the requirements for compiling the Nagios plugins release
- is very small, to develop from CVS needs additional software to be installed. These are the
- minimum levels of software required:
+ are very basic, developing from the Git repository requires additional software to be
+ installed. These are the minimum levels of software required:
<literallayout>
- gnu make 3.79
- automake 1.8.3
- autoconf 2.58
- gnu libtool 1.5.6
+ GNU make 3.79
+ GNU automake 1.9.2
+ GNU autoconf 2.59
+ GNU m4 1.4.2
+ GNU libtool 1.5
</literallayout>
- To compile from CVS, after you have checked out the code, run:
+ To compile from Git, after you have cloned the repository, run:
<literallayout>
tools/setup
./configure
make install
</literallayout>
</para>
-
- <para>Note: gettext is no longer a developer platform requirement. A lot of the files in lib/ and m4/
- are synced with the coreutils project and we use the same levels of gettext that they
- distribute.
- </para>
</section>
<section id="PlugOutput"><title>Plugin Output for Nagios</title>
the entire output to appear in a pager message, which will get chopped
off after a certain length.</para>
+ <para>As Nagios does not capture stderr output, you should only output to
+ STDOUT and not print to STDERR.</para>
+
<section><title>Print only one line of text</title>
<para>Nagios will only grab the first line of text from STDOUT
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>
+ multiple lines, you're out of luck (though this will be a feature of
+ Nagios 3). Remember, keep your output short and to the point.</para>
<para>Output should be in the format:</para>
<literallayout>
<section><title>Screen Output</title>
<para>The plug-in should print the diagnostic and just the
- synopsis part of the help message. A well written plugin would
+ usage part of the help message. A well written plugin would
then have --help as a way to get the verbose help.</para>
+
<para>Code and output should try to respect the 80x25 size of a
crt (remember when fixing stuff in the server room!)</para>
</section>
<para>Note: Not all plugins are coded to expect ranges in this format yet.
There will be some work in providing multiple metrics.</para>
+
+ <table id="ExampleRanges"><title>Example ranges</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry><para>Range definition</para></entry>
+ <entry><para>Generate an alert if x...</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>10</entry>
+ <entry>< 0 or > 10, (outside the range of {0 .. 10})</entry>
+ </row>
+ <row>
+ <entry>10:</entry>
+ <entry>< 10, (outside {10 .. ∞})</entry>
+ </row>
+ <row>
+ <entry>~:10</entry>
+ <entry>> 10, (outside the range of {-∞ .. 10})</entry>
+ </row>
+ <row>
+ <entry>10:20</entry>
+ <entry>< 10 or > 20, (outside the range of {10 .. 20})</entry>
+ </row>
+ <row>
+ <entry>@10:20</entry>
+ <entry>≥ 10 and ≤ 20, (inside the range of {10 .. 20})</entry>
+ </row>
+ <row>
+ <entry>10</entry>
+ <entry>< 0 or > 10, (outside the range of {0 .. 10})</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table id="CommandLineExamples"><title>Command line examples</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry><para>Command line</para></entry>
+ <entry><para>Meaning</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>check_stuff -w10 -c20</entry>
+ <entry>Critical if "stuff" is over 20, else warn if over 10 (will be critical if "stuff" is less than 0)</entry>
+ </row>
+ <row>
+ <entry>check_stuff -w~:10 -c~:20</entry>
+ <entry>Same as above. Negative "stuff" is OK</entry>
+ </row>
+ <row>
+ <entry>check_stuff -w10: -c20</entry>
+ <entry>Critical if "stuff" is over 20, else warn if "stuff" is below 10 (will be critical if "stuff" is less than 0)</entry>
+ </row>
+ <row>
+ <entry>check_stuff -c1:</entry>
+ <entry>Critical if "stuff" is less than 1</entry>
+ </row>
+ <row>
+ <entry>check_stuff -w~:0 -c10</entry>
+ <entry>Critical if "stuff" is above 10; Warn if "stuff" is above zero</entry>
+ </row>
+ <row>
+ <entry>check_stuff -c5:6</entry>
+ <entry>The only noncritical range is 5:6</entry>
+ </row>
+ <row>
+ <entry>check_stuff -c10:20</entry>
+ <entry>Critical if "stuff" is less than 10 or over 20</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</section>
<section><title>Performance data</title>
<orderedlist>
<listitem><para>space separated list of label/value pairs</para>
</listitem>
- <listitem><para>label can contain any characters</para>
+ <listitem><para>label can contain any characters except the equals sign or single quote (')</para>
</listitem>
<listitem><para>the single quotes for the label are optional. Required if
- spaces, = or ' are in the label</para>
+ spaces are in the label</para>
</listitem>
<listitem><para>label length is arbitrary, but ideally the first 19 characters
are unique (due to a limitation in RRD). Be aware of a limitation in the
</para>
<para>
-See the <ulink url="http://tinderbox.altinity.org">Nagios Plugins Tinderbox server</ulink>
+See the <ulink url="http://tinderbox.opsera.com">Nagios Plugins Tinderbox server</ulink>
for the daily test results.
</para>
<section id="CodingGuidelines"><title>Coding guidelines</title>
<para>See <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU
Coding standards</ulink> for general guidelines.</para>
- <section><title>Comments</title>
+ <section><title>C coding</title>
+
+ <para>Variables should be declared at the beginning of code blocks and
+ not inline because of portability with older compilers.</para>
+
<para>You should use /* */ for comments and not // as some compilers
do not handle the latter form.</para>
+
+ <para>You should also avoid using the type "bool" and its values
+ "true" and "false". Instead use the "int" type and the plugins' own
+ "TRUE"/"FALSE" values to keep the code uniformly.</para>
+ </section>
+
+ <section><title>Crediting sources</title>
<para>If you have copied a routine from another source, make sure the licence
from your source allows this. Add a comment referencing the ACKNOWLEDGEMENTS
file, where you can put more detail about the source.</para>
</para>
</section>
- <section><title>CVS comments</title>
- <para>When adding CVS comments at commit time, you can use the following prefixes:
- <variablelist>
- <varlistentry><term>- comment</term>
- <listitem>
- <para>for a comment that can be removed from the Changelog</para>
- </listitem>
- </varlistentry>
- <varlistentry><term>* comment</term>
- <listitem>
- <para>for an important amendment to be included into a features list</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <section><title>Commit Messages</title>
<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 THANKS.in file.</para>
+ <para>If you have a change that is useful for noting in the next release, please
+ update the NEWS file.</para>
+ <para>All commits will be written to a ChangeLog at release time.
+ </para>
</section>
<section id="translationsdevelopers"><title>Translations for developers</title>
<section id="Patches"><title>Patches</title>
<para>If you have a bug patch, please supply a unified or context diff against the
version you are using. For new features, please supply a diff against
- the CVS HEAD version.</para>
+ the Git "master" branch.</para>
<para>Patches should be submitted via
<ulink url="http://sourceforge.net/tracker/?group_id=29880&atid=397599">SourceForge's
Credit will always be given for any patches through a THANKS file in the distribution.</para>
</section>
- <section id="Newplugins"><title>New plugins</title>
+ <section id="Contributedplugins"><title>Contributed plugins</title>
+ <para>Plugins that have been contributed to the project and
+ distributed with the Nagios Plugin files are held in the contrib/ directory and are not installed
+ by default. These plugins are not officially supported by the team.
+ The current policy is that these plugins should be owned and maintained by the original
+ contributor, preferably hosted on <ulink url="http://exchange.nagios.org">Nagios Exchange</ulink>.
+ </para>
+ <para>If patches or bugs are raised to an contributed plugin, we will start communications with the
+ original contributor, but seek to remove the plugin from our distribution.
+ </para>
+ <para>The aim is to distribute only code that the Nagios Plugin team are responsible for.
+ </para>
+ </section>
+
+ <section id="Newplugins"><title>New plugins</title>
<para>If you would like others to use your plugins, please add it to
the official 3rd party plugin repository,
- <ulink url="http://www.nagiosexchange.org">NagiosExchange</ulink>.
+ <ulink url="http://exchange.nagios.org">Nagios Exchange</ulink>.
</para>
<para>We are not accepting requests for inclusion of plugins into
<orderedlist>
<listitem>
- <para>Include copyright and license information in all files</para>
+ <para>Include copyright and license information in all files. Copyright must be solely
+ granted to the Nagios Plugin Development Team</para>
</listitem>
<listitem>
<para>The standard command options are supported (--help, --version,