X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Fdeveloper-guidelines.sgml;h=ed7e422692f7c821063be0e372c3ef42b8583db7;hb=12c17fe8a25ada493a87ed3d5a5885e3414052ac;hp=82dbecaaad44cede9aee25b6769d42ff7e205b90;hpb=e0688a69114c95efaa0fbee8f8e91f6dcc21a1ee;p=nagiosplug.git
diff --git a/doc/developer-guidelines.sgml b/doc/developer-guidelines.sgml
index 82dbeca..ed7e422 100644
--- a/doc/developer-guidelines.sgml
+++ b/doc/developer-guidelines.sgml
@@ -11,18 +11,18 @@
- 2005
+ 2006
Nagios plug-in development guidelines
- $Revision$
- $Date$
+ 1796
+ 2007-09-24 14:51:07 -0400 (Mon, 24 Sep 2007)
- 2000 - 2005
+ 2000 - 2006
Nagios Plugins Development Team
@@ -34,7 +34,7 @@
the plug-in developers and encourage the standarization of the
different kind of plug-ins: C, shell, perl, python, etc.
- Nagios Plug-in Development Guidelines Copyright (C) 2000-2005
+ Nagios Plug-in Development Guidelines Copyright (C) 2000-2006
(Nagios Plugins Team)
Permission is granted to make and distribute verbatim
@@ -55,9 +55,10 @@
gnu make 3.79
- automake 1.8
- autoconf 2.58
- gettext 0.11.5
+ automake 1.9.2
+ autoconf 2.59
+ gnu m4 1.4.2
+ gnu libtool 1.5
To compile from CVS, after you have checked out the code, run:
@@ -68,6 +69,14 @@
make install
+
+ 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.
+
+ 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.
+
Plugin Output for Nagios
@@ -78,11 +87,14 @@
the entire output to appear in a pager message, which will get chopped
off after a certain length.
+ As Nagios does not capture stderr output, you should only output to
+ STDOUT and not print to STDERR.
+
Print only one line of text
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.
+ 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.
Output should be in the format:
@@ -130,8 +142,9 @@
Screen Output
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.
+
Code and output should try to respect the 80x25 size of a
crt (remember when fixing stuff in the server room!)
@@ -234,6 +247,83 @@
Note: Not all plugins are coded to expect ranges in this format yet.
There will be some work in providing multiple metrics.
+
+ Example ranges
+
+
+
+ Range definition
+ Generate an alert if x...
+
+
+
+
+ 10
+ < 0 or > 10, (outside the range of {0 .. 10})
+
+
+ 10:
+ < 10, (outside {10 .. ∞})
+
+
+ ~:10
+ > 10, (outside the range of {-∞ .. 10})
+
+
+ 10:20
+ < 10 or > 20, (outside the range of {10 .. 20})
+
+
+ @10:20
+ ≥ 10 and ≤ 20, (inside the range of {10 .. 20})
+
+
+ 10
+ < 0 or > 10, (outside the range of {0 .. 10})
+
+
+
+
+ Command line examples
+
+
+
+ Command line
+ Meaning
+
+
+
+
+ check_stuff -w10 -c20
+ Critical if "stuff" is over 20, else warn if over 10 (will be critical if "stuff" is less than 0)
+
+
+ check_stuff -w~:10 -c~:20
+ Same as above. Negative "stuff" is OK
+
+
+ check_stuff -w10: -c20
+ Critical if "stuff" is over 20, else warn if "stuff" is below 10 (will be critical if "stuff" is less than 0)
+
+
+ check_stuff -c1:
+ Critical if "stuff" is less than 1
+
+
+ check_stuff -w~:0 -c10
+ Critical if "stuff" is above 10; Warn if "stuff" is above zero
+
+
+ check_stuff -c5:6
+ The only noncritical range is 5:6
+
+
+ check_stuff -c10:20
+ Critical if "stuff" is 10 to 20
+
+
+
+
Performance data
@@ -294,7 +384,7 @@
Translations
If possible, use translation tools for all output to respect the user's language
- settings. See for guidelines
+ settings. See for guidelines
for the core plugins.
@@ -588,7 +678,7 @@ all the current tests and report an overall success rate.
-See the Nagios Plugins Tinderbox server
+See the Nagios Plugins Tinderbox server
for the daily test results.
@@ -616,23 +706,21 @@ link
Testing the C library functions
-Uses the libtap library, which gives
+We use the libtap library, which gives
perl's TAP
(Test Anything Protocol) output. This is used by the FreeBSD team for their regression testing.
-To run tests using the libtap library, download from http://people.freebsd.org/~nik/public_distfiles/
-and compile. There is a problem with tap-1.01
-where pthread support doesn't appear to work
-properly on non-FreeBSD systems. Compile with 'CPPFLAGS="-UHAVE_LIBPTHREAD" ./configure'. You do not need
-to install.
+To run tests using the libtap library, download the latest tar ball and extract.
+There is a problem with tap-1.01 where
+pthread support doesn't appear to work
+properly on non-FreeBSD systems. Install with 'CPPFLAGS="-UHAVE_LIBPTHREAD" ./configure && make && make check && make install'.
-You then have to run the Nagios Plugins' configure with the --with-libtap-object=full_path to the compiled
-tap.o file.
-Then run "make" and "make test" to run all tests.
+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.
@@ -640,9 +728,20 @@ Then run "make" and "make test" to run all tests.
Coding guidelines
See GNU
Coding standards for general guidelines.
- Comments
+ C coding
+
+ Variables should be declared at the beginning of code blocks and
+ not inline because of portability with older compilers.
+
You should use /* */ for comments and not // as some compilers
do not handle the latter form.
+
+ 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.
+
+
+ Crediting sources
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.
@@ -652,26 +751,16 @@ Then run "make" and "make test" to run all tests.
CVS comments
- When adding CVS comments at commit time, you can use the following prefixes:
-
- - comment
-
- for a comment that can be removed from the Changelog
-
-
- * comment
-
- for an important amendment to be included into a features list
-
-
-
-
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.
+ If you have a change that is useful for noting in the next release, please
+ update the NEWS file.
+ All CVS commit comments will be written to a ChangeLog at release time.
+
- Translations for developers
+ Translations for developers
To make the job easier for translators, please follow these guidelines:
@@ -718,8 +807,22 @@ update the THANKS.in file.
Credit will always be given for any patches through a THANKS file in the distribution.
- New plugins
+ Contributed plugins
+ 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 NagiosExchange.
+
+ 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.
+
+ The aim is to distribute only code that the Nagios Plugin team are responsible for.
+
+
+
+ New plugins
If you would like others to use your plugins, please add it to
the official 3rd party plugin repository,
NagiosExchange.
@@ -732,7 +835,8 @@ update the THANKS.in file.
- Include copyright and license information in all files
+ Include copyright and license information in all files. Copyright must be solely
+ granted to the Nagios Plugin Development Team
The standard command options are supported (--help, --version,