introduce 'mod/notification-email', split off from global-functions

README.md

@@ -218,6 +218,7 @@ Available modules
 * [Manage VLANs on bridge ports](doc/mod/bridge-port-vlan.md)
 * [Inspect variables](doc/mod/inspectvar.md)
 * [IP address calculation](doc/mod/ipcalc.md)
+* [Send notifications via e-mail](doc/mod/notification-email.md)
 * [Send notifications via Matrix](doc/mod/notification-matrix.md)
 * [Send notifications via Telegram](doc/mod/notification-telegram.md)
 * [Download script and run it once](doc/mod/scriptrunonce.md)

doc/backup-cloud.md

@@ -36,7 +36,8 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `BackupPassword`: password to encrypt the backup with
 * `BackupRandomDelay`: delay up to amount of seconds when run from scheduler
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/backup-email.md

@@ -15,9 +15,12 @@ configuration export (`/export terse show-sensitive`) via e-mail.
 Requirements and installation
 -----------------------------
 
-Just install the script:
+Just install the script and the required module:
 
-    $ScriptInstallUpdate backup-email;
+    $ScriptInstallUpdate mod/notification-email,backup-email;
+
+Also make sure you configure
+[sending notifications via e-mail](mod/notification-email.md).
 
 Configuration
 -------------
@@ -29,8 +32,6 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `BackupPassword`: password to encrypt the backup with
 * `BackupRandomDelay`: delay up to amount of seconds when run from scheduler
 
-Also valid e-mail settings are required to send mails.
-
 Usage and invocation
 --------------------
 
@@ -47,6 +48,7 @@ See also
 
 * [Upload backup to Mikrotik cloud](backup-cloud.md)
 * [Save configuration to fallback partition](doc/backup-partition.md)
+* [Send notifications via e-mail](mod/notification-email.md)
 * [Upload backup to server](backup-upload.md)
 
 ---

doc/backup-upload.md

@@ -41,7 +41,8 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `BackupUploadUser`: username for server authentication
 * `BackupUploadPass`: password for server authentication
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/check-certificates.md

@@ -26,10 +26,6 @@ Just install the script:
 Configuration
 -------------
 
-The expiry notifications just require notification settings for e-mail,
-[matrix](mod/notification-matrix.md) and/or
-[telegram](mod/notification-telegram.md).
-
 For automatic download and renewal of certificates you need configuration
 in `global-config-overlay`, these are the parameters:
 
@@ -39,6 +35,11 @@ in `global-config-overlay`, these are the parameters:
 Certificates on the web server should be named `CN.pem` (`PEM` format) or
 `CN.p12` (`PKCS#12` format).
 
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
+[matrix](mod/notification-matrix.md) and/or
+[telegram](mod/notification-telegram.md).
+
 Usage and invocation
 --------------------
 

doc/check-health.md

@@ -56,7 +56,8 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `CheckHealthVoltageLow`: value (in volt*10) giving a hard lower limit
 * `CheckHealthVoltagePercent`: percentage value to trigger voltage jumps
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/check-lte-firmware-upgrade.md

@@ -35,7 +35,8 @@ Just install the script:
 Configuration
 -------------
 
-Notification setting are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/check-routeros-update.md

@@ -56,7 +56,8 @@ safe versions from a web server. The configuration goes to
 * `SafeUpdateUrl`: url to check for safe update, the channel (`long-term`,
 `stable` or `testing`) is appended
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/collect-wireless-mac.md

@@ -40,7 +40,8 @@ On first run a disabled access list entry acting as marker (with comment
 "`--- collected above ---`") is added. Move this entry to define where new
 entries are to be added.
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/daily-psk.md

@@ -51,7 +51,8 @@ Then add an access list entry:
 
     /interface/wireless/access-list/add comment="Daily PSK" interface=wl-daily private-pre-shared-key="ToBeChangedDaily";
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/log-forward.md

@@ -46,7 +46,8 @@ The configuration goes to `global-config-overlay`, these are the parameters:
 * `LogForwardIncludeMessage`: define message text to be forwarded (even if
   filter matches)
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/mod/notification-email.md

