Add documentation for initial release

doc/General/MIB-based-polling.md

@@ -1,25 +1,95 @@
-The overall design of MIB-based support is:
+## WARNING ##
 
-Discovery:
+MIB-based polling is experimental.  It might overload your LibreNMS server,
-  - MIBs are not involved; any work done here would have to be 
+destroy your data, set your routers on fire, and kick your cat.  It has been
+tested against a very limited set of devices (namely Ruckus ZD1000 wireless
+controllers, and Net-SNMP on Linux).  It may fail badly on other hardware.
+
+The approach taken is fairly basic and I claim no special expertise in
+understanding MIBs.  Most of my understanding of SNMP comes from reading
+net-snmp man pages, and reverse engineering the output of snmptranslate and
+snmpwalk and trying to make devices work with LibreNMS.  I may have made
+false assumptions and probably use wrong terminology in many places.  Feel
+free to offer corrections/suggestions via pull requests or email.
+
+Paul Gear <paul@librenms.org>
+
+## Overview ##
+
+MIB-based polling is disabled by default; you must set
+    `$config['poller_modules']['mib'] = 1;`
+in config.php to enable it.
+
+The components involved in of MIB-based support are:
+
+### Discovery ###
+
+  - MIB-based detection is not involved; any work done here would have to be
     duplicated by the poller and thus would only increase load.
 
-Polling:
+### Polling ###
-  - Look for a MIB matching sysObjectID in the MIB directory; if one
-    is found:
-    - parse it
-    - walk that MIB on the device
-    - store any numeric results in individual RRD files
-    - update/add graph definitions in the database
-  - Individual OSes (includes/polling/os/*.inc.php) can poll extra MIBs
-    that should be there for a given OS by calling poll_mib().
-  - Devices may be excluded from MIB polling by adding poll_mib = 0 to
-    devices_attribs (see /device/device=ID/tab=edit/section=modules/)
 
-Graphing:
+  - The file `includes/snmp.inc.php` now contains code which can parse MIBs
-  - For each file in the device directory, create a graph using the
+    using `snmptranslate` and use the data returned to populate an array
-    definition in the database.  Future enhancements:
+    which guides the poller in what to store.  At the moment, only OIDs with
-    - Allow graphs to go in different sections
+    Unsigned32 and Counter64 data types are parsed.
-    - Allow graphs to be combined automatically or on a user-defined
+  - `includes/polling/mib.inc.php` looks for a MIB matching sysObjectID in
-      basis.
+    the MIB directory; if one is found, it:
+    - parses it
+    - walks that MIB on the device
+    - stores any numeric results in individual RRD files
+    - updates/adds graph definitions in the previously-unused graph_types
+      database table
+  - Individual OSes (`includes/polling/os/*.inc.php`) can poll extra MIBs
+    for a given OS by calling poll_mib().  At the moment, this actually
+    happens before the general MIB polling.
+  - Devices may be excluded from MIB polling by changing the setting in the
+    device edit screen (`/device/device=ID/tab=edit/section=modules/`)
+
+### Graphing ###
+
+  - For each graph type device directory, a graph will appear in the Device
+    -> Graphs -> MIB section.
+  - At the moment, all units are placed in the same graph.  This is probably
+    non-optimal for, e.g., wifi controllers with hundreds of APs attached.
+
+## Adding/testing other device types ##
+
+One of the goals of this work is to help take out the heavy lifting of
+adding new device types.  Even if you want fully customised graphs or
+tables, you can use the automatic collection of MIBs to make it easy to
+gather the data you want.
+
+### How to add a new device MIB ###
+
+ 1. Ensure the manufacturer's MIB is present in the mibs directory.  If you
+    plan to submit your work to LibreNMS, make sure you attribute the source
+    of the MIB, including the exact download URL.
+ 2. Check that `snmptranslate -Ts -M mibs -m MODULE | grep mibName` produces
+    a named list of OIDs.  See the comments for `snmp_mib_walk()` in
+    `includes/snmp.inc.php` for an example.
+ 3. Check that `snmptranslate -Td -On -M mibs -m MODULE MODULE::mibName`
+    produces a parsed description of the OID values.  An example can be
+    found in the comments for `snmp_mib_parse()` in `includes/snmp.inc.php`.
+ 4. Get the `sysObjectID` from a device, for example:```
+snmpget -v2c -c public -OUsb -m SNMPv2-MIB -M /opt/librenms/mibs -t 30 hostname sysObjectID.0
+```
+ 5. Ensure `snmptranslate -m all -M /opt/librenms/mibs OID 2>/dev/null`
+    (where OID is the value returned for sysObjectID above) results in a
+    valid name for the MIB.  See the comments for `snmp_translate()` in
+    `includes/snmp.inc.php` for an example.  If this step fails, it means
+    there is something wrong with the MIB and net-snmp cannot parse it.
+
+## TODO ##
+
+  - Save the most recent MIB data in the database (including string types
+    which cannot be graphed).  Display it in the appropriate places.
+  - Parse and save integer and timetick data types.
+  - Filter MIBs/OIDs from being polled and/or saved.
+  - Move graphs from the MIB section to elsewhere. e.g. There is already
+    specific support for wireless APs - this should be utilised, but isn't
+    yet.
+  - Combine multiple MIB values into graphs automatically on a predefined or
+    user-defined basis.
+  - Include MIB types in stats submissions.