Cacti (home)ForumsDocumentation

dpdiscover

type:
userplugin
userplugin:
dpdiscover
author:
ericdives
description:
Device discovery via LLDP, CDP, FDP
version:
1.45
pia:
3.1 tested
cacti:
0.8.8b
homepage:
http://runningoffatthemouth.com/?p=1067
date:
2013-11-22
plugins:
discovery,
discover
license:
GPLv2

Download

This plugin can be download here: http://runningoffatthemouth.com/dpdiscover-latest.tgz

You can clone the repository using git: https://github.com/botfodder/dpdiscover.git However, if I'm in the middle of working on the code when you do so, you could end up with a grossly non-functioning plugin.

Purpose

Heavily based on the original Discovery plugin, this plugin sweeps existing devices for (any combination of) LLDP, CDP, or FDP information via SNMP; uses that information to look up the IP (failing v4, a v6 address is attempted), and then attempts to add the device, picking a Host Template based off of the SNMP sysDescr.

Features

Existing systems matching a user configurable filter are not scanned or added. 'Parent' (a known device reporting the existence of a new device) SNMP information can be used to probe the new 'child' (and that too can be filtered, if desired).

When adding new devices, the plugin can be configured to use:

  • Either the IP address (default) or the FQDN as the “hostname” of the device
  • Either the “short” name (default) or the FQDN as the “description” of the device

As part of a multi-Cacti install, the plugin was coded with the desire to avoid having it add a device that might be the responsibility of a different Cacti install.

The 0.2 release includes:

  • Cleanup of the “discover” tab report.
  • Additional email report testing, and also the addition of “discovered with IP but no matching DPDiscover Template” information.
  • Name standardization; at various places “dpdiscover” and “dpdiscovery” were used interchangeably. There should hopefully be no errant “y”s any more.
  • Alas, the directory name change will cause a few issues but I did make an attempt for it to retain at least the settings written to Cacti's “settings” table, and rename them as appropriate. See the “Upgrade” instructions below.

Other features added over time:

  • FDP options.
  • IP or Name change detection and correction (and the option to turn this off).
  • IPv6 either via IP or Hostname.

Prerequisites

PHP 5.2.0 (or earlier with the “filter” PECL module installed). If you are running CentOS 5.x, I suggest you look at uninstalling the “php” packages and replace them with the “php53” ones.

Any equipment you wish to have automatically added to Cacti must be running SNMP, and have a valid DNS (A or AAAA) record available. It of course also must participate in a link layer discovery protocol such as LLDP or CDP (and eventually, FDP).

Installation

Download, gunzip, de-tar and place the resulting directory into the “plugins” directory. Tell Cacti to “Install” and “Activate” the plugin. Visit the “MISC” tab in “Settings” to configure as desired.

To upgrade:

  1. Overwrite existing files in the plugin directory

That's it - the plugin should manage everything else. This should work for going from all versions to the current.

Usage

Under Cacti's “Settings” and “Misc”, there should be a configuration section for DPDiscover. Configure a start time and interval, as well as other options.

Also, in the left menu, there should be a “DPDiscover Templates”. Configure entries so that discovered equipment is given the proper Host Template. Hosts that do not match any DPDiscover Template will not be added. Scanning will exit and log an error if there are no templates detected.

At least one “known host” that participates with other hosts in a discovery protocol is required (in other words, manually entered into Cacti) before DPDiscover will have a chance to work properly.

Additional Help?

If you need additional help, please go to either the forum post for this plugin or the developer's blog post for the plugin.

Possible Bugs?

For 1.45:

  • Timing is a thing I can get anal about. The nature of Cacti, crontabs, and polling would lead to “drift”. The development site has multiple Cacti installs, all polling at 1 minute intervals, and DPDiscover would run daily, originally scheduled for 8:00am. Drift would cause subsequent runs on a given server to start later and later, as the “start” time recorded in the database wouldn’t be “exactly” at 8:00:00 (to the second). This would cause (little by little) the discovery to be pushed to later and later polls. The solution I settled on is to “fudge” the start time by recording it not as the “actual” start time, but the start time pushed back to the minute (exact – 00 seconds) of the “base start time” (IE, with 8:00am as our start time, the time recorded in the database would be whatever hour of the day the job actually started, but with 00 minutes and 00 seconds before converting to the time int that is stored in the database). So, if you have your jobs running every 4 hours, and a base start time of 8:00am, the jobs should record start times of 8:00:00am, 12:00:00pm, 4:00:00pm, etc. and should start somewhere close to the appropriate future (whenever polling is triggered, after the next appropriate start time – which, for a 5 minute polling interval, could be something like 8:04:03 depending on how long everything takes to run).

For 1.44:

  • findhosts.php will stop running if it can't pull the existing hosts or cannot find an “System Description/Host Template” matchings (DPDiscover Templates). Errors will be logged via Cacti's logging system.

