X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Fdeveloper-guidelines.sgml;h=86e694046704ef5353fe46bc7b207027a8e837b6;hb=181107290e5265b5b50f7131dbccaee38dc32db8;hp=6e72192661b5a1184cf0bd6a790f250f62848bfb;hpb=7433e4b73fb48d2486a48b38da50453adc367085;p=nagiosplug.git
diff --git a/doc/developer-guidelines.sgml b/doc/developer-guidelines.sgml
index 6e72192..86e6940 100644
--- a/doc/developer-guidelines.sgml
+++ b/doc/developer-guidelines.sgml
@@ -5,66 +5,25 @@
- Karl
- DeBisschop
-
- karl@debisschop.net
-
+
+ Nagios Plugins Development Team
+
-
-
- Ethan
- Galstad
-
- Author of Nagios
-
-
-
- netsaint@linuxbox.com
-
-
-
-
- Hugo
- Gayosso
-
- hgayosso@gnu.org
-
-
-
-
-
- Subhendu
- Ghosh
-
- sghosh@sourceforge.net
-
-
-
-
- Stanley
- Hopcroft
-
- stanleyhopcroft@sourceforge.net
-
-
-
- 2002
+ 2009
Nagios plug-in development guidelines
- 0.4
- 2 May 2002
+ 1796
+ 2007-09-24 14:51:07 -0400 (Mon, 24 Sep 2007)
- 2000 2001 2002
- Karl DeBisschop, Ethan Galstad,
- Hugo Gayosso, Stanley Hopcroft, Subhendu Ghosh
+ 2000 - 2009
+ Nagios Plugins Development Team
@@ -75,8 +34,8 @@
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-2003
- (Karl DeBisschop, Ethan Galstad, Stanley Hopcroft, Subhendu Ghosh, Ton Voon, Jeremy T. Bouse)
+ Nagios Plug-in Development Guidelines Copyright (C) 2000-2009
+ (Nagios Plugins Team)
Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and this
@@ -91,17 +50,18 @@
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:
- gnu make 3.79
- automake 1.6
- autoconf 2.54
- gettext 0.11.5
+ GNU make 3.79
+ GNU automake 1.9.2
+ GNU autoconf 2.59
+ GNU m4 1.4.2
+ GNU libtool 1.5
- To compile from CVS, after you have checked out the code, run:
+ To compile from Git, after you have cloned the repository, run:
tools/setup
./configure
@@ -119,15 +79,18 @@
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:
- METRIC STATUS: Information text
+ SERVICE STATUS: Information text
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
@@ -139,7 +102,7 @@
-v options for additional verbosity, up to a maximum of 3. The standard
type of output should be:
-
Verbose output levels
+ Verbose output levels
@@ -171,20 +134,13 @@
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!)
- Return the proper status code
- See below
- for the numeric values of status codes and their
- description. Remember to return an UNKNOWN state if bogus or
- invalid command line arguments are supplied or it you are unable
- to check the service.
-
-
Plugin Return Codes
The return codes below are based on the POSIX spec of returning
a positive value. Netsaint prior to v0.0.7 supported non-POSIX
@@ -231,8 +187,12 @@
3
Unknown
Invalid command line arguments were supplied to the
- plugin or the plugin was unable to check the status of the given
- hosts/service
+ plugin or low-level failures internal to the plugin (such as unable to fork,
+ or open a tcp socket) that prevent it from performing the specified
+ operation. Higher-level errors (such as name resolution errors,
+ socket timeouts, etc) are outside of the control of plugins and should
+ generally NOT be reported as UNKNOWN states.
+
@@ -241,12 +201,18 @@
-
Performance data
@@ -292,10 +333,10 @@
space separated list of label/value pairs
- label can contain any characters
+ label can contain any characters except the equals sign or single quote (')
the single quotes for the label are optional. Required if
- spaces, = or ' are in the label
+ spaces are in the label
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
@@ -313,7 +354,7 @@
same UOM
warn and crit are in the range format (see
- )
+ ). Must be the same UOM
UOM (unit of measurement) is one of:
@@ -332,6 +373,13 @@
It is up to third party programs to convert the Nagios plugins
performance data into graphs.
+
+ Translations
+ If possible, use translation tools for all output to respect the user's language
+ settings. See for guidelines
+ for the core plugins.
+
+
System Commands and Auxiliary Files
@@ -393,12 +441,12 @@
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.
To use utils.pm, you need to provide a full path to the
- module in order for it to work with ePN.
+ module in order for it to work.
e.g.
@@ -415,16 +463,18 @@
variable.
- Explicitly initialize each varialable in use. Otherwise with
- caching enabled, the plugin will not be recompilied each time, and
+ 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.
- Do not use > DATA < (these simply do not compile under ePN).
+ Do not use >DATA< handles (these simply do not compile under ePN).
- Do not use named subroutines
+ 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.
If writing to a file (perhaps recording
@@ -435,7 +485,10 @@
As in all plugins need
to monitor their runtime, specially if they are using network
- resources. Use of the alarm is recommended.
+ resources. Use of the alarm 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.
@@ -547,7 +600,7 @@
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 .
+ the verbosity level, as described in .
+Test cases
+
+Tests are the best way of knowing if the plugins work as expected. Please
+create and update test cases where possible.
+
+
+
+To run a test, from the top level directory, run "make test". This will run
+all the current tests and report an overall success rate.
+
+
+
+See the Nagios Plugins Tinderbox server
+for the daily test results.
+
+
+Test cases for plugins
+These use perl's Test::More. To do a one time test, run "cd plugins && perl t/check_disk.t".
+
+
+There will somtimes be failures seen in this output which are known failures that
+need to be fixed. As long as the return code is 0, it will be reported as "test pass".
+(If you have a fix so that the specific test passes, that will be gratefully received!)
+
+
+
+If you want a summary test, run: "cd plugins && prove t/check_disk.t".
+This runs the test in a summary format.
+
+
+
+For a good and amusing tutorial on using Test::More, see this
+
+link
+
+
+
+
+Testing the C library functions
+
+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 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'.
+
+
+
+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.
+
+
+
+
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.
- 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.
+
+ 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.
- 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
-
-
-
+ 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.
+ For contributed code, do not add any named credits in the source code
+ - contributors should be added into the THANKS.in file instead.
+
+
+ Commit Messages
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.
+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 commits will be written to a ChangeLog at release time.
+
+
+ Translations for developers
+ To make the job easier for translators, please follow these guidelines:
+
+
+ Before creating new strings, check the po/nagios-plugins.pot file to
+ see if a similar string
+ already exists
+
+
+ For help texts, break into individual options so that these can be reused
+ between plugins
+
+ Try to avoid linefeeds unless you are working on a block of text
+ Short help is not translated
+ Long help has options in English language, but text translated
+ "Copyright" kept in English
+ Copyright holder names kept in original text
+ Debugging output does not need to be translated
+
+
+
+ Translations for translators
+ To create an up to date list of translatable strings, run: tools/gen_locale.sh
+
+
Submission of new plugins and patches
@@ -643,7 +784,7 @@ update the AUTHORS file.
Patches
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.
+ the Git "master" branch.
Patches should be submitted via
SourceForge's
@@ -658,17 +799,37 @@ update the AUTHORS file.
Credit will always be given for any patches through a THANKS file in the distribution.
- New plugins
- 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
- plugins will be included in the contrib directory.
-
- Plugins in the contrib directory are going to be migrated to the
- standard plugins/plugin-scripts directory as time permits and per user
- requests. The minimum requirements are:
+
+ 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 Nagios Exchange.
+
+ 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,
+ Nagios Exchange.
+
+
+ We are not accepting requests for inclusion of plugins into
+ our distribution at the moment, but when we do, these are the minimum
+ requirements:
+
+
+ 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,
--timeout, --warning, --critical)
@@ -685,25 +846,21 @@ update the AUTHORS file.
It should also follow code format guidelines, and use functions from
-utils (perl or c or sh) rather than cooking it's own
+utils (perl or c or sh) rather than using its own
+
+
+ Includes patches to configure.in if required (via the EXTRAS list if
+ it will only work on some platforms)
+
+
+ If possible, please submit a test harness. Documentation on sample
+ tests coming soon
- New plugins should be submitted via
- SourceForge's
- tracker system for Nagiosplug new plugins
- and be announced to the nagiosplug-devel mailing list.
-
- For new plugins, provide a diff to add to the EXTRAS list (configure.in)
- unless you are fairly sure that the plugin will work for all platforms with
- no non-standard software added.
-
- If possible please submit a test harness. Documentation on sample
- tests coming soon.
-