nagios_send_host_mail.pl


This script takes over the Nagios host e-mail notifications by receiving the Nagios host 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:

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_host_mail.pl [-v] [-V] [-h] [-t] [-H <SMTP host>] [-p ] [-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
      creates a test notification e-mail

-p, --customer
      adds the customer or company name header

-r, --to-recipients
      this argument overrides the Nagios-provided $CONTACTEMAIL$ list of to: recipients. It is good to use together with the -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 and graph adds the Nagiosgraph performance image if available

-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).

# 'host-email-html-int-en' command definition
# sends HTML e-mails in English and includes Nagios URL for Intranet access
define command{
        command_name    host-email-html-int-en
        command_line    /srv/app/nagios/bin/nagios_send_host_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:


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

Nagios notification example using text: host down

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

Nagios notification example using html: host down

The same example notification using the -f multi -u options, formatting as HTML with links to Nagios, and adding the logo image.

Nagios notification example using multi: host down

Since version 1.4, it 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'.

From version 1.7, all improvements that went into the pnp4n scripts were backported into the Nagiosgraph scripts. This includes improved debugging, additional language support (French, German, English, Japanese), and other minor updates.

Nagios notification example using graph: host down

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 the output into a temporary log file is very handy, i.e.:

command_line /srv/app/nagios/lib/nagios_send_host_mail.pl \
-f multi -u -v > /tmp/nagios_send_host_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_host_mail.pl -v -t -r me@frank4dd.com -f graph -u -l en

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 host states. Color can be easily adjusted by setting the %NOTIFICATIONCOLOR values to a different RGB code.

TypeNameColor ValueColor
Notification TypePROBLEM#FF8080 
RECOVERY#80FF80 
ACKNOWLEDGEMENT#FFFF80 
DOWNTIMESTART#80FFFF 
DOWNTIMEEND#80FF80 
DOWNTIMECANCELLED#FFFF80 
FLAPPINGSTART#FF8080 
FLAPPINGSTOP#80FF80 
FLAPPINGDISABLED#FFFF80 
TEST#80FFFF 
Host StateDOWN#FFAA60 
UP#80FF80 
UNREACHABLE#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_host_mail.pl (Latest version 1.8.0, 45490 Bytes)

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

Older Versions:

nagios_send_host_mail-v173.pl Obsolete version 1.7.3, 43891 Bytes

nagios_send_host_mail-v14.pl Obsolete version 1.4.0, 38330 Bytes

nagios_send_host_mail-v13.pl Obsolete version 1.3.0, 28477 Bytes


Implementation Guide - Further information and implementation notes can be found under Flexible Notifications for Nagios.

nagios_send_service_mail.pl - The Nagios monitoring script for services and Nagiosgraph can be found here: nagios_send_service_mail manual.

pnp4n_send_service_mail.pl - The Nagios monitoring script for services with PNP4Nagios can be found here: pnp4n_send_service_mail manual.

Topics:

More Information: