X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Fdeveloper-guidelines.sgml;h=1ce78ff401b67e81bd018d62c7db044c553a9474;hb=b8dacf1c94ac1eae754ac165f451acdee1814765;hp=f5e376a11673a8b7c7aaa63f3211664a7acaa19f;hpb=0205583b4676e5ac0c27c689b6bdb232ce61c617;p=nagiosplug.git diff --git a/doc/developer-guidelines.sgml b/doc/developer-guidelines.sgml index f5e376a..1ce78ff 100644 --- a/doc/developer-guidelines.sgml +++ b/doc/developer-guidelines.sgml @@ -1,70 +1,29 @@ - + Nagios Plug-in Developer Guidelines - 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,10 +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 2001 - 2002 - Karl DeBisschop, Ethan Galstad, Hugo Gayosso, Stanley Hopcroft, - Subhendu Ghosh + 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 @@ -93,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 @@ -116,16 +74,27 @@
Plugin Output for Nagios 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. + 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: + + 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 + be determined by the return code.
Verbose output @@ -133,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 @@ -143,19 +112,19 @@ - 0 + 0 Single line, minimal output. Summary - 1 + 1 Single line, additional information (eg list processes that fail) - 2 + 2 Multi line, configuration debug output (eg ps command used) - 3 + 3 Lots of detail for plugin problem diagnosis @@ -165,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 @@ -203,30 +165,34 @@
- 0 - OK + 0 + OK The plugin was able to check the service and it appeared to be functioning properly - 1 - Warning + 1 + Warning 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 - 2 - Critical + 2 + Critical The plugin detected that either the service was not running or it was above some "critical" threshold - 3 - Unknown + 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. + @@ -235,12 +201,18 @@ -
Threshold range format - 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 +
Threshold and ranges + A range is defined as a start and end point (inclusive) on a numeric scale (possibly + negative or positive infinity). + + 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. + + 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: + critical thresholds. Use the get_status(double, thresholds *) function to + compare the value against the thresholds. + This is the generalised format for ranges: [@]start:end @@ -248,7 +220,7 @@ Notes: - start < end + start ≤ end start and ":" is not required if start=0 @@ -265,10 +237,85 @@ - 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. + 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 less than 10 or over 20 + + + +
Performance data @@ -286,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 @@ -307,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: @@ -326,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 @@ -387,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. @@ -409,27 +463,32 @@ 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 performance data) explicitly close close it. The plugin never - calls exit; that is caught by + calls exit; that is caught by p1.pl, so output streams are never closed. 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. @@ -541,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 .
@@ -599,37 +658,125 @@
+
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 @@ -637,25 +784,52 @@ 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 tracker system for Nagiosplug patches and be announced to the nagiosplug-devel mailing list. + + 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.
-
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) @@ -672,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.
-