Man page for the Nagios notification script nagios_send_service

nagios_send_service_mail.pl

This script takes over the Nagios service e-mail notifications by receiving the Nagios service state information, formatting the e-mail according to various flags and sending it out through an SMTP gateway.

Prerequisites:

Nagios: Nagios-based monitoring system with Nagios environment macros enabled. This is usually done in [nagios_home]/etc/nagios.cfg.

enable_environment_macros=1

Perl: The script is written in Perl, and depends on the following Perl packages:

Mail::Sendmail package, i.e. perl-Mail-Sendmail-0.79-102.1.i586
Getopt::Long
Digest::MD5
MIME::Base64
RRDs perl package; coming with rrdtool. Notification scripts since version 1.8.0 require rrdtool 1.4.x and above.
File::Temp (for graph generation)

A frequently asked question is about the dependency on the mail server Sendmail. There is no such dependency, this is only a unfortunate naming of the perl library Mail::Sendmail, which is providing e-mail related functions to the scripts. The scripts work fine with any mail server, including Postfix, Exim, or others.

Usage:

nagios_send_service_mail.pl [-v] [-V] [-h] [-t] [-H <SMTP host>] [-p <company-name>] [-r <to_recipients>] [-c <cc_recipients>] [-b <bcc_recipients>] [-f <text|html|multi|graph>] [-u] [-l <en|jp|fr|de>]

Options:

-v, --verbose
print extra debugging information

-V, --version
prints version number -h, --help
print this help message

-h, --help
shows the programs help and options

-H, --smtphost=HOST
name or IP address of SMTP gateway

-t, --test
sends a test e-mail to confirm mail functions

-p, --customer
adds a company name header to the ouput

-r, --to-recipients
with this option, the Nagios-provided $CONTACTADDRESS1$ list of to: recipients is overridden. It is good to use this arg together with -t/--test option

-c, --cc-recipients
to add cc: recipients, add this argument and set it to receive the Nagios-provided $CONTACTADDRESS1$ list

-b, --bcc-recipients
the Nagios-provided $CONTACTADDRESS2$ list of bcc: recipients

-f, --format='text|html|multi|graph'
the email format to generate: either plain text,HTML, multipart S/Mime ouput with a inline logo or multipart S/Mime adding the Nagiosgraph performance image

-u, --addurl
this adds URL's to the Nagios web GUI for check status, host and hostgroup views into the html mail, requires -f html, -f multi or -f graph

-l, --language='en|jp|fr|de'
the prefered e-mail language. The content-type header is currently is hard-coded to UTF-8. This might need to be changed if recipients require a different characterset encoding.

Notification Definition Example:

Below is an example of the notification definition in the Nagios command.cfg file. I typically move all notification commands into its own configuration file notifictions.cfg (example).

# 'service-email-html-int-en' command definition
# sends HTML e-mails in English and includes Nagios URL for Intranet access
define command{
        command_name    service-email-html-int-en
        command_line    /srv/app/nagios/bin/nagios_send_service_mail.pl \
-c "$CONTACTADDRESS1$" \
-f html -u
}

Here, the -c "$CONTACTADDRESS1$" \ line is optional, and just demonstrating the ability to define cc: lists.

Script Usage Example:

text - The notification script with its most basic use, English language and plaintext notification.

Nagios notification example using text: service critical

html The same example notification using the -f html and -u options, formatting the content as HTML with links to Nagios.

Nagios notification example using html: service critical

multi - A similar example notification using the -f multi and -u options, formatting the content as S/Mime multipart HTML and adds the logo image.

Nagios notification example using multi: service critical

graph - Performance Graphs: Since version 1.4, 'nagios_send_service_mail.pl' is able to pick up RRD perfomance data and include a on-the-fly generated graph image with the notification. This works with Nagiosgraph v0.9.1 and possibly also with later Nagiosgraph versions. If Nagiosgraph is not available, then it is best to use only the notification formats 'text', 'html' and 'multi'.

Nagios notification example using graph: service critical

Troubleshooting:

Check access/execution rights: It is best to place the scripts in the Nagios plugin directory, and have them be owned by the Nagios user and group.

root@susie:/srv/app/nagios/lib# ls -l nagios_send_*
-rwxr-xr-x 1 nagios nagios 45490 May 23 09:57 nagios_send_host_mail.pl
-rwxr-xr-x 1 nagios nagios 46709 May 22 22:36 nagios_send_service_mail.pl

Check environment macros: The data handover between Nagios and the notification scripts works largely through Nagios environment macros. To ensure the scripts can pick up Nagios data, check the following setting in nagios.cfg:

susie:~ # grep enable_environment_macros /srv/app/nagios/etc/nagios.cfg
enable_environment_macros=1

Check verbose output: For easy troubleshooting, defining the commandline in with the verbose '-v' option and redirecting the output into a temporary log file is very handy, i.e.:

command_line /srv/app/nagios/lib/nagios_send_service_mail.pl \
-f multi -u -v > /tmp/nagios_send_service_mail.log

Check network connectivity: In order to send mails, the scripts need to talk to the SMTP mail relay server. This can be tested in various ways. For checking plain network reachability, telnet host/port:

susie:~ # telnet susie.frank4dd.com 25
Trying 70.85.16.97...
Connected to susie.frank4dd.com.
Escape character is '^]'.
220 susie.frank4dd.com ESMTP Postfix

Check mail sending: Confirm the mail settings and correct delivery, using a commandline tool, e.g.

susie:~ # echo "Test message" | mailx -v -r "me@example.com" -s "Test" 
-S smtp="mail.example.com:587" me@thishost.com

