From 333c6bab2aa6fb28801768efb6db57acf98a1a6a Mon Sep 17 00:00:00 2001 From: laf Date: Wed, 3 Aug 2016 21:45:54 +0100 Subject: [PATCH 1/2] Updated auto discovery docs and pointed users to them on install --- doc/Extensions/Auto-Discovery.md | 62 ++++++++++++++----- .../Installation-CentOS-7-Apache.md | 1 + .../Installation-CentOS-7-Nginx.md | 1 + .../Installation-Ubuntu-1604-Apache.md | 1 + .../Installation-Ubuntu-1604-Nginx.md | 1 + 5 files changed, 49 insertions(+), 17 deletions(-) diff --git a/doc/Extensions/Auto-Discovery.md b/doc/Extensions/Auto-Discovery.md index 8e3342452c..101ae8ad49 100644 --- a/doc/Extensions/Auto-Discovery.md +++ b/doc/Extensions/Auto-Discovery.md @@ -1,10 +1,55 @@ # Auto discovery support +### Getting started with auto discovery. + LibreNMS provides the ability to automatically add devices on your network, we can do this with via a few methods which will be explained below and also indicate if they are enabled by default. All discovery methods run when discovery.php runs (every 6 hours by default and within 5 minutes for new devices). +The first thing to do though is add the required configuration options to `config.php`. + +#### SNMP Details + +To add devices automatically we need to know your snmp details, examples of SNMP v1, v2c and v3 are below: + +```php +// v1 or v2c +$config['snmp']['community'][] = "my_custom_community"; +$config['snmp']['community'][] = "another_community"; + +// v3 +$config['snmp']['v3'][0]['authlevel'] = 'AuthPriv'; +$config['snmp']['v3'][0]['authname'] = 'my_username'; +$config['snmp']['v3'][0]['authpass'] = 'my_password'; +$config['snmp']['v3'][0]['authalgo'] = 'MD5'; +$config['snmp']['v3'][0]['cryptopass'] = 'my_crypto'; +$config['snmp']['v3'][0]['cryptoalgo'] = 'AES'; +``` + +These details will be attempted when adding devices, you can specify any mixture of these. + +#### Your networks + +To add devices, we need to know what are your subnets so we don't go blindly attempting to add devices not +under your control. + +```php +$config['nets'][] = '192.168.0.0/24'; +$config['nets'][] = '172.2.4.0/22'; +``` + +#### Exclusions + +If you have added a network as above but a single device exists within it that you can't auto +add, then you can exclude this with the following: + +```php +$config['autodiscovery']['nets-exclude'][] = '192.168.0.1/32'; +``` + +If you want to enable / disable certain auto-discovery modules then see the rest of this doc for further info. + ### Discovery methods #### ARP @@ -31,23 +76,6 @@ Enabled by default. This module is invoked from bgp-peers discovery module. -### Including / Excluding subnets to scan - -By default the following config is in place to exclude loopback, multicast, etc ranges. You can expand this out by adding more -ranges to config.php - -```php -$config['autodiscovery']['nets-exclude'][] = '0.0.0.0/8'; -$config['autodiscovery']['nets-exclude'][] = '127.0.0.0/8'; -$config['autodiscovery']['nets-exclude'][] = '169.254.0.0/16'; -$config['autodiscovery']['nets-exclude'][] = '224.0.0.0/4'; -$config['autodiscovery']['nets-exclude'][] = '240.0.0.0/4'; -``` - -You will need to specify your own subnets that you would like to scan for which can be done with: - -`$config['nets'][] = '8.8.8.0/24';` - #### Discovering devices by IP By default we don't add devices by IP address, we look for a reverse dns name to be found and add with that. If this fails diff --git a/doc/Installation/Installation-CentOS-7-Apache.md b/doc/Installation/Installation-CentOS-7-Apache.md index a198c48af3..9b08cd898f 100644 --- a/doc/Installation/Installation-CentOS-7-Apache.md +++ b/doc/Installation/Installation-CentOS-7-Apache.md @@ -160,6 +160,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read of a few o - (Performance tuning)[http://docs.librenms.org/Support/Performance] - (Alerting)[http://docs.librenms.org/Extensions/Alerting/] - (Device Groups)[http://docs.librenms.org/Extensions/Device-Groups/] + - (Auto discovery)[http://docs.librenms.org/Extensions/Auto-Discovery/] #### Closing diff --git a/doc/Installation/Installation-CentOS-7-Nginx.md b/doc/Installation/Installation-CentOS-7-Nginx.md index c49ff6204b..ebf4cf1e62 100644 --- a/doc/Installation/Installation-CentOS-7-Nginx.md +++ b/doc/Installation/Installation-CentOS-7-Nginx.md @@ -171,6 +171,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read of a few o - (Performance tuning)[http://docs.librenms.org/Support/Performance] - (Alerting)[http://docs.librenms.org/Extensions/Alerting/] - (Device Groups)[http://docs.librenms.org/Extensions/Device-Groups/] + - (Auto discovery)[http://docs.librenms.org/Extensions/Auto-Discovery/] #### Closing diff --git a/doc/Installation/Installation-Ubuntu-1604-Apache.md b/doc/Installation/Installation-Ubuntu-1604-Apache.md index 6165f2db48..18e9962ce7 100644 --- a/doc/Installation/Installation-Ubuntu-1604-Apache.md +++ b/doc/Installation/Installation-Ubuntu-1604-Apache.md @@ -142,6 +142,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read of a few o - (Performance tuning)[http://docs.librenms.org/Support/Performance] - (Alerting)[http://docs.librenms.org/Extensions/Alerting/] - (Device Groups)[http://docs.librenms.org/Extensions/Device-Groups/] + - (Auto discovery)[http://docs.librenms.org/Extensions/Auto-Discovery/] #### Closing diff --git a/doc/Installation/Installation-Ubuntu-1604-Nginx.md b/doc/Installation/Installation-Ubuntu-1604-Nginx.md index b665fcfcc5..95549343d5 100644 --- a/doc/Installation/Installation-Ubuntu-1604-Nginx.md +++ b/doc/Installation/Installation-Ubuntu-1604-Nginx.md @@ -145,6 +145,7 @@ Now that you've installed LibreNMS, we'd suggest that you have a read of a few o - (Performance tuning)[http://docs.librenms.org/Support/Performance] - (Alerting)[http://docs.librenms.org/Extensions/Alerting/] - (Device Groups)[http://docs.librenms.org/Extensions/Device-Groups/] + - (Auto discovery)[http://docs.librenms.org/Extensions/Auto-Discovery/] #### Closing From 4116b2af90b25a3b10ce7638cf7801bd40e1cdca Mon Sep 17 00:00:00 2001 From: laf Date: Wed, 3 Aug 2016 22:01:05 +0100 Subject: [PATCH 2/2] Added more clarification + snmp-scan usage --- doc/Extensions/Auto-Discovery.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/Extensions/Auto-Discovery.md b/doc/Extensions/Auto-Discovery.md index 101ae8ad49..9d4a3565f7 100644 --- a/doc/Extensions/Auto-Discovery.md +++ b/doc/Extensions/Auto-Discovery.md @@ -7,6 +7,8 @@ a few methods which will be explained below and also indicate if they are enable All discovery methods run when discovery.php runs (every 6 hours by default and within 5 minutes for new devices). +> Please note that you need at least ONE device added before auto-discovery will work. + The first thing to do though is add the required configuration options to `config.php`. #### SNMP Details @@ -76,6 +78,16 @@ Enabled by default. This module is invoked from bgp-peers discovery module. +#### SNMP Scan +This isn't actually an auto- mechanism but manually invoked. + +It's designed to scan through all of the subnets in your config or what you have manually specified +to automatically add devices. An example of it's usage is: + +```bash +./snmp-scan.php r 192.168.0.0/24 +``` + #### Discovering devices by IP By default we don't add devices by IP address, we look for a reverse dns name to be found and add with that. If this fails