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

eworm-de · eworm-de · commit eccc187014da · 2022-09-25T22:10:05.000+02:00
diff --git a/README.md b/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)
diff --git a/doc/backup-cloud.md b/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).
 
diff --git a/doc/backup-email.md b/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)
 
 ---
diff --git a/doc/backup-upload.md b/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).
 
diff --git a/doc/check-certificates.md b/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
 --------------------
 
diff --git a/doc/check-health.md b/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).
 
diff --git a/doc/check-lte-firmware-upgrade.md b/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).
 
diff --git a/doc/check-routeros-update.md b/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).
 
diff --git a/doc/collect-wireless-mac.md b/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).
 
diff --git a/doc/daily-psk.md b/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).
 
diff --git a/doc/log-forward.md b/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).
 
diff --git a/doc/mod/notification-email.md b/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)
diff --git a/doc/mod/notification-matrix.md b/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)
 
 ---
diff --git a/doc/mod/notification-telegram.md b/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)
 
 ---
diff --git a/doc/netwatch-notify.md b/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).
 
diff --git a/doc/sms-forward.md b/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
-of SMS:
+[telegram](mod/notification-telegram.md).
+Also you have to enable receiving of SMS:
 
     /tool/sms/set receive-enabled=yes;
 
diff --git a/global-config b/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
-# to be filled; cc-address can be empty, one address or a comma
-# separated list of addresses.
+# You can send e-mail notifications. Configure the system's mail settings
+# (/tool/e-mail), then install the module:
+# $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";
diff --git a/global-config.changes b/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; }";
 };
diff --git a/global-functions b/global-functions
diff --git a/mod/notification-email b/mod/notification-email
