initial import

Author: nitram2342

LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2023, Martin Schobert, Pentagrid AG
+
+All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ The views and conclusions contained in the software and documentation are those
+ of the authors and should not be interpreted as representing official policies,
+ either expressed or implied, of the project.
+
+ NON-MILITARY-USAGE CLAUSE
+ Redistribution and use in source and binary form for military use and
+ military research is not permitted. Infringement of these clauses may
+ result in publishing the source code of the utilizing applications and
+ libraries to the public. As this software is developed, tested and
+ reviewed by *international* volunteers, this clause shall not be refused
+ due to the matter of *national* security concerns.

README.rst

@@ -0,0 +1,109 @@
+Introduction
+=============
+
+``check_mail_loop.py`` is a Nagios/Icinga plugin that checks an e-mail flow from
+sending an e-mail via SMTP to retrieving it from an IMAP server.
+
+Testing mail delivery is not only a matter of SMTP server availability, but nowadays
+also a matter of mail server reputation. If your mail server's reputation is poor,
+delivered e-mails may end up in spam folders.
+
+The plugin creates an E-mail with a UUID tag in the E-mail header and tries to
+find it later via IMAP. It checks the Inbox and if necessary also the Junk mail box.
+E-mails are deleted by default in the test box.
+
+The script returns OK if the expected UUID was found (exit code 0). If the E-mail
+was not found at all, the ERROR is returned (exit code 2). If the E-mail ended
+up in the Spam box, a WARNING is returned (exit code 1).
+
+You may want to use this check script with:
+
+- `check_rbl <https://github.com/matteocorti/check_rbl>`_
+- `check_dnssec_expiry <https://github.com/mrimann/check_dnssec_expiry>`_
+- and other modules for SMTP and IMAP
+
+Installation
+=============
+
+* Install dependencies:
+
+::
+
+    apt install python3-imaplib2
+
+* Install the script `check_mail_loop.py` on your monitoring station under `/usr/local/bin/check_mail_loop.py`.
+
+* Now, define the check command. Depending on your setup, edit for example `/etc/icinga2/conf.d/commands_check_mail_loop.conf`:
+
+::
+
+    object CheckCommand "mail_loop" {
+      import "plugin-check-command"
+
+      env.SMTP_PASS = "$mail_loop_smtp_pass$"
+      env.IMAP_PASS = "$mail_loop_imap_pass$"
+
+      command = [ "/usr/local/bin/check_mail_loop.py",
+              "--mail-from", "$mail_loop_mail_from$",
+              "--mail-to", "$mail_loop_mail_to$",
+              "--smtp-host", "$mail_loop_smtp_host$",
+              "--smtp-port", "$mail_loop_smtp_port$",
+              "--smtp-user", "$mail_loop_smtp_user$",
+              "--imap-host", "$mail_loop_imap_host$",
+              "--imap-port", "$mail_loop_imap_port$",
+              "--imap-user", "$mail_loop_imap_user$",
+              "--imap-spam", "$mail_loop_imap_spam$",
+              "--imap-cleanup" ]
+    }
+
+* Set up dedicated E-mail accounts. The flag `--imap-cleanup` instructs the plugin to remove all E-mails from the IMAP account.
+
+* Add a configuration file for Icinga, for example `/etc/icinga2/conf.d/services_mail_loop.conf`:
+
+::
+
+    object Service "mail-loop-mail.example.org" {
+      import "generic-service-internet"
+      host_name = "mail.example.org"
+      check_command = "mail_loop"
+
+      vars.mail_loop_mail_from = "test-smtp@example.org"
+      vars.mail_loop_mail_to = "mytestaccount@gmail.com"
+
+      # Configuration for E-mail delivery.
+      vars.mail_loop_smtp_host = "mail.example.org"
+      vars.mail_loop_smtp_port = "465"
+      vars.mail_loop_smtp_user = "test-smtp@example.org"
+      vars.mail_loop_smtp_pass = "secret"
+
+      # IMAP configuration on the Receiving side.
+      # If you use Gmail, you need to enable IMAP with password.
+      vars.mail_loop_imap_host = "imap.gmail.com"
+      vars.mail_loop_imap_port = "993"
+      vars.mail_loop_imap_user = "mytestaccount@gmail.com"
+      vars.mail_loop_imap_pass = "secret"
+      vars.mail_loop_imap_spam = "[Gmail]/Spam"
+
+      # Be polite and do not send too frequently.
+      check_interval = 24h
+      max_check_attempts = 4
+      retry_interval = 4h
+    }
+
+
+
+* Fix permissions of your config file. Otherwise passwords may leak.
+
+::
+
+ chown root.icinga /etc/icinga2/conf.d/services_mail_loop.conf
+ chmod 640 /etc/icinga2/conf.d/services_mail_loop.conf
+
+
+Copyright and Licence
+=====================
+
+``check_mail_loop.py`` is developed by Martin Schobert <martin@pentagrid.ch> and
+published under a BSD licence with a non-military clause. Please read
+``LICENSE.txt`` for further details.
+