mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Added docs on Discovery / Poller, modules and how to debug + FAQs

Browse Source
This commit is contained in:
laf
2015-05-04 16:20:38 +01:00
parent 3de28d8dfb
commit 12ec5113d6
3 changed files with 339 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
doc/Support/Discovery Support.md Normal file
View File

@@ -0,0 +1,138 @@
### discovery.php
This document will explain how to use discovery.php to debug issues or manually running to process data.
#### Command options
```bash
-h <device id> | <device hostname wildcard> Poll single device
-h odd Poll odd numbered devices (same as -i 2 -n 0)
-h even Poll even numbered devices (same as -i 2 -n 1)
-h all Poll all devices
-h new Poll all devices that have not had a discovery run before
-i <instances> -n <number> Poll as instance <number> of <instances>
Instances start at 0. 0-3 for -n 4
Debugging and testing options:
-d Enable debugging output
-m Specify single module to be run
```
`-h` Use this to specify a device via either id or hostname (including wildcard using *). You can also specify odd and
even. all will run discovery against all devices whilst
new will poll only those devices that have recently been added or have been selected for rediscovery.
`-i` This can be used to stagger the discovery process.
`-d` Enables debugging output (verbose output) so that you can see what is happening during a discovery run. This includes
things like rrd updates, SQL queries and response from snmp.
`-m` This enables you to specify the module you want to run for discovery.
#### Discovery config
These are the default discovery config items. You can globally disable a module by setting it to 0. If you just want to
disable it for one device then you can do this within the WebUI -> Settings -> Modules.
```php
$config['discovery_modules']['os'] = 1;
$config['discovery_modules']['ports'] = 1;
$config['discovery_modules']['ports-stack'] = 1;
$config['discovery_modules']['entity-physical'] = 1;
$config['discovery_modules']['processors'] = 1;
$config['discovery_modules']['mempools'] = 1;
$config['discovery_modules']['ipv4-addresses'] = 1;
$config['discovery_modules']['ipv6-addresses'] = 1;
$config['discovery_modules']['sensors'] = 1;
$config['discovery_modules']['storage'] = 1;
$config['discovery_modules']['hr-device'] = 1;
$config['discovery_modules']['discovery-protocols'] = 1;
$config['discovery_modules']['arp-table'] = 1;
$config['discovery_modules']['discovery-arp'] = 0;
$config['discovery_modules']['junose-atm-vp'] = 1;
$config['discovery_modules']['bgp-peers'] = 1;
$config['discovery_modules']['vlans'] = 1;
$config['discovery_modules']['cisco-mac-accounting'] = 1;
$config['discovery_modules']['cisco-pw'] = 1;
$config['discovery_modules']['cisco-vrf'] = 1;
#$config['discovery_modules']['cisco-cef'] = 1;
$config['discovery_modules']['cisco-sla'] = 1;
$config['discovery_modules']['vmware-vminfo'] = 1;
$config['discovery_modules']['libvirt-vminfo'] = 1;
$config['discovery_modules']['toner'] = 1;
$config['discovery_modules']['ucd-diskio'] = 1;
$config['discovery_modules']['services'] = 1;
$config['discovery_modules']['charge'] = 1;
```
#### Discovery modules
`os`: Os detection. This module will pick up the OS of the device.
`ports`: This module will detect all ports on a device excluding ones configured to be ignored by config options.
`ports-stack`: Same as ports except for stacks.
`entity-physical`: Module to pick up the devices hardware support.
`processors`: Processor support for devices.
`mempools`: Memory detection support for devices.
`ipv4-addresses`: IPv4 Address detection
`ipv6-addresses`: IPv6 Address detection
`sensors`: Sensor detection such as Temperature, Humidity, Voltages + More
`storage`: Storage detection for hard disks
`hr-device`: Processor and Memory support via HOST-RESOURCES-MIB.
`discovery-protocols`: Auto discovery module for xDP, OSPF and BGP.
`arp-table`: Detection of the ARP table for the device.
`discovery-arp`: Auto discovery via ARP.
`junose-atm-vp`: Juniper ATM support.
`bgp-peers`: BGP detection and support.
`vlans`: VLAN detection and support.
`cisco-mac-accounting`: MAC Address account support.
`cisco-pw`: Pseudowires wires detection and support.
`cisco-vrf`: VRF detection and support.
`cisco-cef`: CEF detection and support.
`cisco-sla`: SLA detection and support.
`vmware-vminfo`: Detection of vmware guests on an ESXi host
`libvirt-vminfo`: Detection of libvirt guests.
`toner`: Toner levels support.
`ucd-diskio`: Disk I/O support.
`services`: *Nix services support.
`charge`: APC Charge detection and support.
#### Running
Here are some examples of running discovery from within your install directory.
```bash
./discovery.php -h localhost
./discovery.php -h localhost -m ports
```
#### Debugging
To provide debugging output you will need to run the discovery process with the `-d` flag. You can do this either against
all modules, single or multiple modules:
All Modules
```bash
./discovery.php -h localhost -d
```
Single Module
```bash
./discovery.php -h localhost -m ports -d
```
Multiple Modules
```bash
./discovery.php -h localhost -m ports,entity-physical -d
```
It is then advisable to sanitise the output before pasting it somewhere as the debug output will contain snmp details
amongst other items including port descriptions.
The output will contain:
DB Updates
RRD Updates
SNMP Response