Test the notification script: Running the Nagios notification script with the '-t' option creates a test e-mail, together with extra debug output into the mail, and console.

root@susie:/srv/app/nagios/lib# ./nagios_send_service_mail.pl -v -t -r me@frank4dd.com -f graph -u -l en
main: trying to create the Nagiosgraph image.
sub dbfilelist: Checking files inside directory: /srv/app/nagiosgraph/rrd/gw-li10/check%2Dhost%2Dalive___
sub dbfilelist: We found number of files: 1
sub graphinfo: Listing gw-li10/check%2Dhost%2Dalive___ db files in /srv/app/nagiosgraph/rrd: gw-li10/check%2Dhost%2Dalive___ping.rrd
DS gw-li10/check%2Dhost%2Dalive___ping.rrd lines: losspct, rta
file=gw-li10/check%2Dhost%2Dalive___ping.rrd
sub rrdline: file=gw-li10/check%2Dhost%2Dalive___ping.rrd line=losspct color=CC3300
sub rrdline: file=gw-li10/check%2Dhost%2Dalive___ping.rrd line=rta color=993399
create_graph_image: RRDs::graph /tmp/S1Q_YwBZ8W -a PNG -t check-host-alive --border=1 --color=BACK#F2F2F2 --color=SHADEA#000000 --color=SHADEB#000000 DEF:losspct=/srv/app/nagiosgraph/rrd/gw-li10/check%2Dhost%2Dalive___ping.rrd:losspct:AVERAGE LINE2:losspct#CC3300:losspct GPRINT:losspct:MAX:Max\: %6.2lf%s GPRINT:losspct:AVERAGE:Avg\: %6.2lf%s GPRINT:losspct:MIN:Min\: %6.2lf%s GPRINT:losspct:LAST:Cur\: %6.2lf%s\n DEF:rta=/srv/app/nagiosgraph/rrd/gw-li10/check%2Dhost%2Dalive___ping.rrd:rta:AVERAGE LINE2:rta#993399:rta     GPRINT:rta:MAX:Max\: %6.2lf%s GPRINT:rta:AVERAGE:Avg\: %6.2lf%s GPRINT:rta:MIN:Min\: %6.2lf%s GPRINT:rta:LAST:Cur\: %6.2lf%s\n -w 521 -h 60
b64encode_img: completed conversion of source image file: /tmp/S1Q_YwBZ8W -
create_graph_image: Encoded Nagiosgraph image file, format: png

main: Sending HTML email (language: en) with inline logo.
b64encode_img: completed conversion of source image file: /srv/www/std-root/nagios.fm4dd.com/images/nagios-mail.gif -
main: Converted inline logo to base64 and set type to gif.
Sendmail Log says:
Mail::Sendmail v. 0.79_16  - Wed Jun  3 13:02:46 2012
Date: Wed, 3 Jun 2012 13:02:46 +0900
Server: 127.0.0.1 Port: 25
From: nagiosadmin@frank4dd.com
Subject: Nagios: TEST service check-host-alive on gw-li10 (Linux Servers) is UNKNOWN
To: me@frank4dd.com

Result: 250 2.0.0 Ok: queued as 4DCB781E7

Comments:

Please edit the head of the scripts to set the mail return address and Nagios base URL. Particularly the scripts mail sender address. I get occasional notification e-mails from various companies for system or service problems, because the scripts still have my sender mail address.

Language Support: Multi-language language support (French, German, English, Japanese) is implemented, and the definitions can be extended to support other languages as well.

Color Coding: Below is the color code table for the notification type and service states. Color can be easily adjusted by setting the %NOTIFICATIONCOLOR values to a different RGB code.

Type	Name	Color Value
Notification Type	PROBLEM	#FF8080
	RECOVERY	#80FF80
	ACKNOWLEDGEMENT	#FFFF80
	DOWNTIMESTART	#80FFFF
	DOWNTIMEEND	#80FF80
	DOWNTIMECANCELLED	#FFFF80
	FLAPPINGSTART	#FF8080
	FLAPPINGSTOP	#80FF80
	FLAPPINGDISABLED	#FFFF80
	TEST	#80FFFF
Service State	CRITICAL	#FFAA60
	WARNING	#FFFF80
	OK	#80FF80
	UNKNOWN	#80FFFF

Bugs:

The scripts reported to fail when they are used with the Nagios embedded Perl interpreter. The error message is similar to this:

    **ePN failed to compile /etc/nagios3/plugins/nagios_send_host_mail.pl:
    "Variable "$Version" will not stay shared at (eval 1) line 156," at /usr/
    lib/nagios3/p1.pl line 250.

I added a '# nagios: -epn' directive on the scripts line 3 to explicitly disable the use of the embedded Perl interpreter. Using ther embedded Perl interpreter is dangoerous because of the easy introduction of memory leaks.

Nagios v4.0.0-4.0.2 with Nagios BugID 0000498: In these affected versions, the Nagios environment variables are not exported, and as a result the data handover to the scripts does not work. No notifications go out since no destination e-mail address comes from Nagios. This problem is fixed from Nagios 4.0.3 and up.

Download:

nagios_send_service_mail.pl (version 1.8.1, 48814 Bytes)

For an alternate download location, see also the corresponding github repository.

Older Versions:

nagios_send_service_mail-v180.pl Obsolete version 1.8.0, 46712 Bytes

nagios_send_service_mail-v173.pl Obsolete version 1.7.3, 45162 Bytes

nagios_send_service_mail-v14.pl Obsolete version 1.4.0, 41368 Bytes

nagios_send_service_mail-v13.pl Obsolete version 1.3.0, 31664 Bytes

nagios_send_service_mail.pl