@@ -0,0 +1,63 @@
+Send notifications via e-mail
+=============================
+
+[◀ Go back to main README](../../README.md)
+
+> ℹ️️ **Info**: This module can not be used on its own but requires the base
+> installation. See [main README](../../README.md) for details.
+
+Description
+-----------
+
+This module adds support for sending notifications via e-mail. A queue is
+used to make sure notifications are not lost on failure but sent later.
+
+Requirements and installation
+-----------------------------
+
+Just install the module:
+
+    $ScriptInstallUpdate mod/notification-email;
+
+Also you need a valid e-mail account with smtp login credentials.
+
+Configuration
+-------------
+
+Set up your device's
+[e-mail settings](https://wiki.mikrotik.com/wiki/Manual:Tools/email).
+
+Then edit `global-config-overlay`, add `EmailGeneralTo` with a valid
+recipient address. Finally reload the configuration.
+
+### Sending to several recipients
+
+Sending notifications to several recipients is possible as well. Add
+`EmailGeneralCc` on top, which can have a single mail address or a comma
+separated list.
+
+Usage and invocation
+--------------------
+
+There's nothing special to do. Every script or function sending a notification
+will now send it to your e-mail account.
+
+But of course you can send notifications directly or use a function in your
+own scripts. Give it a try:
+
+    $SendEMail "Subject..." "Body..."
+
+Alternatively this sends a notification with all available and configured
+methods:
+
+    $SendNotification "Subject..." "Body..."
+
+See also
+--------
+
+* [Send notifications via Matrix](notification-matrix.md)
+* [Send notifications via Telegram](notification-telegram.md)
+
+---
+[◀ Go back to main README](../../README.md)  
+[▲ Go back to top](#top)

doc/mod/notification-matrix.md

@@ -103,6 +103,7 @@ methods:
 See also
 --------
 
+* [Send notifications via e-mail](notification-email.md)
 * [Send notifications via Telegram](notification-telegram.md)
 
 ---

doc/mod/notification-telegram.md

@@ -66,6 +66,7 @@ methods:
 See also
 --------
 
+* [Send notifications via e-mail](notification-email.md)
 * [Send notifications via Matrix](notification-matrix.md)
 
 ---

doc/netwatch-notify.md

@@ -88,7 +88,8 @@ powered off, but accessibility is of interest.
 
 Go and get your coffee ☕️ before sending the print job.
 
-Also notification settings are required for e-mail,
+Also notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
 [telegram](mod/notification-telegram.md).
 

doc/sms-forward.md

@@ -31,10 +31,11 @@ Just install the script:
 Configuration
 -------------
 
-Notification settings are required for e-mail,
+Notification settings are required for
+[e-mail](mod/notification-email.md),
 [matrix](mod/notification-matrix.md) and/or
-[telegram](mod/notification-telegram.md). Also you have to enable receiving
+[telegram](mod/notification-telegram.md).
-of SMS:
+Also you have to enable receiving of SMS:
 
     /tool/sms/set receive-enabled=yes;
 

global-config

@@ -15,9 +15,11 @@
 :global PrefixInZone true;
 :global ServerNameInZone false;
 
-# These addresses are used to send e-mails to. The to-address needs
+# You can send e-mail notifications. Configure the system's mail settings
-# to be filled; cc-address can be empty, one address or a comma
+# (/tool/e-mail), then install the module:
-# separated list of addresses.
+# $ScriptInstallUpdate mod/notification-email
+# The to-address needs to be filled; cc-address can be empty, one address
+# or a comma separated list of addresses.
 :global EmailGeneralTo "";
 :global EmailGeneralCc "";
 #:global EmailGeneralTo "mail@example.com";

global-config.changes

@@ -92,6 +92,7 @@
   81="Dropped script 'rotate-ntp', as the limitation does no longer exist.";
   82="Renamed the comment parameter 'hostname' to just 'name' for 'netwatch-notify'.";
   83="Introduced new setting to disable news and change notifications, dropped version from configuration.";
+  84="Support for e-mail notifications moved to a module. It is installed automatically if required.";
 };
 
 # Migration steps to be applied on script updates
@@ -106,4 +107,5 @@
   73=":global ScriptInstallUpdate; :global CharacterReplace; :foreach Old,New in={ \"cloud-backup\"=\"backup-cloud\"; \"email-backup\"=\"backup-email\"; \"upload-backup\"=\"backup-upload\" } do={ /system/script/set name=\$New [ find where name=\$Old ]; :foreach Scheduler in=[ /system/scheduler/find where on-event~\$Old ] do={ /system/scheduler/set \$Scheduler name=[ \$CharacterReplace [ get \$Scheduler name ] \$Old \$New ] on-event=[ \$CharacterReplace [ get \$Scheduler on-event ] \$Old \$New ]; }; }; \$ScriptInstallUpdate;";
   81=":global NtpPool; :if ([ :len [ /system/script/find where name=\"rotate-ntp\" ] ] > 0) do={ /system/script/remove [ find where name=\"rotate-ntp\" ]; /system/scheduler/remove [ find where name=\"rotate-ntp\" ]; /system/ntp/client/set servers=\$NtpPool; };";
   82=":global CharacterReplace; :foreach Netwatch in=[ /tool/netwatch/find where comment~\"notify\" !disabled ] do={ /tool/netwatch/set \$Netwatch comment=[ \$CharacterReplace [ get \$Netwatch comment ] \"hostname=\" \"name=\" ]; };";
+  84=":global ScriptInstallUpdate; :global EmailGeneralTo; :if ([ /tool/e-mail/get address ] != \"0.0.0.0\" && [ :len \$EmailGeneralTo ] > 0) do={ \$ScriptInstallUpdate mod/notification-email; }";
 };