53
doc/Support/FAQ.md
View File

@@ -7,11 +7,15 @@
### Support
- [Why do I get blank pages sometimes in the WebUI?](#faq6)
- [Why do I not see any graphs?](#faq10)
- [How do I debug pages not loading correctly?](#faq7)
- [How do I debug the discovery process?](#faq11)
- [How do I debug the poller process?](#faq12)
### Developing
- [How do I add support for a new OS?](#faq8)
- [What can I do to help?](#faq9)
- [How can I test another users branch?](#faq13)
#### <a name="faq1"> How do I install LibreNMS?</a>
@@ -63,6 +67,11 @@ The first thing to do is to add /debug=yes/ to the end of the URI (I.e /devices/
If the page you are trying to load has a substantial amount of data in it then it could be that the php memory limit needs to be increased in php.ini and then your web service reloaded.
#### <a name="faq10"> Why do I not see any graphs?</a>
This is usually due to there being blank spaces outside of the `<?php ?>` php tags within config.php. Remove these and retry.
It's also worth removing the final `?>` at the end of config.php as this is not required.
#### <a name="faq7"> How do I debug pages not loading correctly?</a>
A debug system is in place which enables you to see the output from php errors, warnings and notices along with the MySQL queries that have been run for that page.
@@ -71,6 +80,14 @@ To enable the debug option, add /debug=yes/ to the end of any URI (I.e /devices/
You will then have a two options in the footer of the website - Show SQL Debug and Show PHP Debug. These will both popup that pages debug window for you to view. If the page itself has generated a fatal error then this will be displayed directly on the page.
#### <a name="faq11"> How do I debug the discovery process?</a>
Please see the (Discovery Support)[http://docs.librenms.org/Support/Discovery Support] document for further details.
#### <a name="faq12"> How do I debug the poller process?</a>
Please see the (Poller Support)[http://docs.librenms.org/Support/Poller Support] document for further details.
#### <a name="faq8"> How do I add support for a new OS?</a>
The easiest way to show you how to do that is to link to an existing pull request that has been merged in on [GitHub](https://github.com/librenms/librenms/pull/352/files)
@@ -101,3 +118,39 @@ Thanks for asking, sometimes it's not quite so obvious and everyone can contribu
- Feature requests. Can't code / won't code. No worries, chuck a feature request into Git Hub with enough detail and someone will take a look. A lot of the time this might be what interests someone, they need the same feature or they just have time. Please be patient, everyone who contributes does so in their own time.
- Be nice, this is the foundation of this project. We expect everyone to be nice. People will fall out, people will disagree but please do it so in a respectable way.
- Ask questions. Sometimes just by asking questions you prompt deeper conversations that can lead us to somewhere amazing so please never be afraid to ask a question.
#### <a name="faq13"> How can I test another users branch?</a>
LibreNMS can and is developed by anyone, this means someone may be working on a new feature or support for a device that you want.
It can be helpful for others to test these new features, using Git, this is made easy.
```bash
cd /opt/librenms
```
Firstly ensure that your current branch is in good state:
```bash
git status
```
If you see `nothing to commit, working directory clean` then let's go for it :)
Let's say that you want to test a users (f0o) new development branch (issue-1337) then you can do the following:
```bash
git remote add f0o https://github.com/librenms/librenms.git
git remote update f0o
git checkout issue-1337
```
Once you are done testing, you can easily switch back to the master branch:
```bash
git checkout master
```
If you want to pull any new updates provided by f0o's branch then whilst you are still in it, do the following:
```bash
git pull f0o issue-1337
```

148
doc/Support/Poller Support.md Normal file
View File

@@ -0,0 +1,148 @@
### poller.php
This document will explain how to use poller.php to debug issues or manually running to process data.
#### Command options
```bash
LibreNMS 2014.master Poller
-h <device id> | <device hostname wildcard> Poll single device
-h odd Poll odd numbered devices (same as -i 2 -n 0)
-h even Poll even numbered devices (same as -i 2 -n 1)
-h all Poll all devices
-i <instances> -n <number> Poll as instance <number> of <instances>
Instances start at 0. 0-3 for -n 4
Debugging and testing options:
-r Do not create or update RRDs
-d Enable debugging output
-m Specify module(s) to be run
```
`-h` Use this to specify a device via either id or hostname (including wildcard using *). You can also specify odd and
even. all will run poller against all devices.
`-i` This can be used to stagger the poller process.
`-r` This option will suppress the creation or update of RRD files.
`-d` Enables debugging output (verbose output) so that you can see what is happening during a poller run. This includes
things like rrd updates, SQL queries and response from snmp.
`-m` This enables you to specify the module you want to run for poller.
#### Poller config
These are the default poller config items. You can globally disable a module by setting it to 0. If you just want to
disable it for one device then you can do this within the WebUI -> Settings -> Modules.
```php
$config['poller_modules']['unix-agent'] = 0;
$config['poller_modules']['system'] = 1;
$config['poller_modules']['os'] = 1;
$config['poller_modules']['ipmi'] = 1;
$config['poller_modules']['sensors'] = 1;
$config['poller_modules']['processors'] = 1;
$config['poller_modules']['mempools'] = 1;
$config['poller_modules']['storage'] = 1;
$config['poller_modules']['netstats'] = 1;
$config['poller_modules']['hr-mib'] = 1;
$config['poller_modules']['ucd-mib'] = 1;
$config['poller_modules']['ipSystemStats'] = 1;
$config['poller_modules']['ports'] = 1;
$config['poller_modules']['bgp-peers'] = 1;
$config['poller_modules']['junose-atm-vp'] = 1;
$config['poller_modules']['toner'] = 1;
$config['poller_modules']['ucd-diskio'] = 1;
$config['poller_modules']['wifi'] = 1;
$config['poller_modules']['ospf'] = 1;
$config['poller_modules']['cisco-ipsec-flow-monitor'] = 1;
$config['poller_modules']['cisco-remote-access-monitor'] = 1;
$config['poller_modules']['cisco-cef'] = 1;
$config['poller_modules']['cisco-sla'] = 1;
$config['poller_modules']['cisco-mac-accounting'] = 1;
$config['poller_modules']['cipsec-tunnels'] = 1;
$config['poller_modules']['cisco-ace-loadbalancer'] = 1;
$config['poller_modules']['cisco-ace-serverfarms'] = 1;
$config['poller_modules']['netscaler-vsvr'] = 1;
$config['poller_modules']['aruba-controller'] = 1;
$config['poller_modules']['entity-physical'] = 1;
$config['poller_modules']['applications'] = 1;
$config['poller_modules']['cisco-asa-firewall'] = 1;
```
#### Poller modules
`unix-agent`: Enable the check_mk agent for external support for applications.
`system`: Provides information on some common items like uptime, sysDescr and sysContact.
`os`: Os detection. This module will pick up the OS of the device.
`ipmi`: Enables support for IPMI if login details have been provided for IPMI.
`sensors`: Sensor detection such as Temperature, Humidity, Voltages + More.
`processors`: Processor support for devices.
`mempools`: Memory detection support for devices.
`storage`: Storage detection for hard disks
`netstats`: Statistics for IP, TCP, UDP, ICMP and SNMP.
`hr-mib`: Host resource support.
`ucd-mib`: Support for CPU, Memory and Load.
`ipSystemStats`: IP statistics for device.
`ports`: This module will detect all ports on a device excluding ones configured to be ignored by config options.
`bgp-peers`: BGP detection and support.
`junose-atm-vp`: Juniper ATM support.
`toner`: Toner levels support.
`ucd-diskio`: Disk I/O support.
`wifi`: WiFi Support for those devices with support.
`ospf`: OSPF Support.
`cisco-ipsec-flow-monitor': IPSec statistics support.
`cisco-remote-access-monitor`: Cisco remote access support.
`cisco-cef`: CEF detection and support.
`cisco-sla`: SLA detection and support.
`cisco-mac-accounting`: MAC Address account support.
`cipsec-tunnels`: IPSec tunnel support.
`cisco-ace-loadbalancer`: Cisco ACE Support.
`cisco-ace-serverfarms`: Cisco ACE Support.
`netscaler-vsvr`: Netscaler support.
`aruba-controller`: Arube wireless controller support.
`entity-physical`: Module to pick up the devices hardware support.
`applications`: Device application support.
`cisco-asa-firewall`: Cisco ASA firewall support.
#### Running
Here are some examples of running poller from within your install directory.
```bash
./poller.php -h localhost
./poller.php -h localhost -m ports
```
#### Debugging
To provide debugging output you will need to run the poller process with the `-d` flag. You can do this either against
all modules, single or multiple modules:
All Modules
```bash
./poller.php -h localhost -d
```
Single Module
```bash
./poller.php -h localhost -m ports -d
```
Multiple Modules
```bash
./poller.php -h localhost -m ports,entity-physical -d
```
It is then advisable to sanitise the output before pasting it somewhere as the debug output will contain snmp details
amongst other items including port descriptions.
The output will contain:
DB Updates
RRD Updates
SNMP Response