mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
Add documentation for initial release
This commit is contained in:
@ -1,25 +1,95 @@
|
||||
The overall design of MIB-based support is:
|
||||
## WARNING ##
|
||||
|
||||
Discovery:
|
||||
- MIBs are not involved; any work done here would have to be
|
||||
MIB-based polling is experimental. It might overload your LibreNMS server,
|
||||
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:
|
||||
- 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/)
|
||||
### Polling ###
|
||||
|
||||
Graphing:
|
||||
- For each file in the device directory, create a graph using the
|
||||
definition in the database. Future enhancements:
|
||||
- Allow graphs to go in different sections
|
||||
- Allow graphs to be combined automatically or on a user-defined
|
||||
basis.
|
||||
- The file `includes/snmp.inc.php` now contains code which can parse MIBs
|
||||
using `snmptranslate` and use the data returned to populate an array
|
||||
which guides the poller in what to store. At the moment, only OIDs with
|
||||
Unsigned32 and Counter64 data types are parsed.
|
||||
- `includes/polling/mib.inc.php` looks for a MIB matching sysObjectID in
|
||||
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.
|
||||
|
||||
|
Reference in New Issue
Block a user