Add a button to reset port state history (#12457)

* Add API function to reset port state

* Log the activity

* Make StyleCI Happy

* Update FAQ.md

Add FAQ explaining problem and use

doc/Support/FAQ.md

@@ -43,6 +43,7 @@ path: blob/master/doc/
 - [How do I use trend prediction in graphs](#how-do-i-use-trend-prediction-in-graphs)
 - [How do I move only the DB to another server](#move-db-to-another-server)
 - [What are the "optional requirements message" when I add SNMPv3 devices](#optional-requirements-for-snmpv3-sha2-auth)
+- [How do I clean up alerts from my switches and routers about ports being down or changing speed](#network-config-permanent-change)
 
 # Developing
 
@@ -372,6 +373,24 @@ However, ignore tag can be read in alert rules. For example on device, if `devic
 or `macros.device = 1` condition is is set and ignore alert tag is on,
 the alert rule won't match. The alert rule is ignored.
 
+## <a name="network-config-permanent-change"> How do I clean up alerts from my switches and routers about ports being down or changing speed</a>
+
+Some properties used for alerting (ending in `_prev`) are only updated when a
+change is detected, and not every time the poller runs. This means that if you
+make a permanant change to your network such as removing a device, performing a
+major firmware upgrade, or downgrading a WAN connection, you may be stuck with
+some unresolvable alerts.
+
+If a port will be permantly down, it's best practice to configure it to be
+administratively down on the device to prevent malicious access. You can then
+only run alerts on ports with `ifAdminStatus = up`. Otherwise, you'll need to
+reset the device port state history.
+
+On the device generating alerts, use the cog button to go to the edit device
+page. At the top of the _device settings_ pane is a button labelled `Reset Port
+State` - this will clear the historic state for all ports on that device,
+allowing any active alerts to clear.
+
 ## <a name="faq8"> How do I add support for a new OS?</a>
 
 Please see [Supporting a new OS](../Developing/Support-New-OS.md) if you are adding all

includes/html/forms/reset-port-state.inc.php

@@ -0,0 +1,73 @@
+<?php
+
+/**
+ * reset-port-state.inc.php
+ *
+ * LibreNMS form for reseting port state
+ *
+ * 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 <http://www.gnu.org/licenses/>.
+ *
+ * @link       http://librenms.org
+ * @copyright  2021 Adam Bishop
+ * @author     Adam Bishop <adam@omega.org.uk>
+ */
+
+use App\Models\Device;
+
+if (! Auth::user()->hasGlobalAdmin()) {
+    $response = [
+        'status'  => 'error',
+        'message' => 'Need to be admin',
+    ];
+    echo _json_encode($response);
+    exit;
+}
+
+if (isset($_POST['device_id'])) {
+    if (! is_numeric($_POST['device_id'])) {
+        $status = 'error';
+        $message = 'Invalid device id ' . $_POST['device_id'];
+    } else {
+        $device = Device::find($_POST['device_id']);
+
+        log_event('Port state history reset by ' . Auth::user()->username, $device);
+
+        try {
+            foreach ($device->ports()->get() as $port) {
+                $port->ifSpeed_prev = null;
+                $port->ifHighSpeed_prev = null;
+                $port->ifOperStatus_prev = null;
+                $port->ifAdminStatus_prev = null;
+
+                $port->save();
+            }
+            $status = 'ok';
+            $message = 'Port state cleared successfully';
+        } catch (Exception $e) {
+            $status = 'error';
+            $message = 'Clearing port state failed: $e';
+        }
+    }
+} else {
+    $status = 'Error';
+    $message = 'Undefined POST keys received';
+}
+
+$output = [
+    'status'  => $status,
+    'message' => $message,
+];
+
+header('Content-type: application/json');
+echo _json_encode($output);

includes/html/pages/device/edit/device.inc.php

@@ -97,22 +97,26 @@ $disable_notify = get_dev_attrib($device, 'disable_notify');
 
 <h3> Device Settings </h3>
 <div class="row">
-    <div class="col-md-1 col-md-offset-2">
+    <!-- Bootstrap 3 doesn't support mediaqueries for text aligns (e.g. text-md-left), which makes these buttons stagger on sm or xs screens -->
+    <div class="col-md-2 col-md-offset-2">
         <form id="delete_host" name="delete_host" method="post" action="delhost/" role="form">
             <?php echo csrf_field() ?>
             <input type="hidden" name="id" value="<?php echo $device['device_id']; ?>">
             <button type="submit" class="btn btn-danger" name="Submit"><i class="fa fa-trash"></i> Delete device</button>
         </form>
     </div>
-    <div class="col-md-1 col-md-offset-2">
+    <div class="col-md-2 text-center">
         <?php
         if (\LibreNMS\Config::get('enable_clear_discovery') == 1 && ! $device['snmp_disable']) {
             ?>
-            <button type="submit" id="rediscover" data-device_id="<?php echo $device['device_id']; ?>" class="btn btn-primary" name="rediscover"><i class="fa fa-retweet"></i> Rediscover device</button>
+            <button type="submit" id="rediscover" data-device_id="<?php echo $device['device_id']; ?>" class="btn btn-primary" name="rediscover" title="Schedule the device for immediate rediscovery by the poller"><i class="fa fa-retweet"></i> Rediscover device</button>
             <?php
         }
         ?>
     </div>
+    <div class="col-md-2 text-right">
+        <button type="submit" id="reset_port_state" data-device_id="<?php echo $device['device_id']; ?>" class="btn btn-info" name="reset_ports"          <button type="submit" id="reset_port_state" data-device_id="<?php echo $device['device_id']; ?>" class="btn btn-info" name="reset_ports" title="Reset interface speed, admin up/down, and link up/down history, clearing associated alarms"><i class="fa fa-recycle"></i> Reset Port State</button>
+    </div>
 </div>
 <br>
 <form id="edit" name="edit" method="post" action="" role="form" class="form-horizontal">
@@ -216,7 +220,7 @@ $disable_notify = get_dev_attrib($device, 'disable_notify');
     <div class="form-group">
         <label for="parent_id" class="col-sm-2 control-label">This device depends on:</label>
         <div class="col-sm-6">
-            <select multiple name="parent_id[]" id="parent_id" class="form-control">
+            <select multiple name="parent_id[]" id="parent_id" class="form-control" style="width: 100%">
                 <?php
                 $dev_parents = dbFetchColumn('SELECT device_id from devices WHERE device_id IN (SELECT dr.parent_device_id from devices as d, device_relationships as dr WHERE d.device_id = dr.child_device_id AND d.device_id = ?)', [$device['device_id']]);
                 if (! $dev_parents) {
@@ -335,6 +339,25 @@ If `devices.ignore = 0` or `macros.device = 1` condition is is set and ignore al
             }
         });
     });
+    $("#reset_port_state").click(function() {
+        var device_id = $(this).data("device_id");
+        $.ajax({
+            type: 'POST',
+            url: 'ajax_form.php',
+            data: { type: "reset-port-state", device_id: device_id },
+            dataType: "json",
+            success: function(data){
+                if(data['status'] == 'ok') {
+                    toastr.success(data['message']);
+                } else {
+                    toastr.error(data['message']);
+                }
+            },
+            error:function(){
+                toastr.error('An error occured while attempting to reset port state alarms');
+            }
+        });
+    });
     $('#hostname-edit-button').click(function(e) {
         e.preventDefault();
         disabled_state = document.getElementById('edit-hostname-input').disabled;