Add Scheduled Maintenance behaviour to control alerts (librenms#17929)

* Fix typo

* Apply code cleanup

* Add behaviors to scheduled maintenance

A scheduled maintenance means that no alert rule checks are run for
affected devices. Therefore any new issue would go by unnoticed.

This behavior will be called "Skip alert rule checks". Two more
behaviors are introduced:

- "No alert transporting": Alert rule checks are run as usual, but no
  alert transport (e. g. e-mail) happens
- "Information only": Choose this if you want to see the screwdriver
  right of the device name at the detail page. Alerting and alert
  transport will continue to work as before.

* Add documentation for scheduled maintenances

* Ensure that device type icon is displayed below device state

Otherwise the icon "overshadows" the text if the latter one is to long.

* Improve warning in config definition file

* Update Scheduled-Maintenances.md

* Update api_functions.inc.php

* Update schedule-maintenance.inc.php

* Update config_definitions.json

* Update alert_schedule.inc.php

* Update device_maintenance.inc.php

* Update settings.php

* Update settings.php

* Update settings.php

* Update settings.php

---------

Co-authored-by: Neil Lathwood <[email protected]>

Author: mwobst

LibreNMS/Alert/AlertRules.php

@@ -38,6 +38,7 @@
 use Illuminate\Support\Facades\Log;
 use LibreNMS\Alerting\QueryBuilderParser;
 use LibreNMS\Enum\AlertState;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
 use LibreNMS\Enum\Severity;
 use PDO;
 use PDOException;
@@ -47,7 +48,7 @@ class AlertRules
     public function runRules($device_id)
     {
         //Check to see if under maintenance
-        if (AlertUtil::isMaintenance($device_id) > 0) {
+        if (AlertUtil::isMaintenance($device_id, MaintenanceAlertBehavior::SKIP->value) > 0) {
             echo "Under Maintenance, skipping alert rules check.\r\n";
 
             return false;

LibreNMS/Alert/AlertUtil.php

@@ -207,9 +207,9 @@ public static function getRules($device_id)
      * @param  int  $device_id  Device-ID
      * @return bool
      */
-    public static function isMaintenance($device_id)
+    public static function isMaintenance($device_id, $behavior)
     {
-        return DeviceCache::get($device_id)->isUnderMaintenance();
+        return DeviceCache::get($device_id)->isUnderMaintenance($behavior);
     }
 
     /**

LibreNMS/Alert/RunAlerts.php

@@ -38,6 +38,7 @@
 use App\Models\Eventlog;
 use LibreNMS\Alerting\QueryBuilderParser;
 use LibreNMS\Enum\AlertState;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
 use LibreNMS\Enum\Severity;
 use LibreNMS\Exceptions\AlertTransportDeliveryException;
 use LibreNMS\Polling\ConnectivityHelper;
@@ -548,8 +549,23 @@ public function runAlerts()
                 $noacc = false;
             }
 
-            if (AlertUtil::isMaintenance($alert['device_id'])) {
+            $disable_alert_transport = AlertUtil::isMaintenance(
+                $alert['device_id'],
+                MaintenanceAlertBehavior::MUTE->value
+            );
+            $skip_alert_rule_checks = AlertUtil::isMaintenance(
+                $alert['device_id'],
+                MaintenanceAlertBehavior::SKIP->value
+            );
+
+            // Do not send alert notifications for these types of scheduled maintenance
+            if ($disable_alert_transport || $skip_alert_rule_checks) {
                 $noiss = true;
+            }
+
+            // If alert rule checks are to be skipped, ensure that this alert is
+            // not to be handled again by this method again (by changing open to 0 later)
+            if ($skip_alert_rule_checks) {
                 $noacc = true;
             }
 

LibreNMS/Enum/MaintenanceAlertBehavior.php

@@ -0,0 +1,56 @@
+<?php
+
+/*
+ * MaintenanceAlertBehavior.php
+ *
+ * -Description-
+ *
+ * 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 <https://www.gnu.org/licenses/>.
+ *
+ * @package    LibreNMS
+ * @link       https://www.librenms.org
+ */
+
+namespace LibreNMS\Enum;
+
+enum MaintenanceAlertBehavior: int
+{
+    case ANY = 0;
+    case SKIP = 1;
+    case MUTE = 2;
+    case RUN = 3;
+
+    public static function is_valid_option($value)
+    {
+        $valid_options = [
+            self::SKIP->value,
+            self::MUTE->value,
+            self::RUN->value,
+        ];
+
+        return in_array((int) $value, $valid_options);
+    }
+
+    public static function get_value_or_fallback($value, $fallback)
+    {
+        // the fallback value needs to be validated first to avoid config nonsense
+        $valid_fallback = self::is_valid_option($fallback)
+            ? $fallback
+            : self::SKIP->value;
+
+        return self::is_valid_option($value)
+            ? (int) $value
+            : (int) $valid_fallback;
+    }
+}

LibreNMS/Polling/ConnectivityHelper.php

@@ -32,6 +32,7 @@
 use App\Models\Eventlog;
 use LibreNMS\Data\Source\Fping;
 use LibreNMS\Data\Source\FpingResponse;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
 use LibreNMS\Enum\Severity;
 use SnmpQuery;
 use Symfony\Component\Process\Process;
@@ -171,7 +172,10 @@ public function ipFamily(): string
 
     private function updateAvailability(bool $previous, bool $status): void
     {
-        if (LibrenmsConfig::get('graphing.availability_consider_maintenance') && $this->device->isUnderMaintenance()) {
+        if (
+            LibrenmsConfig::get('graphing.availability_consider_maintenance')
+            && $this->device->isUnderMaintenance(MaintenanceAlertBehavior::SKIP->value)
+        ) {
             return;
         }
 

app/Http/Controllers/DeviceController.php

@@ -12,6 +12,7 @@
 use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Blade;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
 use LibreNMS\Interfaces\UI\DeviceTab;
 use LibreNMS\Util\Debug;
 use LibreNMS\Util\Graph;
@@ -94,6 +95,9 @@ public function index(Request $request, $device, $current_tab = 'overview', $var
         $data = $tab_controller->data($device, $request);
         $page_links = $data['page_links'] ?? [];
 
+        // Pass 'any' behaviour for scheduled behaviors
+        $maintenance_any_behaviour = MaintenanceAlertBehavior::ANY->value;
+
         // Device Link Menu, select the primary link
         $device_links = $this->deviceLinkMenu($device, $current_tab);
         $primary_device_link_name = LibrenmsConfig::get('html.device.primary_link', 'edit');

app/Http/Controllers/Table/AlertScheduleController.php

@@ -29,6 +29,7 @@
 use App\Models\AlertSchedule;
 use Carbon\Carbon;
 use Illuminate\Support\Facades\DB;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
 
 class AlertScheduleController extends TableController
 {
@@ -56,6 +57,7 @@ protected function sortFields($request)
             'start' => 'start',
             'end' => 'end',
             'status' => DB::raw("end < '" . Carbon::now('UTC') . "'"), // only partition lapsed
+            'behavior' => 'behavior',
         ];
     }
 
@@ -65,9 +67,26 @@ protected function sortFields($request)
      */
     public function formatItem($schedule)
     {
+        $behavior_lang_keypart = '';
+
+        if ($schedule->behavior == MaintenanceAlertBehavior::SKIP->value) {
+            $behavior_lang_keypart = 'skip_alerts';
+        } elseif ($schedule->behavior == MaintenanceAlertBehavior::MUTE->value) {
+            $behavior_lang_keypart = 'mute_alerts';
+        } elseif ($schedule->behavior == MaintenanceAlertBehavior::RUN->value) {
+            $behavior_lang_keypart = 'run_alerts';
+        }
+
+        if (! empty($behavior_lang_keypart)) {
+            $behavior_str = __('maintenance.behavior.options.' . $behavior_lang_keypart);
+        } else {
+            $behavior_str = '';
+        }
+
         return [
             'title' => htmlentities($schedule->title),
             'notes' => htmlentities($schedule->notes),
+            'behavior' => $behavior_str,
             'id' => $schedule->schedule_id,
             'start' => $schedule->recurring ? '' : $schedule->start->toDateTimeString('minutes'),
             'end' => $schedule->recurring ? '' : $schedule->end->toDateTimeString('minutes'),

app/Http/Controllers/Table/DeviceController.php

@@ -33,6 +33,7 @@
 use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Blade;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
 use LibreNMS\Util\Rewrite;
 use LibreNMS\Util\Time;
 use LibreNMS\Util\Url;
@@ -154,7 +155,7 @@ public function formatItem($device)
         return [
             'extra' => $this->getLabel($device),
             'status' => $status,
-            'maintenance' => $device->isUnderMaintenance(),
+            'maintenance' => $device->isUnderMaintenance(MaintenanceAlertBehavior::ANY->value),
             'icon' => '<img src="' . asset($device->icon) . '" title="' . pathinfo($device->icon, PATHINFO_FILENAME) . '">',
             'hostname' => $this->getHostname($device, $status),
             'metrics' => $this->getMetrics($device),

app/Models/Device.php

@@ -17,6 +17,7 @@
 use Illuminate\Database\Query\JoinClause;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Str;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
 use LibreNMS\Exceptions\InvalidIpException;
 use LibreNMS\Util\IP;
 use LibreNMS\Util\IPv4;
@@ -240,7 +241,7 @@ public function name(): string
         return '';
     }
 
-    public function isUnderMaintenance()
+    public function isUnderMaintenance($behavior = MaintenanceAlertBehavior::SKIP->value)
     {
         if (! $this->device_id) {
             return false;
@@ -265,6 +266,10 @@ public function isUnderMaintenance()
                 }
             });
 
+        if ($behavior != MaintenanceAlertBehavior::ANY->value) {
+            $query = $query->where('behavior', $behavior);
+        }
+
         return $query->exists();
     }
 

database/migrations/2025_06_19_165621_add_behavior_to_alert_schedule_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use LibreNMS\Enum\MaintenanceAlertBehavior;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('alert_schedule', function (Blueprint $table) {
+            $table->integer('behavior')->default(
+                MaintenanceAlertBehavior::SKIP->value
+            );
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('alert_schedule', function (Blueprint $table) {
+            $table->dropColumn('behavior');
+        });
+    }
+};