473 lines
18 KiB
Plaintext
Executable File
473 lines
18 KiB
Plaintext
Executable File
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
check_email_delivery - sends email and verifies delivery
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
check_email_delivery -vV
|
|
check_email_delivery --usage
|
|
check_email_delivery --help
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over
|
|
|
|
=item --warning <seconds>[,<smtp_seconds>,<imap_seconds>]
|
|
|
|
Exit with WARNING if the most recent email found is older than <seconds>. The
|
|
optional <smtp_seconds> and <imap_seconds> parameters will be passed on to the
|
|
included plugins that are used for those tasks. If they are not
|
|
given then they will not be passed on and the default for that plugin will apply.
|
|
Also known as: -w <seconds>[,<send>[,<recv>]]
|
|
|
|
When using the --plugin option, only one parameter is supported (-w <seconds>) and it will apply
|
|
to the entire process. You can specify a warning threshold specific to each plugin in the
|
|
plugin command line.
|
|
|
|
When using the --plugin option, no measuring of "most recent email" is done because we would
|
|
not know how to read this information from receive plugins. This may be addressed in future versions.
|
|
|
|
=item --critical <seconds>[,<smtp_seconds>,<imap_seconds>]
|
|
|
|
Exit with CRITICAL if the most recent email found is older than <seconds>. The
|
|
optional <smtp_seconds> and <imap_seconds> parameters will be passed on to the
|
|
included plugins that are used for those tasks. If they are not
|
|
given then they will not be passed on and the default for that plugin will apply.
|
|
Also known as: -c <seconds>[,<send>[,<recv>]]
|
|
|
|
When using the --plugin option, only one parameter is supported (-c <seconds>) and it will apply
|
|
to the entire process. You can specify a critical threshold specific to each plugin in the
|
|
plugin command line.
|
|
|
|
When using the --plugin option, no measuring of "most recent email" is done because we would
|
|
not know how to read this information from receive plugins. This may be addressed in future versions.
|
|
|
|
=item --timeout <seconds>
|
|
|
|
=item --timeout <smtp_seconds>,<imap_seconds>
|
|
|
|
=item --timeout <plugin1_seconds>,<plugin2_seconds>,...
|
|
|
|
Exit with CRITICAL if the plugins do not return a status within the specified number of seconds.
|
|
When only one parameter is used, it applies to each plugin. When multiple parameters are used
|
|
(separated by commas) they apply to plugins in the same order the plugins were specified on the
|
|
command line. When using --timeout but not the --plugin option, the first parameter is for
|
|
check_smtp_send and the second is for check_imap_receive.
|
|
|
|
=item --alert <pluginN>
|
|
|
|
Exit with WARNING or CRITICAL only if a warning or error (--warning, --critical, or --timeout)
|
|
occurs for specified plugins. If a warning or error occurs for non-specified plugins that run
|
|
BEFORE the specified plugins, the exit status will be UNKNOWN. If a warning of error occurs
|
|
for non-specified plugins that run AFTER the specified plugins, the exit status will not be
|
|
affected.
|
|
|
|
You would use this option if you are using check_email_delivery with the --plugin option and
|
|
the plugins you configure each use different servers, for example different SMTP and IMAP servers.
|
|
By default, if you do not use the --alert option, if anything goes wrong during the email delivery
|
|
check, a WARNING or CRITICAL alert will be issued. This means that if you define check_email_delivery
|
|
for the SMTP server only and the IMAP server fails, Nagios will alert you for the SMTP server which
|
|
would be misleading. If you define it for both the SMTP server and IMAP server and just one of them
|
|
fails, Nagios will alert you for both servers, which would still be misleading. If you have this
|
|
situation, you may want to use the --alert option. You define the check_email_delivery check for
|
|
both servers: for the SMTP server (first plugin) you use --alert 1, and for for the IMAP server
|
|
(second plugin) you use --alert 2. When check_email_delivery runs with --alert 1 and the SMTP
|
|
server fails, you will get the appropriate alert. If the IMAP server fails it will not affect the
|
|
status. When check_email_delivery runs with --alert 2 and the SMTP server fails, you will get the
|
|
UNKNOWN return code. If the IMAP server generates an alert you will get a WARNING or CRITICAL as
|
|
appropriate.
|
|
|
|
You can repeat this option to specify multiple plugins that should cause an alert.
|
|
Do this if you have multiple plugins on the command line but some of them involve the same server.
|
|
|
|
See also: --plugin.
|
|
Also known as: -A <pluginN>
|
|
|
|
|
|
=item --wait <seconds>[,<seconds>,...]
|
|
|
|
How long to wait between sending the message and checking that it was received. View default with
|
|
the -vV option.
|
|
|
|
When using the --plugin option, you can specify as many wait-between times as you have plugins
|
|
(minus the last plugin, because it makes no sense to wait after running the last one). For
|
|
example, if you use the --plugin option twice to specify an SMTP plugin and an IMAP plugin, and
|
|
you want to wait 5 seconds between sending and receiving, then you would specify --wait 5. A second
|
|
example, if you are using the --plugin option three times, then specifying -w 5 will wait 5 seconds
|
|
between the second and third plugins also. You can specify a different wait time
|
|
of 10 seconds between the second and third plugins, like this: -w 5,10.
|
|
|
|
=item --hostname <server>
|
|
|
|
Address or name of the SMTP and IMAP server. Examples: mail.server.com, localhost, 192.168.1.100.
|
|
Also known as: -H <server>
|
|
|
|
=item --smtp-server <server>
|
|
|
|
Address or name of the SMTP server. Examples: smtp.server.com, localhost, 192.168.1.100.
|
|
Using this option overrides the hostname option.
|
|
|
|
=item --smtp-port <number>
|
|
|
|
Service port on the SMTP server. Default is 25.
|
|
|
|
=item --smtp-username <username>
|
|
|
|
=item --smtp-password <password>
|
|
|
|
Username and password to use when connecting to the SMTP server with the TLS option.
|
|
Use these options if the SMTP account has a different username/password than the
|
|
IMAP account you are testing. These options take precendence over the --username and
|
|
the --password options.
|
|
|
|
These are shell-escaped; special characters are ok.
|
|
|
|
=item --imap-server <server>
|
|
|
|
Address or name of the IMAP server. Examples: imap.server.com, localhost, 192.168.1.100.
|
|
Using this option overrides the hostname option.
|
|
|
|
=item --imap-port <number>
|
|
|
|
Service port on the IMAP server. Default is 143. If you use SSL the default is 993.
|
|
|
|
=item --imap-username <username>
|
|
|
|
=item --imap-password <password>
|
|
|
|
Username and password to use when connecting to the IMAP server.
|
|
Use these options if the IMAP account has a different username/password than the
|
|
SMTP account you are testing. These options take precendence over the --username and
|
|
the --password options.
|
|
|
|
These are shell-escaped; special characters are ok.
|
|
|
|
=item --username <username>
|
|
|
|
=item --password <password>
|
|
|
|
Username and password to use when connecting to IMAP server.
|
|
Also known as: -U <username> -P <password>
|
|
|
|
Also used as the username and password for SMTP when the TLS option is enabled.
|
|
To specify a separate set of credentials for SMTP authentication, see the
|
|
options --smtp-username and --smtp-password.
|
|
|
|
=item --imap-check-interval <seconds>
|
|
|
|
How long to wait between polls of the imap-server for the specified mail. Default is 5 seconds.
|
|
|
|
=item --imap-retries <times>
|
|
|
|
How many times to poll the imap-server for the mail, before we give up. Default is 10.
|
|
|
|
=item --body <message>
|
|
|
|
Use this option to specify the body of the email message.
|
|
|
|
=item --header <header>
|
|
|
|
Use this option to set an arbitrary header in the message. You can use it multiple times.
|
|
|
|
=item --mailto recipient@your.net
|
|
|
|
You can send a message to multiple recipients by repeating this option or by separating
|
|
the email addresses with commas (no whitespace allowed):
|
|
|
|
$ check_email_delivery ... --mailto recipient@your.net,recipient2@your.net --mailfrom sender@your.net
|
|
|
|
This argument is shell-escaped; special characters or angle brackets around the address are ok.
|
|
|
|
=item --mailfrom sender@your.net
|
|
|
|
Use this option to set the "from" address in the email.
|
|
|
|
=item --imapssl
|
|
=item --noimapssl
|
|
|
|
Use this to enable or disable SSL for the IMAP plugin.
|
|
|
|
This argument is shell-escaped; special characters or angle brackets around the address are ok.
|
|
|
|
=item --smtptls
|
|
=item --nosmtptls
|
|
|
|
Use this to enable or disable TLS/AUTH for the SMTP plugin.
|
|
|
|
=item --libexec
|
|
|
|
Use this option to set the path of the Nagios libexec directory. The default is
|
|
/usr/local/nagios/libexec. This is where this plugin looks for the SMTP and IMAP
|
|
plugins that it depends on.
|
|
|
|
=item --plugin <command>
|
|
|
|
This is a new option introduced in version 0.5 of the check_email_delivery plugin.
|
|
It frees the plugin from depending on specific external plugins and generalizes the
|
|
work done to determine that the email loop is operational. When using the --plugin
|
|
option, the following options are ignored: libexec, imapssl, smtptls, hostname,
|
|
username, password, smtp*, imap*, mailto, mailfrom, body, header, search.
|
|
|
|
Use this option multiple times to specify the complete trip. Typically, you would use
|
|
this twice to specify plugins for SMTP and IMAP, or SMTP and POP3.
|
|
|
|
The output will be success if all the plugins return success. Each plugin should be a
|
|
standard Nagios plugin.
|
|
|
|
A random token will be automatically generated and passed to each plugin specified on
|
|
the command line by substituting the string %TOKEN1%.
|
|
|
|
Example usage:
|
|
|
|
command_name check_email_delivery
|
|
command_line check_email_delivery
|
|
--plugin "$USER1$/check_smtp_send -H $ARG1$ --mailto recipient@your.net --mailfrom sender@your.net --header 'Subject: Nagios Test %TOKEN1%.'"
|
|
--plugin "$USER1$/check_imap_receive -H $ARG1$ -U $ARG1$ -P $ARG2$ -s SUBJECT -s 'Nagios Test %TOKEN1%.'"
|
|
|
|
This technique allows for a lot of flexibility in configuring the plugins that test
|
|
each part of your email delivery loop.
|
|
|
|
See also: --token.
|
|
Also known as: -p <command>
|
|
|
|
=item --token <format>
|
|
|
|
This is a new option introduced in version 0.5 of the check_email_delivery plugin.
|
|
It can be used in conjunction with --plugin to control the tokens that are generated
|
|
and passed to the plugins, like %TOKEN1%.
|
|
|
|
Use this option multiple times to specify formats for different tokens. For example,
|
|
if you want %TOKEN1% to consist of only alphabetical characters but want %TOKEN2% to
|
|
consist of only digits, then you might use these options: --token aaaaaa --token nnnnn
|
|
|
|
Any tokens used in your plugin commands that have not been specified by --token <format>
|
|
will default to --token U-X-Y
|
|
|
|
Token formats:
|
|
a - alpha character (a-z)
|
|
n - numeric character (0-9)
|
|
c - alphanumeric character (a-z0-9)
|
|
h - hexadecimal character (0-9a-f)
|
|
U - unix time, seconds from epoch. eg 1193012441
|
|
X - a word from the pgp even list. eg aardvark
|
|
Y - a word from the pgp odd list. eg adroitness
|
|
|
|
Caution: It has been observed that some IMAP servers do not handle underscores well in the
|
|
search criteria. For best results, avoid using underscores in your tokens. Use hyphens or commas instead.
|
|
|
|
See also: --plugin.
|
|
Also known as: -T <format>
|
|
|
|
The PGP word list was obtained from http://en.wikipedia.org/wiki/PGP_word_list
|
|
|
|
=item --file <file>
|
|
|
|
Save (append) status information into the given tab-delimited file. Format used:
|
|
|
|
token start-time end-time status plugin-num output
|
|
|
|
Note: format may change in future versions and may become configurable.
|
|
|
|
This option available as of version 0.6.2.
|
|
|
|
Also known as: -F <file>
|
|
|
|
=item --hires
|
|
|
|
Use the Time::HiRes module to measure time, if available.
|
|
|
|
=item --verbose
|
|
|
|
Display additional information. Useful for troubleshooting. Use together with --version to see the default
|
|
warning and critical timeout values.
|
|
Also known as: -v
|
|
|
|
=item --version
|
|
|
|
Display plugin version and exit.
|
|
Also known as: -V
|
|
|
|
=item --help
|
|
|
|
Display this documentation and exit. Does not work in the ePN version.
|
|
Also known as: -h
|
|
|
|
=item --usage
|
|
|
|
Display a short usage instruction and exit.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
=head2 Send a message with custom headers
|
|
|
|
$ check_email_delivery -H mail.server.net --mailto recipient@your.net --mailfrom sender@your.net
|
|
--username recipient --password secret
|
|
|
|
EMAIL DELIVERY OK - 1 seconds
|
|
|
|
=head2 Set warning and critical timeouts for receive plugin only:
|
|
|
|
$ check_email_delivery -H mail.server.net --mailto recipient@your.net --mailfrom sender@your.net
|
|
--username recipient --password secret -w ,,5 -c ,,15
|
|
|
|
EMAIL DELIVERY OK - 1 seconds
|
|
|
|
=head1 EXIT CODES
|
|
|
|
Complies with the Nagios plug-in specification:
|
|
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
|
|
2 Critical The plugin detected that either the service was not running or it was above some "critical" threshold
|
|
3 Unknown Invalid command line arguments were supplied to the plugin or the plugin was unable to check the status of the given hosts/service
|
|
|
|
=head1 NAGIOS PLUGIN NOTES
|
|
|
|
Nagios plugin reference: http://nagiosplug.sourceforge.net/developer-guidelines.html
|
|
|
|
This plugin does NOT use Nagios DEFAULT_SOCKET_TIMEOUT (provided by utils.pm as $TIMEOUT) because
|
|
the path to utils.pm must be specified completely in this program and forces users to edit the source
|
|
code if their install location is different (if they realize this is the problem). You can view
|
|
the default timeout for this module by using the --verbose and --version options together. The
|
|
short form is -vV.
|
|
|
|
Other than that, it attempts to follow published guidelines for Nagios plugins.
|
|
|
|
=head1 CHANGES
|
|
|
|
Wed Oct 29 13:08:00 PST 2005
|
|
+ version 0.1
|
|
|
|
Wed Nov 9 17:16:09 PST 2005
|
|
+ updated arguments to check_smtp_send and check_imap_receive
|
|
+ added eval/alarm block to implement -c option
|
|
+ added wait option to adjust sleep time between smtp and imap calls
|
|
+ added delay-warn and delay-crit options to adjust email delivery warning thresholds
|
|
+ now using an inline PluginReport package to generate the report
|
|
+ copyright notice and GNU GPL
|
|
+ version 0.2
|
|
|
|
Thu Apr 20 14:00:00 CET 2006 (by Johan Nilsson <johann (at) axis.com>)
|
|
+ version 0.2.1
|
|
+ corrected bug in getoptions ($imap_server would never ever be set from command-line...)
|
|
+ will not make $smtp_server and $imap_server == $host if they're defined on commandline
|
|
+ added support for multiple polls of imap-server, with specified intervals
|
|
+ changed default behaviour in check_imap_server (searches for the specific id in subject and deletes mails found)
|
|
+ increased default delay_warn from 65 seconds to 95 seconds
|
|
|
|
Thu Apr 20 16:00:00 PST 2006 (by Geoff Crompton <geoff.crompton@strategicdata.com.au>)
|
|
+ fixed a bug in getoptions
|
|
+ version 0.2.2
|
|
|
|
Tue Apr 24 21:17:53 PDT 2007
|
|
+ now there is an alternate version (same but without embedded perl POD) that is compatible with the new new embedded-perl Nagios feature
|
|
+ version 0.2.3
|
|
|
|
Fri Apr 27 20:32:53 PDT 2007
|
|
+ documentation now mentions every command-line option accepted by the plugin, including abbreviations
|
|
+ changed connection error to display timeout only if timeout was the error
|
|
+ default IMAP plugin is libexec/check_imap_receive (also checking for same but with .pl extension)
|
|
+ default SMTP plugin is libexec/check_smtp_send (also checking for same but with .pl extension)
|
|
+ removed default values for SMTP port and IMAP port to allow those plugins to set the defaults; so current behavior stays the same and will continue to make sense with SSL
|
|
+ version 0.3
|
|
|
|
Thu Oct 11 10:00:00 EET 2007 (by Timo Virtaneva <timo (at) virtaneva dot com>
|
|
+ Changed the header and the search criteria so that the same email-box can be used for all smtp-servers
|
|
+ version 0.3.1
|
|
|
|
Sun Oct 21 11:01:03 PDT 2007
|
|
+ added support for TLS options to the SMTP plugin
|
|
+ version 0.4
|
|
|
|
Sun Oct 21 16:17:14 PDT 2007
|
|
+ added support for arbitrary plugins to send and receive mail (or anthing else!). see the --plugin option.
|
|
+ version 0.5
|
|
|
|
Tue Dec 4 07:36:20 PST 2007
|
|
+ added --usage option because the official nagios plugins have both --help and --usage
|
|
+ added --timeout option to match the official nagios plugins
|
|
+ shortcut option for --token is now -T to avoid clash with standard shortcut -t for --timeout
|
|
+ fixed some minor pod formatting issues for perldoc
|
|
+ version 0.5.1
|
|
|
|
Sat Dec 15 07:39:59 PST 2007
|
|
+ improved compatibility with Nagios embedded perl (ePN)
|
|
+ version 0.5.2
|
|
|
|
Thu Jan 17 20:27:36 PST 2008 (by Timo Virtaneva <timo (at) virtaneva dot com> on Thu Oct 11 10:00:00 EET 2007)
|
|
+ Changed the header and the search criteria so that the same email-box can be used for all smtp-servers
|
|
+ version 0.5.3
|
|
|
|
Mon Jan 28 22:11:02 PST 2008
|
|
+ fixed a bug, smtp-password and imap-password are now string parameters
|
|
+ added --alert option to allow selection of which plugin(s) should cause a WARNING or CRITICAL alert
|
|
+ version 0.6
|
|
|
|
Mon Feb 11 19:09:37 PST 2008
|
|
+ fixed a bug for embedded perl version, variable "%status" will not stay shared in load_modules
|
|
+ version 0.6.1
|
|
|
|
Mon May 26 10:39:19 PDT 2008
|
|
+ added --file option to allow plugin to record status information into a tab-delimited file
|
|
+ changed default token from U_X_Y to U-X-Y
|
|
+ version 0.6.2
|
|
|
|
Wed Jan 14 08:29:35 PST 2009
|
|
+ fixed a bug that the --header parameter was not being passed to the smtp plugin.
|
|
+ version 0.6.3
|
|
|
|
Mon Jun 8 15:43:48 PDT 2009
|
|
+ added performance data for use with PNP4Nagios! (thanks to Ben Ritcey for the patch)
|
|
+ version 0.6.4
|
|
|
|
Wed Sep 16 07:10:10 PDT 2009
|
|
+ added elapsed time in seconds to performance data
|
|
+ version 0.6.5
|
|
|
|
Fri Oct 8 19:48:44 PDT 2010
|
|
+ fixed uniform IMAP and SMTP username and password bug (thanks to Micle Moerenhout for pointing it out)
|
|
+ version 0.6.6
|
|
|
|
Mon Jan 3 08:24:23 PST 2011
|
|
+ added shell escaping for smtp-username, smtp-password, mailto, mailfrom, imap-username, and imap-password arguments
|
|
+ version 0.7.0
|
|
|
|
Fri May 6 08:35:09 AST 2011
|
|
+ added --hires option to enable use of Time::Hires if available
|
|
+ version 0.7.1
|
|
|
|
Sun Jun 12 17:17:06 AST 2011
|
|
+ added --imap-mailbox option to pass through to check_imap_receive --mailbox option
|
|
+ added --ssl option to conveniently enable both --smtp-tls and --imap-ssl
|
|
+ version 0.7.2
|
|
|
|
=head1 AUTHOR
|
|
|
|
Jonathan Buhacoff <jonathan@buhacoff.net>
|
|
|
|
=head1 COPYRIGHT AND LICENSE
|
|
|
|
Copyright (C) 2005-2011 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 3 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, see <http://www.gnu.org/licenses/>.
|
|
|
|
http://www.gnu.org/licenses/gpl.txt
|
|
|
|
=cut
|