global-functions

@@ -10,7 +10,7 @@
 :local 0 "global-functions";
 
 # expected configuration version
-:global ExpectedConfigVersion 83;
+:global ExpectedConfigVersion 84;
 
 # global variables not to be changed by user
 :global GlobalFunctionsReady false;
@@ -26,7 +26,6 @@
 :global DownloadPackage;
 :global EitherOr;
 :global EscapeForRegEx;
-:global FlushEmailQueue;
 :global GetMacVendor;
 :global GetRandom20CharAlNum;
 :global GetRandom20CharHex;
@@ -49,8 +48,6 @@
 :global ScriptFromTerminal;
 :global ScriptInstallUpdate;
 :global ScriptLock;
-:global SendEMail;
-:global SendEMail2;
 :global SendNotification;
 :global SendNotification2;
 :global SymbolByUnicodeName;
@@ -318,74 +315,6 @@
   :return $Return;
 }
 
-# flush e-mail queue
-:set FlushEmailQueue do={
-  :global EmailQueue;
-
-  :global EitherOr;
-  :global IsDNSResolving;
-  :global IsTimeSync;
-  :global LogPrintExit2;
-
-  :local AllDone true;
-  :local QueueLen [ :len $EmailQueue ];
-
-  :if ([ /tool/e-mail/get last-status ] = "in-progress") do={
-    $LogPrintExit2 debug $0 ("Sending mail in currently in progress, not flushing.") false;
-    :return false;
-  }
-
-  :if ([ $IsTimeSync ] = false) do={
-    $LogPrintExit2 debug $0 ("Time is not synced, not flushing.") false;
-    :return false;
-  }
-
-  :if ([ :typeof [ :toip [ /tool/e-mail/get address ] ] ] != "ip" && [ $IsDNSResolving ] = false) do={
-    $LogPrintExit2 debug $0 ("Server address is a DNS name and resolving fails, not flushing.") false;
-    :return false;
-  }
-
-  :if ([ :len [ /system/scheduler/find where name=$0 ] ] > 0 && $QueueLen = 0) do={
-    $LogPrintExit2 warning $0 ("Flushing E-Mail messages from scheduler, but queue is empty.") false;
-  }
-
-  /system/scheduler/set interval=($QueueLen . "m") [ find where name=$0 ];
-
-  :foreach Id,Message in=$EmailQueue do={
-    :if ([ :typeof $Message ] = "array" ) do={
-      :local Attach [ $EitherOr ($Message->"attach") "" ];
-      :while ([ /tool/e-mail/get last-status ] = "in-progress") do={ :delay 1s; }
-      /tool/e-mail/send to=($Message->"to") cc=($Message->"cc") subject=($Message->"subject") \
-        body=($Message->"body") file=$Attach;
-      :local Wait true;
-      :do {
-        :delay 1s;
-        :local Status [ /tool/e-mail/get last-status ];
-        :if ($Status = "succeeded") do={
-          :set ($EmailQueue->$Id);
-          :set Wait false;
-          :if (($Message->"remove-attach") = true) do={
-            :foreach File in=[ :toarray $Attach ] do={
-              /file/remove $File;
-            }
-          }
-        }
-        :if ($Status = "failed") do={
-          :set AllDone false;
-          :set Wait false;
-        }
-      } while=($Wait = true);
-    }
-  }
-
-  :if ($AllDone = true && $QueueLen = [ :len $EmailQueue ]) do={
-    /system/scheduler/remove [ find where name=$0 ];
-    :set EmailQueue;
-  } else={
-    /system/scheduler/set interval=1m [ find where name=$0 ];
-  }
-}
-
 # get MAC vendor
 :set GetMacVendor do={
   :local Mac [ :tostr $1 ];
@@ -609,46 +538,6 @@
   :set NotificationFunctions ({});
 }
 
