send_nrdp Perl Client

Project Notes

###############################################################################
# send_nrdp.pl - Perl implementation of an NRDP client.
# Written: March 2011
# Author: Adam McLean
###############################################################################

Design Goals:
------------
1) Our environment is mixed Unix (AIX, Linux, Solaris). This needs to work on
them all without CPAN modules. This meant no SSL support (sorry).
2) Act as a drop-in replacement for send_nrpe. Many scripts already call
send_nrpe, and we'd like to move to NRDP seamlessly.
3) Allow for basic http authentication for those who like to have casual
protection. Note that without SSL the user/password hash can be intercepted
and easily read.
3) Optionally cache results if a send is failed so they can be retried the next
time the script is run. Accomodates alarms that occur during Nagios builds or
downtime.
4) Optionally send results to a second server running NRDP to accomodate
distributed environemnts. One of them is likely up and can send the alarm if
configured.
5) Optionally write an execution log file so verification / debugging is made
easy.

Command Line Options:
---------------------
-H [hostname]
** REQUIRED **
- Specify the host address or IP address of the listening server.
-p [port]
** OPTIONAL **
This value is ignored and exists for backward compatibility with send_nrpe.
All communication is via port 80.
-to [seconds]
** OPTIONAL **
- Number of seconds to wait before considering execution a timeout.
- Default is 10.
-d [delimiter]
** OPTIONAL **
- The delimiter to use when parsing alarms from standard input.
- Default is tab.
-c [config_file]
** OPTIONAL **
- Full path to the configuration file containing additional options.
- This can be the send_nrpe configuration file with nrdp options in it, or
a file with just nrdp options in it.
-od
** OPTIONAL **
- Added for backward compatability with send_nrpe. nrpd doesn't appear
to use timestamps in its execution. Data is sent first in first out.
-url [url]
** REQUIRED on commandline or Config file **
- URL that the nrdp CGI can be found at.
-token [token]
** REQUIRED on commandline or Config file **
- Token to use when submitting alarms.
-http_user [user]
** OPTIONAL **
- User name to use when using basic http authentication.
-http_pass [pass]
** OPTIONAL **
- Password to use when using basic http authentication.
-debug
** OPTIONAL **
- Debug messages will be printed to stdout/stderr during execution.

Configuration file options:
---------------------------
Many of the extended options go in the configuration file. Because this
can be used as a drop-in replacement for send_nrpe the configuration name=value
pairs are prefixed with a comment. This allows them to live in the send_nrpe
configuration file without interfering with normal send_nrpe operation.

NOTE: All configuration options are in the format of # NRDP name=value
NOTE: Values specified on the commandline over-ride values in the config file.

# NRDP url=[url]
** REQUIRED in Config or commandline **
- URL that the NRDP cgi can be found at.
# NRDP token=[token]
** REQUIRED in Config or commandline **
- Token to use when submitting results to NRDP.
# NRDP http_user=[user]
** OPTIONAL **
- User name to use when using basic http authentication.
# NRDP http_pass=[pass]
** OPTIONAL **
- Password to use when using basic http authentication.
# NRDP additional_host=[hostname]
** OPTIONAL **
- Specify the additional host to notify.
- NOTE: the URL for NRDP must be the same for this host as the one specified
by the (-H) commandline option.
# NRDP cache_file=[filename]
** OPTIONAL **
- Full path to the cache file to write failed send results to.
- These will queue up until they are considered expired or succesfully sent.
- Every time send_nrdp is called it will first try to send its cached
results, then send fresh ones.
# NRDP cache_expiration=[seconds]
** OPTIONAL **
- Number of seconds before we consider cached results as stale and discard
them.
- NOTE: There is no default for this. If you don't use this option beware that
a busy host that can't talk to NRDP for a long period of time could make
a very large cache_file.
# NRDP logging=[0|1]
** OPTIONAL **
- Whether our execution should be logged. Set to 1 for true 0 for false.
- Defult is false (0).
- Data is logged to the log_file as defined (see below).
# NRDP log_file=[filename]
** OPTIONAL **
- Full path to the log filename. This will be written to if logging is
set to true (1).
# NRDP parse_fatal=[0|1]
** OPTIONAL **
- Alarms are sent via stdin, and we expect them in a certain format.
- Sometimes we're sending hundreds of alarms at once, and for whatever
reason, one of those alarms might be missing a delimiter, or may come
in with too many / few columns.
- This controls whether a single alarm being incorrectly formatted is
considered fatal, and prevents the send of the remaining alarms.
- Default value is true (1), set to false (0) if errors in formatting
are non-fatal, and shouldn't impede normal operation.
# NRDP debug=[0|1]
** OPTIONAL **
- Determines whether debug messages should be sent to the log_file.
- Allows for easy verification / debugging of scripted use of send_nrdp.pl
when you can't be there to watch stdout/stderr.

Alarm format:
-------------
Alarms are sent to send_nrdp the same way they go to send_nrpe. Delimited
by a seperator, and terminated by literal newlines.

Service Checks:
<host_name>[tab]<svc_description>[tab]<return_code>[tab]<plugin_output>[newline]

Host Checks:
<host_name>[tab]<return_code>[tab]<plugin_output>[newline]

NOTE: If you are sending long output in your plugin_output, make sure and use
a LITERAL n, and not a newline character. Otherwise you'll get parsing
errors.