smtp_hello_: reformat metadata

plugins/network/smtp_hello_

@@ -1,18 +1,8 @@
 #!/bin/bash
 #
-# smtp_hello_ - munin plugin for measuring smtp hello response
 # Copyright (C) 2008 Marek Mahut <mmahut@fedoraproject.org>
 # Copyright (C) 2022 Andreas Perhab, WT-IO-IT GmbH <a.perhab@wtioit.at>
 #
-# Usage:
-#   ln -s /usr/share/munin/plugins/smtp_hello_ /etc/munin/plugins/smtp_hello_mysmtpserver.example.com
-#
-# Environment variables (optional):
-#   SMTP_PORT: port number to use for connection, default is 25
-#   SMTP_COMMAND: command to use to test the connection, default is "HELO localhost"
-#   TIMEOUT_SECONDS: seconds to take at most for the test, default is 120
-#
-#
 # 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
@@ -27,12 +17,108 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 #
-#$log$
+
-#Revision 2.0  2022/05/03 09:15:32 Andreas Perhab (ap-wtioit)
+: <<=cut
-#Improve compatiblity.
+
-#
+=head1 NAME
-#%# family=auto
+
-#%# capabilities=autoconf
+smtp_hello_ - Plugin for measuring smtp hello response time
+
+=head1 CONFIGURATION
+
+This plugin is intended to be symlinked with the host to monitor appended after the plugin name. e.g.
+   ln -s /usr/share/munin/plugins/smtp_hello_ /etc/munin/plugins/smtp_hello_mysmtpserver.example.com
+
+To use it you need to have the following requirements installed:
+
+   curl (with smtp support) or nc
+   time or bash with keyword time
+
+Only when running with curl this plugin is also able to check if the mailserver is responding properly. With nc just
+the time to connect is measured and no status reported.
+
+Parameters:
+
+=over 2
+
+    SMTP_PORTS      - Space seperated list of ports to check. For example "25 465 587" Default is "25".
+    SMTP_COMMAND    - SMTP command to use to test the connection. Default is "HELO localhost". For some mail servers it
+                      may be required to change this to e.g. "QUIT" or "HELP"
+    TIMEOUT_SECONDS - Timeout for the SMTP connection test. default is 120 (seconds)
+
+=back
+
+Example:
+
+=over 2
+
+    [smtp_hello_*]
+    env.SMTP_PORTS 25 465 587
+    env.SMTP_COMMAND HELO localhost
+    env.TIMEOUT_SECONDS 60
+
+=back
+
+Default warnings and criticals are as following:
+Emit a warning when we take more than half the configured timeout time (60s). Set to critical when we get more than 99%
+ of the timeout time (118s). Those are calculated as an integer, for timeouts with lower numbers also configure individual
+ warnings and criticals. The plugin also emits a warning when curl is not able to communicate properly with the SMTP
+ server.
+
+Different warnings and critical can be specified as following:
+
+=over 2
+
+    [smtp_hello_*]
+    # warn when any port doesn't respond within 20 seconds (note make sure to overwrite this for status)
+    env.warning :10
+    # warn when port 25 doesn't respond within 20 seconds
+    env.host_warning :20
+    # critical when port 25 doesn't respond within 60 seconds
+    env.host_critical :60
+    # any status code that is not zero should be a warning
+    env.status_warning 0:0
+    # warn when port 25 doesn't respond within 40 seconds
+    env.host_465_warning :40
+    # critical when port 465 doesn't respond within 60 seconds
+    env.host_465_critical :60
+    # any status code that is not zero should be a warning
+    env.status_465_warning 0:0
+
+=back
+
+
+ [postfix_mailqueue]
+    env.spooldir /var/spool/postfix
+
+=head1 AUTHOR
+
+Marek Mahut
+
+Copyright (C) 2008 Marek Mahut <mmahut@fedoraproject.org>
+Copyright (C) 2022 Andreas Perhab, WT-IO-IT GmbH <a.perhab@wtioit.at>
+
+=head1 LICENSE
+
+Gnu GPLv2
+
+SPDX-License-Identifier: GPL-2.0-or-later
+
+
+
+=head1 MAGIC MARKERS
+
+=begin comment
+
+These magic markers are used by munin-node-configure when installing
+munin-node.
+
+=end comment
+
+ #%# family=auto
+ #%# capabilities=autoconf
+
+=cut
 
 . "$MUNIN_LIBDIR/plugins/plugin.sh"
 
