index 3c37e5c104a858c9faeed19794f18fb776410813..15920afe07c38794e25dabce12ef68e58a6f7887 100644 (file)
</author>
</authorgroup>
- <pubdate>2005</pubdate>
+ <pubdate>2006</pubdate>
<title>Nagios plug-in development guidelines</title>
<revhistory>
</revhistory>
<copyright>
- <year>2000 - 2005</year>
+ <year>2000 - 2006</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-2005
+ <para>Nagios Plug-in Development Guidelines Copyright (C) 2000-2006
(Nagios Plugins Team)</para>
<para>Permission is granted to make and distribute verbatim
<literallayout>
gnu make 3.79
- automake 1.8
+ automake 1.9.2
autoconf 2.58
- gettext 0.11.5
+ gnu m4 1.4.2
+ gnu libtool 1.5
</literallayout>
To compile from CVS, after you have checked out the code, run:
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>
+ <para>Note: gnu libtool, which must be at version 1.5.22 or above, has files installed into CVS, so is not
+ a development platform requirement.
+ </para>
</section>
<section id="PlugOutput"><title>Plugin Output for Nagios</title>
</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
+ <section id="thresholdformat"><title>Threshold and ranges</title>
+ <para>A range is defined as a start and end point (inclusive) on a numeric scale (possibly
+ negative or positive infinity).
+ </para>
+ <para>A threshold is a range with an alert level (either warning or critical). Use the
+ set_thresholds(thresholds *, char *, char *) function to set the thresholds.
+ </para>
+ <para>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>
+ critical thresholds. Use the get_status(double, thresholds *) function to
+ compare the value against the thresholds.</para>
+ <para>This is the generalised format for ranges:</para>
<literallayout>
[@]start:end
<para>Notes:</para>
<orderedlist>
- <listitem><para>start > end</para>
+ <listitem><para>start ≤ end</para>
</listitem>
<listitem><para>start and ":" is not required if start=0</para>
</listitem>
</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>
+ <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 10 to 20</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</section>
<section><title>Performance data</title>
<section><title>Translations</title>
<para>If possible, use translation tools for all output to respect the user's language
- settings. See <xref linkend="translations_developers"> for guidelines
+ settings. See <xref linkend="translationsdevelopers"> for guidelines
for the core plugins.
</para>
</section>
</para>
<para>
-If you want a summary test, run: "cd plugins && perl -MTest::Harness -e 'runtests(@ARGV)' t/check_disk.t".
+If you want a summary test, run: "cd plugins && prove t/check_disk.t".
This runs the test in a summary format.
</para>
<section><title>Testing the C library functions</title>
<para>
-Will be looking at using libtap, which is utilised by the FreeBSD team. The output is
-based on perl's TAP (Test Anything Protocol) format, so that Test::Harness will understand
-results. This is still in planning stages.
+We use <ulink url="http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap">the libtap library</ulink>, which gives
+perl's TAP
+(Test Anything Protocol) output. This is used by the FreeBSD team for their regression testing.
+</para>
+
+<para>
+To run tests using the libtap library, download the latest tar ball and extract.
+There is a problem with tap-1.01 where
+<ulink url="http://jc.ngo.org.uk/trac-bin/trac.cgi/ticket/25">pthread support doesn't appear to work</ulink>
+properly on non-FreeBSD systems. Install with 'CPPFLAGS="-UHAVE_LIBPTHREAD" ./configure && make && make check && make install'.
+</para>
+
+<para>
+When you run Nagios Plugins' configure, it will look for the tap library and will automatically
+setup the tests. Run "make test" to run all the tests.
</para>
</section>
<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>
+ </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>
update the THANKS.in file.</para>
</section>
- <section id="translations_developers"><title>Translations for developers</title>
+ <section id="translationsdevelopers"><title>Translations for developers</title>
<para>To make the job easier for translators, please follow these guidelines:</para>
<orderedlist>
<listitem><para>
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://www.nagiosexchange.org">NagiosExchange</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>.
<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,