|
|
@@ -1,931 +0,0 @@
|
|
|
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
|
|
|
-<HTML
|
|
|
-><HEAD
|
|
|
-><TITLE
|
|
|
->Nagios plug-in development guidelines</TITLE
|
|
|
-><META
|
|
|
-NAME="GENERATOR"
|
|
|
-CONTENT="Modular DocBook HTML Stylesheet Version 1.64
|
|
|
-"></HEAD
|
|
|
-><BODY
|
|
|
-CLASS="BOOK"
|
|
|
-BGCOLOR="#FFFFFF"
|
|
|
-TEXT="#000000"
|
|
|
-LINK="#0000FF"
|
|
|
-VLINK="#840084"
|
|
|
-ALINK="#0000FF"
|
|
|
-><DIV
|
|
|
-CLASS="BOOK"
|
|
|
-><A
|
|
|
-NAME="AEN1"
|
|
|
-></A
|
|
|
-><DIV
|
|
|
-CLASS="TITLEPAGE"
|
|
|
-><H1
|
|
|
-CLASS="TITLE"
|
|
|
-><A
|
|
|
-NAME="AEN3"
|
|
|
->Nagios plug-in development guidelines</A
|
|
|
-></H1
|
|
|
-><H3
|
|
|
-CLASS="AUTHOR"
|
|
|
-><A
|
|
|
-NAME="AEN5"
|
|
|
->Karl DeBisschop</A
|
|
|
-></H3
|
|
|
-><DIV
|
|
|
-CLASS="AFFILIATION"
|
|
|
-><DIV
|
|
|
-CLASS="ADDRESS"
|
|
|
-><P
|
|
|
-CLASS="ADDRESS"
|
|
|
->karl@debisschop.net</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><H3
|
|
|
-CLASS="AUTHOR"
|
|
|
-><A
|
|
|
-NAME="AEN11"
|
|
|
->Ethan Galstad</A
|
|
|
-></H3
|
|
|
-><DIV
|
|
|
-CLASS="AFFILIATION"
|
|
|
-><DIV
|
|
|
-CLASS="ADDRESS"
|
|
|
-><P
|
|
|
-CLASS="ADDRESS"
|
|
|
->netsaint@linuxbox.com</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><H3
|
|
|
-CLASS="AUTHOR"
|
|
|
-><A
|
|
|
-NAME="AEN21"
|
|
|
->Hugo Gayosso</A
|
|
|
-></H3
|
|
|
-><DIV
|
|
|
-CLASS="AFFILIATION"
|
|
|
-><DIV
|
|
|
-CLASS="ADDRESS"
|
|
|
-><P
|
|
|
-CLASS="ADDRESS"
|
|
|
->hgayosso@gnu.org</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><H3
|
|
|
-CLASS="AUTHOR"
|
|
|
-><A
|
|
|
-NAME="AEN27"
|
|
|
->Subhendu Ghosh</A
|
|
|
-></H3
|
|
|
-><DIV
|
|
|
-CLASS="AFFILIATION"
|
|
|
-><DIV
|
|
|
-CLASS="ADDRESS"
|
|
|
-><P
|
|
|
-CLASS="ADDRESS"
|
|
|
->sghosh@sourceforge.net</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><H3
|
|
|
-CLASS="AUTHOR"
|
|
|
-><A
|
|
|
-NAME="AEN33"
|
|
|
->Stanley Hopcroft</A
|
|
|
-></H3
|
|
|
-><DIV
|
|
|
-CLASS="AFFILIATION"
|
|
|
-><DIV
|
|
|
-CLASS="ADDRESS"
|
|
|
-><P
|
|
|
-CLASS="ADDRESS"
|
|
|
->stanleyhopcroft@sourceforge.net</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><P
|
|
|
-CLASS="COPYRIGHT"
|
|
|
->Copyright © 2000 2001 2002 by Karl DeBisschop, Ethan Galstad,
|
|
|
- Hugo Gayosso, Stanley Hopcroft, Subhendu Ghosh</P
|
|
|
-><HR></DIV
|
|
|
-><DIV
|
|
|
-CLASS="TOC"
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><B
|
|
|
->Table of Contents</B
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#PREFACE"
|
|
|
->About the guidelines</A
|
|
|
-></DT
|
|
|
-><DD
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN51"
|
|
|
->Copyright</A
|
|
|
-></DT
|
|
|
-></DL
|
|
|
-></DD
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN56"
|
|
|
-></A
|
|
|
-></DT
|
|
|
-><DD
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#PLUGOUTPUT"
|
|
|
->Plugin Output for Nagios</A
|
|
|
-></DT
|
|
|
-><DD
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN60"
|
|
|
->Print only one line of text</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN63"
|
|
|
->Screen Output</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN67"
|
|
|
->Return the proper status code</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN71"
|
|
|
->Plugin Return Codes</A
|
|
|
-></DT
|
|
|
-></DL
|
|
|
-></DD
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#SYSCMDAUXFILES"
|
|
|
->System Commands and Auxiliary Files</A
|
|
|
-></DT
|
|
|
-><DD
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN117"
|
|
|
->Don't execute system commands without specifying their
|
|
|
- full path</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN121"
|
|
|
->Use spopen() if external commands must be executed</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN125"
|
|
|
->Don't make temp files unless absolutely required</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN128"
|
|
|
->Don't be tricked into following symlinks</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN131"
|
|
|
->Validate all input</A
|
|
|
-></DT
|
|
|
-></DL
|
|
|
-></DD
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#PERLPLUGIN"
|
|
|
->Perl Plugins</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#RUNTIME"
|
|
|
->Runtime Timeouts</A
|
|
|
-></DT
|
|
|
-><DD
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN165"
|
|
|
->Use DEFAULT_SOCKET_TIMEOUT</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN168"
|
|
|
->Add alarms to network plugins</A
|
|
|
-></DT
|
|
|
-></DL
|
|
|
-></DD
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#PLUGOPTIONS"
|
|
|
->Plugin Options</A
|
|
|
-></DT
|
|
|
-><DD
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN174"
|
|
|
->Option Processing</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#AEN187"
|
|
|
->Plugins with more than one type of threshold, or with
|
|
|
- threshold ranges</A
|
|
|
-></DT
|
|
|
-></DL
|
|
|
-></DD
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#SUBMITTINGCHANGES"
|
|
|
->New submissions and patches</A
|
|
|
-></DT
|
|
|
-></DL
|
|
|
-></DD
|
|
|
-></DL
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="PREFACE"
|
|
|
-><HR><H1
|
|
|
-><A
|
|
|
-NAME="PREFACE"
|
|
|
->About the guidelines</A
|
|
|
-></H1
|
|
|
-><P
|
|
|
->The purpose of this guidelines is to provide a reference for
|
|
|
- the plug-in developers and encourage the standarization of the
|
|
|
- different kind of plug-ins: C, shell, perl, python, etc.</P
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H1
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN51"
|
|
|
->Copyright</A
|
|
|
-></H1
|
|
|
-><P
|
|
|
->Nagios Plug-in Development Guidelines Copyright (C) 2000 2001
|
|
|
- 2002
|
|
|
- Karl DeBisschop, Ethan Galstad, Hugo Gayosso, Stanley Hopcroft,
|
|
|
- Subhendu Ghosh</P
|
|
|
-><P
|
|
|
->Permission is granted to make and distribute verbatim
|
|
|
- copies of this manual provided the copyright notice and this
|
|
|
- permission notice are preserved on all copies.</P
|
|
|
-><P
|
|
|
->The plugins themselves are copyrighted by their respective
|
|
|
- authors.</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="ARTICLE"
|
|
|
-><DIV
|
|
|
-CLASS="TOC"
|
|
|
-><DL
|
|
|
-><DT
|
|
|
-><B
|
|
|
->Table of Contents</B
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#PLUGOUTPUT"
|
|
|
->Plugin Output for Nagios</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#SYSCMDAUXFILES"
|
|
|
->System Commands and Auxiliary Files</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#PERLPLUGIN"
|
|
|
->Perl Plugins</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#RUNTIME"
|
|
|
->Runtime Timeouts</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#PLUGOPTIONS"
|
|
|
->Plugin Options</A
|
|
|
-></DT
|
|
|
-><DT
|
|
|
-><A
|
|
|
-HREF="#SUBMITTINGCHANGES"
|
|
|
->New submissions and patches</A
|
|
|
-></DT
|
|
|
-></DL
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><H1
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="PLUGOUTPUT"
|
|
|
->Plugin Output for Nagios</A
|
|
|
-></H1
|
|
|
-><P
|
|
|
->You should always print something to STDOUT that tells if the
|
|
|
- service is working or why its 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.</P
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN60"
|
|
|
->Print only one line of text</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->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.</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN63"
|
|
|
->Screen Output</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->The plug-in should print the diagnostic and just the
|
|
|
- synopsis part of the help message. A well written plugin would
|
|
|
- then have --help as a way to get the verbose help.</P
|
|
|
-><P
|
|
|
->Code and output should try to respect the 80x25 size of a
|
|
|
- crt (remember when fixing stuff in the server room!)</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN67"
|
|
|
->Return the proper status code</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->See <A
|
|
|
-HREF="#RETURNCODES"
|
|
|
->Table 1 in the section called <I
|
|
|
->Plugin Return Codes</I
|
|
|
-></A
|
|
|
-> 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.</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN71"
|
|
|
->Plugin Return Codes</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->The return codes below are based on the POSIX spec of returning
|
|
|
- a positive value. Netsaint prior to v0.0.7 supported non-POSIX
|
|
|
- compliant return code of "-1" for unknown. Nagios supports POSIX return
|
|
|
- codes by default.</P
|
|
|
-><P
|
|
|
->Note: Some plugins will on occasion print on STDOUT that an error
|
|
|
- occurred and error code is 138 or 255 or some such number. These
|
|
|
- are usually caused by plugins using system commands and having not
|
|
|
- enough checks to catch unexpected output. Developers should include a
|
|
|
- default catch-all for system command output that returns an UNKOWN
|
|
|
- return code.</P
|
|
|
-><DIV
|
|
|
-CLASS="TABLE"
|
|
|
-><A
|
|
|
-NAME="RETURNCODES"
|
|
|
-></A
|
|
|
-><P
|
|
|
-><B
|
|
|
->Table 1. Plugin Return Codes</B
|
|
|
-></P
|
|
|
-><TABLE
|
|
|
-BORDER="1"
|
|
|
-BGCOLOR="#E0E0E0"
|
|
|
-CELLSPACING="0"
|
|
|
-CELLPADDING="4"
|
|
|
-CLASS="CALSTABLE"
|
|
|
-><THEAD
|
|
|
-><TR
|
|
|
-><TH
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->Numeric Value</P
|
|
|
-></TH
|
|
|
-><TH
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->Service Status</P
|
|
|
-></TH
|
|
|
-><TH
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->Status Description</P
|
|
|
-></TH
|
|
|
-></TR
|
|
|
-></THEAD
|
|
|
-><TBODY
|
|
|
-><TR
|
|
|
-><TD
|
|
|
-ALIGN="CENTER"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->0</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="MIDDLE"
|
|
|
-><P
|
|
|
->OK</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->The plugin was able to check the service and it
|
|
|
- appeared to be functioning properly</P
|
|
|
-></TD
|
|
|
-></TR
|
|
|
-><TR
|
|
|
-><TD
|
|
|
-ALIGN="CENTER"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->1</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="MIDDLE"
|
|
|
-><P
|
|
|
->Warning</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->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</P
|
|
|
-></TD
|
|
|
-></TR
|
|
|
-><TR
|
|
|
-><TD
|
|
|
-ALIGN="CENTER"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->2</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="MIDDLE"
|
|
|
-><P
|
|
|
->Critical</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->The plugin detected that either the service was not
|
|
|
- running or it was above some "critical" threshold</P
|
|
|
-></TD
|
|
|
-></TR
|
|
|
-><TR
|
|
|
-><TD
|
|
|
-ALIGN="CENTER"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->3</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="MIDDLE"
|
|
|
-><P
|
|
|
->Unknown</P
|
|
|
-></TD
|
|
|
-><TD
|
|
|
-ALIGN="LEFT"
|
|
|
-VALIGN="TOP"
|
|
|
-><P
|
|
|
->Invalid command line arguments were supplied to the
|
|
|
- plugin or the plugin was unable to check the status of the given
|
|
|
- hosts/service</P
|
|
|
-></TD
|
|
|
-></TR
|
|
|
-></TBODY
|
|
|
-></TABLE
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H1
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="SYSCMDAUXFILES"
|
|
|
->System Commands and Auxiliary Files</A
|
|
|
-></H1
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN117"
|
|
|
->Don't execute system commands without specifying their
|
|
|
- full path</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->Don't use exec(), popen(), etc. to execute external
|
|
|
- commands without explicity using the full path of the external
|
|
|
- program.</P
|
|
|
-><P
|
|
|
->Doing otherwise makes the plugin vulnerable to hijacking
|
|
|
- by a trojan horse earlier in the search path. See the main
|
|
|
- plugin distribution for examples on how this is done.</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN121"
|
|
|
->Use spopen() if external commands must be executed</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->If you have to execute external commands from within your
|
|
|
- plugin and you're writing it in C, use the spopen() function
|
|
|
- that Karl DeBisschop has written.</P
|
|
|
-><P
|
|
|
->The code for spopen() and spclose() is included with the
|
|
|
- core plugin distribution.</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN125"
|
|
|
->Don't make temp files unless absolutely required</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->If temp files are needed, make sure that the plugin will
|
|
|
- fail cleanly if the file can't be written (e.g., too few file
|
|
|
- handles, out of disk space, incorrect permissions, etc.) and
|
|
|
- delete the temp file when processing is complete.</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN128"
|
|
|
->Don't be tricked into following symlinks</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->If your plugin opens any files, take steps to ensure that
|
|
|
- you are not following a symlink to another location on the
|
|
|
- system.</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN131"
|
|
|
->Validate all input</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->use routines in utils.c or utils.pm and write more as needed</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H1
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="PERLPLUGIN"
|
|
|
->Perl Plugins</A
|
|
|
-></H1
|
|
|
-><P
|
|
|
->Perl plugins are coded a little more defensively than other
|
|
|
- plugins because of embedded Perl. When configured as such, embedded
|
|
|
- Perl Nagios (ePN) requires stricter use of the some of Perl's features.
|
|
|
- This section outlines some of the steps needed to use ePN
|
|
|
- effectively.</P
|
|
|
-><P
|
|
|
-></P
|
|
|
-><OL
|
|
|
-TYPE="1"
|
|
|
-><LI
|
|
|
-><P
|
|
|
-> 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
|
|
|
- particular, do not use BEGIN blocks to initialize variables.</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->To use utils.pm, you need to provide a full path to the
|
|
|
- module in order for it to work with ePN.</P
|
|
|
-><P
|
|
|
-CLASS="LITERALLAYOUT"
|
|
|
-> e.g.<br>
|
|
|
- use lib "/usr/local/nagios/libexec";<br>
|
|
|
- use utils qw(...);<br>
|
|
|
- </P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->Perl scripts should be called with "-w"</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->All Perl plugins must compile cleanly under "use strict" - i.e. at
|
|
|
- least explicitly package names as in "$main::x" or predeclare every
|
|
|
- variable. </P
|
|
|
-><P
|
|
|
->Explicitly initialize each varialable in use. Otherwise with
|
|
|
- caching enabled, the plugin will not be recompilied each time, and
|
|
|
- therefore Perl will not reinitialize all the variables. All old
|
|
|
- variable values will still be in effect.</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->Do not use < DATA > (these simply do not compile under ePN).</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->Do not use named subroutines</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->If writing to a file (perhaps recording
|
|
|
- performance data) explicitly close close it. The plugin never
|
|
|
- calls <I
|
|
|
-CLASS="EMPHASIS"
|
|
|
->exit</I
|
|
|
->; that is caught by
|
|
|
- p1.pl, so output streams are never closed.</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->As in <A
|
|
|
-HREF="#RUNTIME"
|
|
|
->the section called <I
|
|
|
->Runtime Timeouts</I
|
|
|
-></A
|
|
|
-> all plugins need
|
|
|
- to monitor their runtime, specially if they are using network
|
|
|
- resources. Use of the <I
|
|
|
-CLASS="EMPHASIS"
|
|
|
->alarm</I
|
|
|
-> is recommended.
|
|
|
- Plugins may import a default time out ($TIMEOUT) from utils.pm.
|
|
|
- </P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->Perl plugins should import %ERRORS from utils.pm
|
|
|
- and then "exit $ERRORS{'OK'}" rather than "exit 0"
|
|
|
- </P
|
|
|
-></LI
|
|
|
-></OL
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H1
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="RUNTIME"
|
|
|
->Runtime Timeouts</A
|
|
|
-></H1
|
|
|
-><P
|
|
|
->Plugins have a very limited runtime - typically 10 sec.
|
|
|
- As a result, it is very important for plugins to maintain internal
|
|
|
- code to exit if runtime exceeds a threshold. </P
|
|
|
-><P
|
|
|
->All plugins should timeout gracefully, not just networking
|
|
|
- plugins. For instance, df may lock if you have automounted
|
|
|
- drives and your network fails - but on first glance, who'd think
|
|
|
- df could lock up like that. Plus, it should just be more error
|
|
|
- resistant to be able to time out rather than consume
|
|
|
- resources.</P
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN165"
|
|
|
->Use DEFAULT_SOCKET_TIMEOUT</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->All network plugins should use DEFAULT_SOCKET_TIMEOUT to timeout</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN168"
|
|
|
->Add alarms to network plugins</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->If you write a plugin which communicates with another
|
|
|
- networked host, you should make sure to set an alarm() in your
|
|
|
- code that prevents the plugin from hanging due to abnormal
|
|
|
- socket closures, etc. Nagios takes steps to protect itself
|
|
|
- against unruly plugins that timeout, but any plugins you create
|
|
|
- should be well behaved on their own.</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H1
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="PLUGOPTIONS"
|
|
|
->Plugin Options</A
|
|
|
-></H1
|
|
|
-><P
|
|
|
->A well written plugin should have --help as a way to get
|
|
|
- verbose help. Code and output should try to respect the 80x25 size of a
|
|
|
- crt (remember when fixing stuff in the server room!)</P
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN174"
|
|
|
->Option Processing</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->For plugins written in C, we recommend the C standard
|
|
|
- getopt library for short options. If using getopt_long, check to
|
|
|
- be sure that HAVE_GETOPT_H is defined (configure checks this and
|
|
|
- sets the #define in common/config.h).</P
|
|
|
-><P
|
|
|
->For plugins written in Perl, we recommend Getopt::Long module.</P
|
|
|
-><P
|
|
|
->Positional arguments are strongly discouraged.</P
|
|
|
-><P
|
|
|
->There are a few reserved options that should not be used
|
|
|
- for other purposes:</P
|
|
|
-><P
|
|
|
-CLASS="LITERALLAYOUT"
|
|
|
-> -V version (--version)<br>
|
|
|
- -h help (--help)<br>
|
|
|
- -t timeout (--timeout)<br>
|
|
|
- -w warning threshold (--warning)<br>
|
|
|
- -c critical threshold (--critical)<br>
|
|
|
- -H hostname (--hostname)<br>
|
|
|
- </P
|
|
|
-><P
|
|
|
->In addition to the reserved options above, some other standard options are:</P
|
|
|
-><P
|
|
|
-CLASS="LITERALLAYOUT"
|
|
|
-> -C SNMP community (--community)<br>
|
|
|
- -a authentication password (--authentication)<br>
|
|
|
- -l login name (--logname)<br>
|
|
|
- -p port or password (--port or --passwd/--password)monitors operational<br>
|
|
|
- -u url or username (--url or --username)<br>
|
|
|
- </P
|
|
|
-><P
|
|
|
->Look at check_pgsql and check_procs to see how I currently
|
|
|
- think this can work. Standard options are:</P
|
|
|
-><P
|
|
|
->The option -V or --version should be present in all
|
|
|
- plugins. For C plugins it should result in a call to print_revision, a
|
|
|
- function in utils.c which takes two character arguments, the
|
|
|
- command name and the plugin revision.</P
|
|
|
-><P
|
|
|
->The -? option, or any other unparsable set of options,
|
|
|
- should print out a short usage statement. Character width should
|
|
|
- be 80 and less and no more that 23 lines should be printed (it
|
|
|
- should display cleanly on a dumb terminal in a server
|
|
|
- room).</P
|
|
|
-><P
|
|
|
->The option -h or --help should be present in all plugins.
|
|
|
- In C plugins, it should result in a call to print_help (or
|
|
|
- equivalent). The function print_help should call print_revision,
|
|
|
- then print_usage, then should provide detailed
|
|
|
- help. Help text should fit on an 80-character width display, but
|
|
|
- may run as many lines as needed.</P
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H2
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="AEN187"
|
|
|
->Plugins with more than one type of threshold, or with
|
|
|
- threshold ranges</A
|
|
|
-></H2
|
|
|
-><P
|
|
|
->Old style was to do things like -ct for critical time and
|
|
|
- -cv for critical value. That goes out the window with POSIX
|
|
|
- getopt. The allowable alternatves are:</P
|
|
|
-><P
|
|
|
-></P
|
|
|
-><OL
|
|
|
-TYPE="1"
|
|
|
-><LI
|
|
|
-><P
|
|
|
->long options like -critical-time (or -ct and -cv, I
|
|
|
- suppose).</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->repeated options like `check_load -w 10 -w 6 -w 4 -c
|
|
|
- 16 -c 10 -c 10`</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->for brevity, the above can be expressed as `check_load
|
|
|
- -w 10,6,4 -c 16,10,10`</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->ranges are expressed with colons as in `check_procs -C
|
|
|
- httpd -w 1:20 -c 1:30` which will warn above 20 instances,
|
|
|
- and critical at 0 and above 30</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->lists are expressed with commas, so Jacob's check_nmap
|
|
|
- uses constructs like '-p 1000,1010,1050:1060,2000'</P
|
|
|
-></LI
|
|
|
-><LI
|
|
|
-><P
|
|
|
->If possible when writing lists, use tokens to make the
|
|
|
- list easy to remember and non-order dependent - so
|
|
|
- check_disk uses '-c 10000,10%' so that it is clear which is
|
|
|
- the precentage and which is the KB values (note that due to
|
|
|
- my own lack of foresight, that used to be '-c 10000:10%' but
|
|
|
- such constructs should all be changed for consistency,
|
|
|
- though providing reverse compatibility is fairly
|
|
|
- easy).</P
|
|
|
-></LI
|
|
|
-></OL
|
|
|
-><P
|
|
|
->As always, comments are welcome - making this consistent
|
|
|
- without a host of long options was quite a hassle, and I would
|
|
|
- suspect that there are flaws in this strategy. Perhaps clear
|
|
|
- long-options is the most important of the above choices, but not
|
|
|
- all POSIX systems have C libraries for long options, so the
|
|
|
- short forms must exist as well.</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-><DIV
|
|
|
-CLASS="SECTION"
|
|
|
-><HR><H1
|
|
|
-CLASS="SECTION"
|
|
|
-><A
|
|
|
-NAME="SUBMITTINGCHANGES"
|
|
|
->New submissions and patches</A
|
|
|
-></H1
|
|
|
-><P
|
|
|
->If you would like other to use your plugins and have it included in
|
|
|
- the standard distribution, please include patches for the relavant
|
|
|
- configuration files, in particular "configure.in" Otherwise submitted
|
|
|
- plugins will be included in the contrib directory.</P
|
|
|
-><P
|
|
|
->Plugins in the contrib directory are going to be migrated to the
|
|
|
- standard plugins/plugin-scripts directory as time permits and per user
|
|
|
- requests</P
|
|
|
-><P
|
|
|
->Patches should be submitted via the SourceForge and be announced to
|
|
|
- the mailing list.</P
|
|
|
-><P
|
|
|
->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.</P
|
|
|
-><P
|
|
|
->If possible please submit a test harness. Documentation on sample
|
|
|
- tests coming soon.</P
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-></DIV
|
|
|
-></BODY
|
|
|
-></HTML
|
|
|
->
|
Ton Voon