For 1.43:

  • 1.42 (not released here - only on GitHub) introduced timing adjustments; prior, the start of the job might drift depending on how long the discovery would take to run.
  • 1.43 introduced adjustments for “disabled” hosts. They aren't probed in any way and are only read in during the discovery process to avoid attempting to add duplicates.
  • This version and all prior didn't do sufficient sanity checking before allowing the check to run fully.

For 1.41:

  • Like all previous versions, I've never gotten around to using the ADD function on the report page. This version added the checkbox in settings to turn off name correction.

For 1.40:

  • Waiting for bug reports, so I don't know of anything … yet.

For 1.30:

  • You tell me.
  • Please be aware that any device that responds to SNMP v1 only will not report an accurate sysUptime past 228 days.
  • A suspected interoperability bug with Autom8 doesn't exist. The bug only exists if you're using a database type of “mysqli” with Autom8.

For 1.26:

  • 1.25 used a better IP update code, but somewhere along the line the ability to activate or deactivate FDP disappeared from the git repo (discovered this while installing another Cacti server). Back now.

For 1.2:

  • Code was added to detect and correct IP changes (if the new IP meets proper requirements and actually responds to an SNMP probe). However, this code could be a little buggy. Please let me know if you run into issues with it (I *think* I got everything figured out there, but you never know).
  • There's a new setting to activate or deactivate this option, and it defaults to 'on', so you'll want to check the setting after upgrading.

For 1.1:

  • I still haven't tested (and honestly don't intend to) the “FQDN for Hostname” and IPv6 possibility.
  • There's a new configuration option for removing “excluded” hosts from the email report; they will still show up in the web report.
  • While the upgrade process looks to make sense and would appear to work fine for all versions after 0.1, upgrading to 1.1 from 0.1 … well, I haven't tested it.

For 1.0:

  • If you're using FQDN for “Hostname” (instead of the IP), code exists to deal with adding or properly detecting the “udp6:” prefix. It has not been tested at all, so you're on your own. Let me know if it bugs somewhere along the line for you (or, you know, just use the IP as the hostname and save Cacti the effort of having to ask DNS for it).
  • FDP has been added and tested!

For 0.4:

  • IPv6 has been tested for “IP as Hostname” - IPs are added using “udp6:[IPv6::IP]”. FQDN as hostname? Probably very buggy if only an IPv6 address exists for the host. This may also be very dependent on what version of SNMP you're using (modern versions of Net-SNMP should be okay).
  • You can now choose whether to use a particular discovery protocol or not. Be aware that LLDP aware Cisco devices will be scanned both for LLDP and CDP, but this should be safe; the CDP scanner should only add devices not detected via LLDP.
  • Yeah, still no FDP. Maybe in 0.5? I actually have Cacti on a mon-box that scans Brocade equipment now.
  • Upgrading from everything except 0.1 should simply be a matter of overwriting the existing files, and then going in to “Settings” - “Misc”, verifying the settings for using a particular discovery protocol, and then “SAVE”ing the settings.
  • For this and all prior versions (and “early” 1.0 versions) a bug existed whereby discovery names of ”” were considered valid and processed normally (and the FQDN code would just make it ”.your.domain.com”). It was fixed in 1.0 (though if you downloaded it “right after” I posted it, you could have buggy code).

0.3:

  • Don't know if the “ADD” button is working properly yet.
  • Still no FDP.
  • Still no IPv6 testing yet.
  • Fixed in this release:
    • During debugging on a second server, we discovered the requirement for PHP 5.2.0 - we use “filter_var”, which isn't part PHP until 5.2.0 (a PECL module may be available, but is unsupported). Suggest CentOS 5 users look at uninstalling “php” packages, and install “php53” instead.
    • Discovered that somewhere along the line I changed the dpdiscover_parent_filter variable and as such, findhosts.php, if configured to use parent SNMP values, wouldn't filter them out.

0.2:

  • The “ADD” functionality on the “discover” tab may not work properly; it was tested, but at some point I noticed that the device had been added twice (once with an FQDN description). This may have been the work of an errant use of the “back” button in my browser.
  • Still no FDP yet.
  • Still no IPv6 testing yet.

0.1:

  • Oh, plenty I'm sure. Not the least of which is that I need to get the report tab's page cleaned up a bit.
  • FDP hasn't been coded yet.
  • IPv6 hasn't been tested.
  • “Email report” functionality should work but hasn't been successfully tested yet.

Best place to complain about bugs? The GitHub issues page for DPDiscover.

You may also use the forum post for this plugin.

It may run on versions of Cacti earlier than 0.8.8b, but I am unfamiliar with Cacti prior than 0.8.8b, so … that's all on you.

Screenshots

None available yet.






Personal Tools