-# send notification via e-mail - expects one array argument
-:set ($NotificationFunctions->"email") do={
-  :local Notification $1;
-
-  :global Identity;
-  :global EmailGeneralTo;
-  :global EmailGeneralToOverride;
-  :global EmailGeneralCc;
-  :global EmailGeneralCcOverride;
-  :global EmailQueue;
-
-  :global EitherOr;
-  :global IfThenElse;
-  :global QuotedPrintable;
-
-  :local To [ $EitherOr ($EmailGeneralToOverride->($Notification->"origin")) $EmailGeneralTo ];
-  :local Cc [ $EitherOr ($EmailGeneralCcOverride->($Notification->"origin")) $EmailGeneralCc ];
-
-  :local EMailSettings [ /tool/e-mail/get ];
-  :if ([ :len $To ] = 0 || ($EMailSettings->"address") = "0.0.0.0" || ($EMailSettings->"from") = "<>") do={
-    :return false;
-  }
-
-  :if ([ :typeof $EmailQueue ] = "nothing") do={
-      :set EmailQueue ({});
-  }
-  :local Signature [ /system/note/get note ];
-  :set ($EmailQueue->[ :len $EmailQueue ]) {
-    to=$To; cc=$Cc;
-    subject=[ $QuotedPrintable ("[" . $Identity . "] " . ($Notification->"subject")) ];
-    body=(($Notification->"message") . \
-      [ $IfThenElse ([ :len ($Notification->"link") ] > 0) ("\n\n" . ($Notification->"link")) "" ] . \
-      [ $IfThenElse ([ :len $Signature ] > 0) ("\n-- \n" . $Signature) "" ]); \
-    attach=($Notification->"attach"); remove-attach=($Notification->"remove-attach") };
-  :if ([ :len [ /system/scheduler/find where name="\$FlushEmailQueue" ] ] = 0) do={
-    /system/scheduler/add name="\$FlushEmailQueue" interval=1s start-time=startup \
-      on-event=(":global FlushEmailQueue; \$FlushEmailQueue;");
-  }
-}
-
 # parse key value store
 :set ParseKeyValueStore do={
   :local Source $1;
@@ -1115,22 +1004,6 @@
   :return true;
 }
 