@@ -50,11 +136,11 @@ time_executable=""
 if which time >/dev/null; then
   # use time executable found in PATH
   time_executable=$(which time)
-elif [ -x /usr/bin/time ] ; then
+elif [ -x /usr/bin/time ]; then
   # use time executable found in /usr/bin
   time_executable="/usr/bin/time"
 fi
-if [ "$time_executable" != "" ] ; then
+if [ "$time_executable" != "" ]; then
   function take_the_time() {
     "$time_executable" -f "%e" "$@" 2>&1 | tail -n 1
     return "${PIPESTATUS[0]}"
@@ -75,10 +161,10 @@ elif { time echo; } >/dev/null 2>&1; then
 fi
 
 nc_executable=""
-if which nc >/dev/null ; then
+if which nc >/dev/null; then
   # use nc from PATH
   nc_executable=$(which nc)
-elif [ -x /usr/bin/nc ] ; then
+elif [ -x /usr/bin/nc ]; then
   # as fallback use /usr/bin/nc if found
   nc_executable="/usr/bin/nc"
 fi
@@ -95,8 +181,8 @@ if [ "$1" == "config" ]; then
   echo "graph_category network"
   echo "graph_args --base 1000 --lower-limit 0"
   for port in $SMTP_PORTS; do
-    if [[ $port ]] ; then
+    if [[ $port ]]; then
-      if [[ $port = "25" ]] ; then
+      if [[ $port = "25" ]]; then
         suffix=""
       else
         suffix="_$port"
@@ -109,7 +195,7 @@ if [ "$1" == "config" ]; then
       eval "export host${suffix}_critical=\${host${suffix}_critical:-:$((TIMEOUT_SECONDS * 99 / 100))}"
       print_warning "host${suffix}"
       print_critical "host${suffix}"
-      if [ "$curl_with_smtp_support" == "1" ] ; then
+      if [ "$curl_with_smtp_support" == "1" ]; then
         # if we have curl, all non-zero exit codes indicate an error
         eval "export status${suffix}_warning=\${status${suffix}_warning:-0:0}"
         echo "status$suffix.label smtp port $port check status"
@@ -119,7 +205,6 @@ if [ "$1" == "config" ]; then
     fi
   done
 
-
 elif [ "$1" == "autoconf" ]; then
 
   if [ "$take_the_time" != "" ] && [ -x "$nc_executable" ]; then
@@ -131,13 +216,13 @@ elif [ "$1" == "autoconf" ]; then
 
 else
   for port in $SMTP_PORTS; do
-    if [[ $port ]] ; then
+    if [[ $port ]]; then
-      if [[ $port = "25" ]] ; then
+      if [[ $port = "25" ]]; then
         suffix=""
       else
         suffix="_$port"
       fi
-      if [ "$curl_with_smtp_support" == "1" ] ; then
+      if [ "$curl_with_smtp_support" == "1" ]; then
         value=$(take_the_time curl --silent -X "$SMTP_COMMAND" --max-time "$TIMEOUT_SECONDS" "smtp://$host:$port/")
         status=$?
       else
@@ -150,7 +235,7 @@ else
         status=""
       fi
       echo "host$suffix.value $value"
-      if [ -n "$status" ] ; then
+      if [ -n "$status" ]; then
         echo "status$suffix.value $status"
       fi
     fi