feature: Added purge-port scipt to allow deleting of ports from the CLI. (#7528)

* Add purge-port scipt to allow deleting of ports from the CLI.

  This script allows deleting single ports by their port_id or a list
  of ports read from a file or STDIN.

  LibreNMS Port purge tool
        -p <port_id>    Purge single port by it's port-id
        -f <file>       Purge a list of ports, read port-ids from <file>, one on each line.
                        A filename of - means reading from STDIN.

Signed-off-by: Maximilian Wilhelm <max@sdn.clinic>

* Update CLI-Tools.md

doc/Support/CLI-Tools.md

@@ -0,0 +1,37 @@
+source: Support/CLI-Tools.md
+### Command line tools
+
+Here's a brief list of command line tools, some might be missing.
+If you think something is missing, feel free to ask us or send a pull request :-)
+
+### purge-ports.php
+
+This script provides CLI access to the "delete port" function of the WebUI.
+This might come in handy when trying to clean up old ports after large changes
+within the network or when hacking on the poller/discovery functions.
+
+<pre><code>
+LibreNMS Port purge tool
+-p port_id  Purge single port by it's port-id
+-f file     Purge a list of ports, read port-ids from _file_, one on each line
+            A filename of - means reading from STDIN.
+</code></pre>
+
+#### Querying port IDs from the database
+
+One simple way to obtain port IDs is by querying the SQL database.
+
+If you wanted to query all deleted ports from the database, you could to
+this with the following query:
+
+```bash
+echo 'SELECT port_id, hostname, ifDescr FROM ports, devices WHERE devices.device_id = ports.device_id AND deleted = 1' | mysql -h your_DB_server -u your_DB_user -p --skip-column-names your_DB_name
+```
+
+When you are sure that the list of ports is correct and you want to delete all of them,
+you can write the list into a file and call purge-ports.php with that file as input:
+
+```
+echo 'SELECT port_id FROM ports, devices WHERE devices.device_id = ports.device_id AND deleted = 1' | mysql -h your_DB_server -u your_DB_user -p --skip-column-names your_DB_name > ports_to_delete
+./purge-ports.php -f ports_to_delete
+```

mkdocs.yml

@@ -112,6 +112,7 @@ pages:
       - Extensions/Plugin-System.md
   - 11. Misc:
       - Security information: General/Security.md
+      - CLI Scripts: Support/CLI-Tools.md
   - hidden:
       - Alerting/Rules.md
       - Alerting/Templates.md

scripts/purge-port.php

@@ -0,0 +1,81 @@
+#!/usr/bin/env php
+<?php
+/*
+ * 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/>.
+ */
+
+/**
+ * libreNMS CLI utility to purge old ports.
+ *
+ * @author Maximilian Wilhelm <max@sdn.clinic>
+ * @copyright 2016-2017 LibreNMS, Barbarossa
+ * @license GPL
+ * @package LibreNMS
+ * @subpackage ?
+ *
+ */
+
+chdir(dirname($argv[0]));
+
+$init_modules = array();
+require realpath(__DIR__ . '/..') . '/includes/init.php';
+
+$opt = getopt('p:f:');
+
+// Single Port-id given on cmdline?
+$port_id = null;
+if ($opt['p']) {
+    $port_id = $opt['p'];
+}
+
+// File with port-ids given on cmdline?
+$port_id_file = null;
+if ($opt['f']) {
+     $port_id_file = $opt['f'];
+}
+
+if (! $port_id && ! $port_id_file || ($port_id && $port_id_file)) {
+    print $console_color->convert($config['project_name_version'].' Port purge tool
+    -p <port_id>  Purge single port by it\'s port-id
+    -f <file>     Purge a list of ports, read port-ids from <file>, one on each line.
+                  A filename of - means reading from STDIN.
+');
+}
+
+// Purge single port
+if ($port_id) {
+    delete_port($port_id);
+}
+
+// Delete multiple ports
+if ($port_id_file) {
+    $fh = null;
+    if ($port_id_file == '-') {
+        $fh = STDIN;
+    } else {
+        $fh = fopen($port_id_file, "r");
+        if (! $fh) {
+            echo "Failed to open port-id list \"" . $port_id_file . "\": \n";
+            exit(1);
+        }
+    }
+
+    while ($port_id = trim(fgets($fh))) {
+        delete_port($port_id);
+    }
+
+    if ($fh != STDIN) {
+        fclose($fh);
+    }
+}