-# send notification via e-mail - expects at least two string arguments
-:set SendEMail do={
-  :global SendEMail2;
-
-  $SendEMail2 ({ subject=$1; message=$2; link=$3 });
-}
-
-# send notification via e-mail - expects one array argument
-:set SendEMail2 do={
-  :local Notification $1;
-
-  :global NotificationFunctions;
-
-  ($NotificationFunctions->"email") ("\$NotificationFunctions->\"email\"") $Notification;
-}
-
 # send notification via NotificationFunctions - expects at least two string arguments
 :set SendNotification do={
   :global SendNotification2;

mod/notification-email

@@ -0,0 +1,133 @@
+#!rsc by RouterOS
+# RouterOS script: mod/notification-email
+# Copyright (c) 2013-2022 Christian Hesse <mail@eworm.de>
+# https://git.eworm.de/cgit/routeros-scripts/about/COPYING.md
+
+:global FlushEmailQueue;
+:global NotificationFunctions;
+:global SendEMail;
+:global SendEMail2;
+
+# flush e-mail queue
+:set FlushEmailQueue do={
+  :global EmailQueue;
+
+  :global EitherOr;
+  :global IsDNSResolving;
+  :global IsTimeSync;
+  :global LogPrintExit2;
+
+  :local AllDone true;
+  :local QueueLen [ :len $EmailQueue ];
+
+  :if ([ /tool/e-mail/get last-status ] = "in-progress") do={
+    $LogPrintExit2 debug $0 ("Sending mail in currently in progress, not flushing.") false;
+    :return false;
+  }
+
+  :if ([ $IsTimeSync ] = false) do={
+    $LogPrintExit2 debug $0 ("Time is not synced, not flushing.") false;
+    :return false;
+  }
+
+  :if ([ :typeof [ :toip [ /tool/e-mail/get address ] ] ] != "ip" && [ $IsDNSResolving ] = false) do={
+    $LogPrintExit2 debug $0 ("Server address is a DNS name and resolving fails, not flushing.") false;
+    :return false;
+  }
+
+  :if ([ :len [ /system/scheduler/find where name=$0 ] ] > 0 && $QueueLen = 0) do={
+    $LogPrintExit2 warning $0 ("Flushing E-Mail messages from scheduler, but queue is empty.") false;
+  }
+
+  /system/scheduler/set interval=($QueueLen . "m") [ find where name=$0 ];
+
+  :foreach Id,Message in=$EmailQueue do={
+    :if ([ :typeof $Message ] = "array" ) do={
+      :local Attach [ $EitherOr ($Message->"attach") "" ];
+      :while ([ /tool/e-mail/get last-status ] = "in-progress") do={ :delay 1s; }
+      /tool/e-mail/send to=($Message->"to") cc=($Message->"cc") subject=($Message->"subject") \
+        body=($Message->"body") file=$Attach;
+      :local Wait true;
+      :do {
+        :delay 1s;
+        :local Status [ /tool/e-mail/get last-status ];
+        :if ($Status = "succeeded") do={
+          :set ($EmailQueue->$Id);
+          :set Wait false;
+          :if (($Message->"remove-attach") = true) do={
+            :foreach File in=[ :toarray $Attach ] do={
+              /file/remove $File;
+            }
+          }
+        }
+        :if ($Status = "failed") do={
+          :set AllDone false;
+          :set Wait false;
+        }
+      } while=($Wait = true);
+    }
+  }
+
+  :if ($AllDone = true && $QueueLen = [ :len $EmailQueue ]) do={
+    /system/scheduler/remove [ find where name=$0 ];
+    :set EmailQueue;
+  } else={
+    /system/scheduler/set interval=1m [ find where name=$0 ];
+  }
+}
+
+# send notification via e-mail - expects one array argument
+:set ($NotificationFunctions->"email") do={
+  :local Notification $1;
+
+  :global Identity;
+  :global EmailGeneralTo;
+  :global EmailGeneralToOverride;
+  :global EmailGeneralCc;
+  :global EmailGeneralCcOverride;
+  :global EmailQueue;
+
+  :global EitherOr;
+  :global IfThenElse;
+  :global QuotedPrintable;
+
+  :local To [ $EitherOr ($EmailGeneralToOverride->($Notification->"origin")) $EmailGeneralTo ];
+  :local Cc [ $EitherOr ($EmailGeneralCcOverride->($Notification->"origin")) $EmailGeneralCc ];
+
+  :local EMailSettings [ /tool/e-mail/get ];
+  :if ([ :len $To ] = 0 || ($EMailSettings->"address") = "0.0.0.0" || ($EMailSettings->"from") = "<>") do={
+    :return false;
+  }
+
+  :if ([ :typeof $EmailQueue ] = "nothing") do={
+      :set EmailQueue ({});
+  }
+  :local Signature [ /system/note/get note ];
+  :set ($EmailQueue->[ :len $EmailQueue ]) {
+    to=$To; cc=$Cc;
+    subject=[ $QuotedPrintable ("[" . $Identity . "] " . ($Notification->"subject")) ];
+    body=(($Notification->"message") . \
+      [ $IfThenElse ([ :len ($Notification->"link") ] > 0) ("\n\n" . ($Notification->"link")) "" ] . \
+      [ $IfThenElse ([ :len $Signature ] > 0) ("\n-- \n" . $Signature) "" ]); \
+    attach=($Notification->"attach"); remove-attach=($Notification->"remove-attach") };
+  :if ([ :len [ /system/scheduler/find where name="\$FlushEmailQueue" ] ] = 0) do={
+    /system/scheduler/add name="\$FlushEmailQueue" interval=1s start-time=startup \
+      on-event=(":global FlushEmailQueue; \$FlushEmailQueue;");
+  }
+}
+
+# send notification via e-mail - expects at least two string arguments
+:set SendEMail do={
+  :global SendEMail2;
+
+  $SendEMail2 ({ subject=$1; message=$2; link=$3 });
+}
+
+# send notification via e-mail - expects one array argument
+:set SendEMail2 do={
+  :local Notification $1;
+
+  :global NotificationFunctions;
+
+  ($NotificationFunctions->"email") ("\$NotificationFunctions->\"email\"") $Notification;
+}