Intro/Background
The check_email_delivery plugin allows you to send an email message and then check that it was received. This is also called checking an email loop. This is accomplished through two additional plugins (included), called check_smtp_send and check_imap_receive. As of version 0.5, you can also use other plugins to create the loop.
This project includes:
check_smtp_send - connects to an SMTP server and sends a message
check_imap_receive - connects to and searches an IMAP account for messages
check_email_delivery - sends email and verifies delivery using other plugins
Documentation:
http://www.openparty.net/2008/software/NagiosCheckEmailDelivery/check_smtp_send.html
http://www.openparty.net/2008/software/NagiosCheckEmailDelivery/check_imap_receive.html
http://www.openparty.net/2008/software/NagiosCheckEmailDelivery/check_email_delivery.html
You can use check_smtp_send and check_imap_receive independently, and you can use check_email_delivery to check that an email loop is working.
Features of check_smtp_send:
- custom headers
- custom body message
- can accept body message from stdin
- SSL and SASL support via Net::SMTP::SSL and Authen::SASL
- TLS support via Net::SMTP::TLS
- CRAM-MD5 and more support via Net::SMTP_auth
Features of check_imap_receive:
- select which mailbox to check (defaults to INBOX)
- use IMAP search feature to select only relevant messages
- capture-max option enables you to compare selected emails and find the highest integer value of interest in them using a regular expression; this value is reported in plugin's output
- option to delete or leave selected messages
- option to delete selected messages except the one with the highest value found by capture-max
- plugin output reports elapsed time, number of emails found, value captured (if applicable), and number of emails deleted
- SSL support via IO::Socket::SSL
- a local search option allows you to download messages and search locally instead of using the IMAP SEARCH command on the server (especially useful for Exchange 2003 admins who suffer from slow indexing times)
Features of check_email_delivery:
- uses separate plugins for email sending and receiving, so you could use alternative plugins to do this work
- does not use any additional database to keep track of which emails were sent or received... out of the box it stamps sent emails with time sent and it uses the capture-max option of the imap plugin to find the most recent email received, and applies threshold to this difference
- option to save status into a tab-delimited file to help with running statistics on email delivery loop (--file)
I use these plugins on my networks so I'm open to suggestions for improvements and to assist you with some difficulties if you use these plugins.
All three plugins are documented with perl POD. Use the --help option to view it.
Download
Current version is 0.6.3, posted on 2 July 2008.
Tar/Gzip
http://www.buhacoff.net/2008/projects/nagios/check_email_delivery-0.6.4.tar.gz
Zip
http://www.buhacoff.net/2008/projects/nagios/check_email_delivery-0.6.4.zip
How to Install
Copy the 3 included scripts to your nagios plugin folder.
How to Run
Sample Nagios configuration
define command{
command_name check_email_delivery
command_line $USER1$/check_email_delivery -H $HOSTADDRESS$ --mailfrom $ARG3$ --mailto $ARG4$ --username $ARG5$ --password $ARG6$ --libexec $USER1$ -w $ARG1$ -c $ARG2$
}
define service{
use generic-service
host_name mail.your.net
service_description EMAIL DELIVERY
check_command check_email_delivery!5!120!sender@your.net!recipient@your.net!recipient@your.net!password
}
Sample configuration with plugins specified (since version 0.5)
A new usage example equivalent to the old one but using the new --plugins and --token options:
define command{
command_name check_email_delivery
command_line $USER1$/check_email_delivery -p '$USER1$/check_smtp_send -H $HOSTADDRESS$ --mailfrom $ARG3$ --mailto $ARG4$ -U $ARG5$ -P $ARG6$ --header "Subject: Nagios %TOKEN1%" -w $ARG1$ -c $ARG2$' -p '$USER1$/check_imap_receive -H $HOSTADDRESS$ -U $ARG5$ -P $ARG6$ -s SUBJECT -s "Nagios %TOKEN1%" -w $ARG1$ -c $ARG2$' -w $ARG1$,$ARG1$ -c $ARG2$,$ARG2$
}
define service{
use generic-service
host_name mail.your.net
service_description EMAIL DELIVERY
check_command check_email_delivery!5!120!sender@your.net!recipient@your.net!recipient@your.net!password
}
Sample configuration for Nagios with ePN
If you are using Nagios with embedded perl (ePN), you must use the epn versions of the plugin (included in the distribution). If you don't, you are likely to get an error saying "ePN failed to compile /usr/lib/nagios/plugins/check_email_delivery: Missing right curly or square bracket". Your epn-compatible command line might look like this (note the plugin commands have _epn appended):
define command{
command_name check_email_delivery
command_line $USER1$/check_email_delivery_epn -p '$USER1$/check_smtp_send_epn -H $HOSTADDRESS$ --mailfrom $ARG3$ --mailto $ARG4$ -U $ARG5$ -P $ARG6$ --header "Subject: Nagios %TOKEN1%" -w $ARG1$ -c $ARG2$' -p '$USER1$/check_imap_receive_epn -H $HOSTADDRESS$ -U $ARG5$ -P $ARG6$ -s SUBJECT -s "Nagios %TOKEN1%" -w $ARG1$ -c $ARG2$' -w $ARG1$,$ARG1$ -c $ARG2$,$ARG2$
}
Usage Notes
check_email_delivery runs other plugins to create the email loop. If any of those exits with a CRITICAL status, then check_email_delivery will also exit with CRITICAL. If all return OK or WARNING, then check_email_delivery continues the check and uses threshold options to decide whether to return OK or WARNING.
As of version 0.5, any plugins can be used to create the loop by using the --plugin option. The possibilities are pretty exciting. For example, you can check the function of an email-to-ftp gateway: use check_smtp_send to send the email, and then use an ftp plugin to check that the file is accessible by ftp.
As of version 0.6, there is an --alert option that you can use in conjunction with the --plugin option. This new --alert option is useful if your delivery loop involves more than one server and you happen to only be interested in the status of just one of the servers.
How do you send attachments or other special messages? Currently there is no built-in way but you can use the --stdin option to send a prepared message. So send yourself the message you want to use for testing, then use your mail client's "view raw message" feature, copy & paste the raw message body to a text file on your nagios server. Configure check_smtp_send like this: cat saved_message.txt | check_smtp_send --stdin [other options here].
Troubleshooting
EMAIL DELIVERY UNKNOWN - imap unknown: Missing perl modules: Mail::IMAPClient
This might happen to you even if you have Mail::IMAPClient installed on your system. Check the file permissions on your Mail::IMAPClient files in @INC to make sure nagios can access them. The user who had this problem said he solved it by changing the permissions ... so it wasn't really a problem with this plugin.
error using check_smtp_send to send a mail through Gmail with ssl
Problem:
The email, at last, is sent, but the plugin returns an UNKNOW STATE to Nagios. Shell execution returns that:
./check_smtp_send -H smtp.gmail.com --mailfrom mymail@gmail.com --mailto mymail@test.com -U myuser@gmail.com -P mypassword --header "Subject: Nagios Test" -w 5 -c 120 --tls --ssl
Use of uninitialized value in pattern match (m//) at /usr/lib/perl5/site_perl/5.8.8/Net/SMTP/TLS.pm line 140, line 7.
Use of uninitialized value in numeric eq (==) at /usr/lib/perl5/site_perl/5.8.8/Net/SMTP/TLS.pm line 396, line 7.
Use of uninitialized value in concatenation (.) or string at /usr/lib/perl5/site_perl/5.8.8/Net/SMTP/TLS.pm line 397, line 7.
Use of uninitialized value in concatenation (.) or string at /usr/lib/perl5/site_perl/5.8.8/Net/SMTP/TLS.pm line 397, line 7.
An error occurred disconnecting from the mail server:
at ./check_smtp_send line 203
I've got all needed Perl modules well installed and the plugin works well through other smtp servers without ssl.
Solution:
This appears to be a malfunction of the gmail servers. Apparently once the smtp client sends the "quit" command, gmail disconnects immediately instead of sending a successful quit response (don't ask me why that's part of the protocol in the first place). The Net::SMTP::TLS module then has a problem because it's looking for this response and it's not there, which is what causes those warnings you see on the console.
On my system I fixed it by editing /usr/lib/perl5/site_perl/5.8.8/Net/SMTP/TLS.pm
Line 139: add || "" to the end of the line immediately before the semicolon. So the revised line looks like this:
my $line = $me->{sock}->getline() || "";
Line 395: add || (221,"") to the end of the line immediately before the semicolon. So the revised line looks like this:
my ($num, $txt) = $me->_response() || (221,"");
After doing that, the script runs ok.
Future Improvements
Open to suggestions... please email me at jonathan@buhacoff.net
If you would like to be notified of bug fixes and improvements, just email me at jonathan@buhacoff.net and ask to be on the mailing list.
Important! Please include the word Nagios in your subject line to help your message get through my spam filter.
License
check_email_delivery - a Nagios plugin to check SMTP and IMAP services
Copyright (C) 2005-2008 Jonathan Buhacoff
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Search for other plugins at Nagios Exchange
http://www.nagiosexchange.org
See also...
http://nagios.org
http://nagiosplug.sourceforge.net
http://search.cpan.org/dist/Nagios-Plugin/lib/Nagios/Plugin.pm
Comments (0)
You don't have permission to comment on this page.