From e2d6a9990320d0c9c2c66a7ca69a17cc2a1ddfca Mon Sep 17 00:00:00 2001
From: f0o <f0o@librenms.org>
Date: Sat, 1 Aug 2015 08:58:43 +0000
Subject: [PATCH] Added SNMP-Scanner + Docs

---
 doc/Support/Discovery Support.md |  22 +++++-
 snmp-scan.php                    | 111 +++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+), 1 deletion(-)
 create mode 100755 snmp-scan.php

diff --git a/doc/Support/Discovery Support.md b/doc/Support/Discovery Support.md
index 0f7565b95..bcd8758f9 100644
--- a/doc/Support/Discovery Support.md	
+++ b/doc/Support/Discovery Support.md	
@@ -162,4 +162,24 @@ DB Updates
 
 RRD Updates
 
-SNMP Response
\ No newline at end of file
+SNMP Response
+
+### SNMP Scan
+
+Apart from before mentioned Auto-Discovery options LibreNMS is also able to proactively scan a network for SNMP-enabled devices using the configured version/credentials.
+
+Using the SNMP-Scanner may take long time to finish depending on the size of your network. Tests have shown that a sparsely populated /24 is scanned within 2 Minutes whereas a sparsely populated /16 will take about 11 Hours.
+
+If possible, devide your network into smaller subnet segments and scan these subnets instead. You can use an utility like the GNU Screen or tmux to avoid aborting the scan when logging out of your Shell. You can run several instances of the SNMP-Scanner simultaneously.
+
+To run the SNMP-Scanner you need to execute the `snmp-scan.php` from within your LibreNMS installation directory.
+
+Here the script's help-page as reference:
+```text
+Usage: ./snmp-scan.php -r <CIDR_Range> [-d] [-l] [-h]
+  -r CIDR_Range     CIDR noted IP-Range to scan
+                    Example: 192.168.0.0/24
+  -d                Enable Debug
+  -l                Show Legend
+  -h                Print this text                            
+```
diff --git a/snmp-scan.php b/snmp-scan.php
new file mode 100755
index 000000000..df582d7b1
--- /dev/null
+++ b/snmp-scan.php
@@ -0,0 +1,111 @@
+#!/usr/bin/env php
+<?php
+/*
+ * Copyright (C) 2015 Daniel Preussker <f0o@librenms.org>
+ * 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/>.
+ */
+
+/**
+ * SNMP Scan
+ * @author f0o <f0o@librenms.org>
+ * @copyright 2015 f0o, LibreNMS
+ * @license GPL
+ * @package LibreNMS
+ * @subpackage Discovery
+ */
+
+$ts = microtime(true);
+
+chdir(dirname($argv[0]));
+
+require 'includes/defaults.inc.php';
+require 'config.php';
+require 'includes/definitions.inc.php';
+
+if ($config['autodiscovery']['snmpscan'] == false) {
+    echo 'SNMP-Scan disabled.'.PHP_EOL;
+    exit(2);
+}
+
+require 'includes/functions.php';
+require 'includes/discovery/functions.inc.php';
+
+$opts  = getopt('r:d::l::h::');
+$stats = array('count'=> 0, 'known'=>0, 'added'=>0, 'failed'=>0);
+$start = false;
+$debug = false;
+$quiet = 1;
+$net   = false;
+
+if (isset($opts['h']) || empty($opts)) {
+    echo 'Usage: '.$argv[0].' -r <CIDR_Range> [-d] [-l] [-h]'.PHP_EOL;
+    echo '  -r CIDR_Range     CIDR noted IP-Range to scan'.PHP_EOL;
+    echo '                    Example: 192.168.0.0/24'.PHP_EOL;
+    echo '  -d                Enable Debug'.PHP_EOL;
+    echo '  -l                Show Legend'.PHP_EOL;
+    echo '  -h                Print this text'.PHP_EOL;
+    exit(0);
+}
+if (isset($opts['d'])) {
+    $debug = true;
+    $quiet = 0;
+}
+if (isset($opts['r'])) {
+    $net   = Net_IPv4::parseAddress($opts['r']);
+    $start = ip2long($net->network);
+}
+
+if ($start !== false) {
+    if (isset($opts['l'])) {
+        echo 'Legend:  * = Known Device;  . = Unpingable Device;  + = Added Device;  - = Failed To Add Device;'.PHP_EOL;
+    }
+    echo 'Range: '.$net->network.'/'.$net->bitmask.PHP_EOL;
+    $config['snmp']['timeout'] = 1;
+    $config['snmp']['retries'] = 0;
+    $config['fping_options']['retries']  = 0;
+    $end   = ip2long($net->broadcast)-1;
+    while ($start++ < $end) {
+        $stats['count']++;
+        $device_id = false;
+        $host      = long2ip($start);
+        $test      = isPingable($host);
+        if ($test['result'] === false) {
+            echo '.';
+            continue;
+        }
+        foreach (array('udp','tcp') as $transport) {
+            if (ip_exists($host)) {
+                $stats['known']++;
+                echo '*';
+                continue;
+            }
+            if ($device_id !== false && $device_id > 0) {
+                $stats['added']++;
+                echo '+';
+            } else if ($device_id === 0) {
+                $stats['failed']++;
+                echo '-';
+                break;
+            }
+            $device_id = addHost(gethostbyaddr($host), '', $config['snmp']['port'], $transport, $quiet, $config['distributed_poller_group'], 0);
+        }
+    }
+    echo PHP_EOL;
+    echo 'Scanned '.$stats['count'].' IPs, Already know '.$stats['known'].' Devices, Added '.$stats['added'].' Devices, Failed to add '.$stats['failed'].' Devices.'.PHP_EOL;
+    echo 'Runtime: '.(microtime(true)-$ts).' secs'.PHP_EOL;
+    exit(0);
+} else {
+    echo 'Could not interpret supplied CIDR noted IP-Range: '.$opts['r'].PHP_EOL;
+    exit(2);
+}