Writing NetSaint Plugins


Plugin Development

One of the nice features of NetSaint is that it is designed to use external programs (called "plugins") to check the status of monitored hosts/services. This makes it easy for you to write your own plugins to monitor any type of service you like. If you create a new plugin and feel like sharing it with others, let me know and I'll make it available for download with the other plugins.

With What Shall I Write It?

NetSaint plugins can be compiled C/C++ programs, PERL scripts, shell scripts, or anything you like. NetSaint simply doesn't care.

What Are The Guidelines For Plugins?

Following these simple guidlines when writing plugins will help ensure they integrate well with NetSaint. The last three are security related and were suggested by Karl DeBisschop.

  1. Print something, but keep it short
    You should always print something to STDIO 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.
  2. Print only one line of text
    NetSaint will only grab the first line of text from STDIO 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.
  3. Don't print semi-colons in the output
    NetSaint uses semi-colons to parse data in log files, so you should take steps to ensure that your output does not contain any.
  4. Add alarms to network plugins
    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.
  5. Return the proper status code
    See the table 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.
  6. Don't execute external programs without specifying the full path
    Don't exec(), fork(), or whatever any programs without explicity using the full path of the external program. Doing otherwise makes the plugin vulnerable to hijacking by a trojan horse earlier in the search path.
  7. Don't use popen()
    The popen() function has buffer overflow-related security issues.
  8. Don't make temp files unless absolutely required
    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.)

Where Can I Find Examples?

You can download the source code for various plugins at www.netsaint.org. Look at these for examples on how to return the proper status levels, text output, etc. They are not perfect, but they work.

Plugin Return Codes

Numeric Value Service Status Status Description
0 Ok The plugin was able to check the service and it appeared to be functioning properly
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
-1 Unknown Invalid command line arguments were supplied to the plugin or the plugin was unable to check the status of the given hosts/service
2 Critical The plugin detected that either the service was not running or it was above some "critical" threshold