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

Docs refactor (#7389)

Browse Source 
* docs: Refactored docs for new layout

* some more changes

* more doc updates

* More doc updates

* small update

* small update
This commit is contained in:
Neil Lathwood
2017-10-02 21:36:22 +01:00
committed by GitHub
parent 738067e622
commit f1b50737bb
28 changed files with 266 additions and 361 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/Extensions/Agent-Setup.md
View File

@@ -1,5 +1,4 @@
# Agent Setup
source: Extensions/Agent-Setup.md
The agent can be used to gather data from remote systems you can use LibreNMS in combination with check_mk (found [here](https://github.com/librenms/librenms-agent)).
The agent can be extended to include data about [applications](Applications.md) on the remote system.

4
doc/Extensions/Applications.md
View File

@@ -1,6 +1,6 @@
source: Extensions/Applications.md
Applications
------------
## Introduction
You can use Application support to graph performance statistics from many applications.
Different applications support a variety of ways collect data: by direct connection to the application, snmpd extend, or [the agent](Agent-Setup.md).

32
doc/Extensions/Auto-Discovery.md
View File

@@ -124,17 +124,31 @@ Enabled by default.
This module is invoked from bgp-peers discovery module.
## SNMP Scan
This isn't actually an auto-discovery 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.
### SNMP Scan
Apart from the aforementioned Auto-Discovery options, LibreNMS is also able to proactively scan a network for SNMP-enabled devices using the configured version/credentials.
SNMP Scan will scan `$config['nets']` by default and respects `$config['autodiscovery']['nets-exclude']`.
An example of it's usage is:
To run the SNMP-Scanner you need to execute the `snmp-scan.py` from within your LibreNMS installation directory.
Here the script's help-page for reference:
```text
usage: snmp-scan.py [-h] [-r NETWORK] [-t THREADS] [-l] [-v]
Scan network for snmp hosts and add them to LibreNMS.
optional arguments:
-h, --help show this help message and exit
-r NETWORK CIDR noted IP-Range to scan. Can be specified multiple times
This argument is only required if $config['nets'] is not set
Example: 192.168.0.0/24 Example: 192.168.0.0/31 will be
treated as an RFC3021 p-t-p network with two addresses,
192.168.0.0 and 192.168.0.1 Example: 192.168.0.1/32 will be
treated as a single host address
-t THREADS How many IPs to scan at a time. More will increase the scan
speed, but could overload your system. Default: 32
-l, --legend Print the legend.
-v, --verbose Show debug output. Specifying multiple times increases the
verbosity.
```bash
./snmp-scan.py -r 192.168.0.0/24
```

15
doc/Extensions/Device-Groups.md
View File

@@ -1,9 +1,8 @@
source: Extensions/Device-Groups.md
# Device Groups
LibreNMS supports grouping your devices together in much the same way as you can configure alerts. This document will hopefully help you get started.
### Pattern
### Patterns
Patterns work in the same was as Entities within the alerting system, the format of the pattern is based on the MySQL structure your data is in such
as __tablename.columnname__. If you are ensure of what the entity is you want then have a browse around inside MySQL using `show tables` and `desc <tablename>`.
@@ -16,16 +15,22 @@ As a working example and a common question, let's assume you want to group devic
As with alerts, the `Like` operation allows MySQL Regular expressions.
A list of common entities is maintained in our [Alerting docs](http://docs.librenms.org/Extensions/Alerting/#entities).
A list of common entities is maintained in our [Alerting docs](/Alerting/Entities/).
### Conditions
Please see our [Alerting docs](http://docs.librenms.org/Extensions/Alerting/#syntax) for explanations.
Please see our [Alerting docs](/Alerting/Rules/#syntax) for explanations.
### Connection
If you only want to group based on one pattern then select And. If however you want to build a group based on multiple patterns then you can build a SQL like
query using And / Or. As an example, we want to base our group on the devices hostname AND it's type. Use the pattern as before, `devices.hostname`, select the condition which in this case would be `Like` and then enter `dc1.@.example.com` then click And. Now enter `devices.type` in the pattern, select `Equals` and enter `firewall`. This would then match dc1.fw01.example.com but not dc1.sw01.example.com as that is a network type.
query using And / Or.
As an example, we want to base our group on the devices hostname AND it's type. Use the pattern as before, `devices.hostname`, select
the condition which in this case would be `Like` and then enter `dc1.@.example.com` then click And. Now enter `devices.type` in the pattern, select `Equals`
and enter `firewall`. This would then match dc1.fw01.example.com but not dc1.sw01.example.com as that is a network type.
![Device Groups](/img/device_groups.png)
You can now select this group from the Devices -> All Devices link in the navigation at the top. You can also use the group to map alert rules to by creating an alert mapping
`Overview -> Alerts -> Rule Mapping`.

112
doc/Extensions/Interface-Description-Parsing.md
View File

@@ -1,56 +1,78 @@
source: Extensions/Interface-Description-Parsing.md
Table of Content:
- [About](#about)
- [Setup](#setup)
- [Keywords](#keywords)
- [Type-keywords](#type-keywords)
- [Info-keywords](#info-keywords)
- [Examples](#examples)
- [Sourcecode](#source)
# <a name="about">About</a>:
## About
Librenms can interpret, display and group certain additional information on ports.
For this a small `bash` script is supplied in `scripts/` called `ifAlias`.
This is done based on the format that the port description is written although it's possible
to customise the parser to be specific for your setup.
<a name="setup">Setup</a>:
## Keywords
This requires a little bit of setup on the monitored Server (Not the server running librenms!):
See [examples](#examples) for formats.
* Add `ifAlias` from `/opt/librenms/scripts/` or download it from [here](#source) to the Server and make
- **Keywords**
- `Cust` - Customer
- `Transit` - Transit link
- `Peering` - Peering link
- `Core` - Infrastructure link (non-customer)
- Info-keywords
- `()` contains a note
- `{}` contains *your* circuit id
- `[]` contains the service type or speed
## Examples
Cisco IOS / NXOS / IOSXR:
```text
interface Gi0/1
descr Transit: Example Provider (AS65000)
interface Gi0/2
descr Peering: Peering Exchange
interface Gi0/3
descr Core: core.router01 FastEthernet0/0 (Telco X CCID023141)
interface Gi0/4
descr Cust: Example Customer [10Mbit] (T1 Telco Y CCID129031) {EXAMP0001}
```
Unix / Linux:
> This requires an additional script to be [setup](#setup)
```text
# eth3: Cust: Example Customer [10Mbit] (T1 Telco Y CCID129031) {EXAMP0001}
# eth0: Transit: Example Provider (AS65000)
# eth1: Core: core.router01 FastEthernet0/0 (Telco X CCID023141)
# eth2: Peering: Peering Exchange
```
## Customisation
The following config options can be set to enable more custom types:
```php
$config['customers_descr'][] = 'cust';
$config['transit_descr'][] = "transit";
$config['peering_descr'][] = "peering";
$config['core_descr'][] = "core";
$config['custom_descr'][] = "something_made_up";
```
## Custom interface parser
It's also possible to write your own parser, the existing one is: includes/port-descr-parser.inc.php
Once you've created your own then you can enable it with:
```php
$config['port_descr_parser'] = "includes/custom/my-port-descr-parser.inc.php";
```
## Setup
For Unix / Linux based systems, you need to run an additional script to support the parsing of interface infor.
- Add `ifAlias` from `/opt/librenms/scripts/` or download it from [here](https://github.com/librenms/librenms/blob/master/scripts/ifAlias) to the Server and make
it executable `chmod +x /path/to/ifAlias`
* Add to `snmpd.conf` something like:
- Add to `snmpd.conf` something like:
``pass .1.3.6.1.2.1.31.1.1.1.18 /path/to/ifAlias``
* Restart your `net-snmpd`
- Restart `snmpd` - `service snmpd restart`
There are no changes to be made or additions to install for the polling librenms.
Now you can set up your [keywords](#keywords) in your `/etc/network/interfaces`
``//Add more distributions than just Debian based``
# <a name="keywords">Keywords</a>:
See [examples](#examples) for formats.
* <a name="type-keywords">Type-keywords</a>:
* `Cust` - Customer
* `Transit` - Transit link
* `Peering` - Peering link
* `Core` - Infrastructure link (non-customer)
* `Server` - Server link (non-customer)
* <a name="info-keywords">Info-keywords</a>:
* `()` contains a note
* `{}` contains *your* circuit id
* `[]` contains the service type or speed
# <a name="examples">Examples</a>:
```text
# eth3: Cust: Example Customer [10Mbit] (T1 Telco Y CCID129031) {EXAMP0001}`
# eth0: Transit: Example Provider (AS65000)`
# eth1: Core: core.router01 FastEthernet0/0 (Telco X CCID023141)`
# eth2: Peering: Peering Exchange
```
# <a name="source">Source code</a>:
* https://github.com/librenms/librenms/blob/master/scripts/ifAlias
``//Add more distributions than just Debian based``

2
doc/Extensions/Memcached.md
View File

@@ -1,6 +1,8 @@
source: Extensions/Memcached.md
# Memcached
> At this present moment, it is not advisable to run memcached other than for Distributed Polling.
LibreNMS can store SQL results in memcached to achieve performance advantages of in-memory value storage and removing work load for frequent queries off the MySQL backend.
To enable memcached in your install you need to have `memcached` installed and the PHP extension `php5-memcached` or `php-memcached` and add the following lines to your `config.php`:

3
doc/Extensions/Network-Map.md
View File

@@ -1,7 +1,6 @@
source: Extensions/Network-Map.md
# Network Map
## LibreNMS has the ability to show you a network map based on:
LibreNMS has the ability to show you a network map based on:
- xDP Discovery
- MAC addresses

18
doc/Extensions/Oxidized.md
View File

@@ -1,6 +1,7 @@
source: Extensions/Oxidized.md
# Oxidized integration
# Oxidized intro
---
Integrating LibreNMS with [Oxidized](https://github.com/ytti/oxidized-web) brings the following benefits:
- Config viewing: Current, History, and Diffs all under the Configs tab of each device
@@ -13,9 +14,8 @@ Then you can procede to the LibreNMS Web UI and go to Oxidized Settings in the E
To have devices automatically added, you will need to configure oxidized to pull them from LibreNMS [Feeding Oxidized](#feeding-oxidized)
## Detailed integration information
### Config viewing
### Detailed integration information
---
This is a straight forward use of Oxidized, it relies on you having a working Oxidized setup which is already taking config snapshots for your devices.
When you have that, you only need the following config to enable the display of device configs within the device page itself:
@@ -43,15 +43,15 @@ You can set a default group that devices will fall back to with:
$config['oxidized']['default_group'] = 'default';
```
##### SELinux
#### SELinux
If you're runnng SELinux, you'll need to allow httpd to connect outbound to the network, otherwise Oxidized integration in the web UI will silently fail:
```
setsebool -P httpd_can_network_connect 1
```
### Feeding Oxidized
----
Oxidized has support for feeding devices into it via an API call, support for Oxidized has been added to the LibreNMS API. A sample config for Oxidized is provided below.
@@ -79,7 +79,7 @@ $config['oxidized']['reload_nodes'] = true;
```
#### Using Groups
### Working with groups
To return a group to Oxidized you can do this by matching a regex for either `hostname`, `os` or `location`. The order is `hostname` is matched first, if nothing is found then `os` is tried and then `location` is attempted.
The first match found will be used. To match on the device hostnames that contain 'lon-sw' or if the location contains 'London' then you would place the following within config.php:
@@ -110,7 +110,7 @@ groups:
password: <password>
```
#### Miscellaneous
### Miscellaneous
If you have devices which you do not wish to appear in Oxidized then you can edit those devices in Device -> Edit -> Misc and enable "Exclude from Oxidized?"
@@ -121,7 +121,7 @@ $config['oxidized']['ignore_types'] = array('server');
$config['oxidized']['ignore_os'] = array('linux');
```
### Trigger configuration downloads
### Trigger configuration backups
Using the Oxidized REST API and [Syslog Hooks](/Extensions/Syslog/#external-hooks), Oxidized can trigger configuration downloads whenever a configuration change event has been logged. An example script to do this is included in `./scripts/syslog-notify-oxidized.php`. Oxidized can spawn a new worker thread and perform the download immediately with the following configuration

88
doc/Extensions/Port-Description-Parser.md
View File

@@ -1,87 +1 @@
source: Extensions/Port-Description-Parser.md
# Configuring interface descriptions for parsing.
LibreNMS includes the ability to parse your interface descriptions for set information to display and segment in the WebUI.
The following information is used from interface descriptions:
- Type. This is currently Cust (Customer), Peering, Transit and Core
- Circuit information
- Notes
- Speed
When setting the description, you use the type followed directly with : and then the information on that port. Some examples based on
configuring a Cisco 2960 interface
#### Customer port
description Cust: Customer A
#### Transport port
description Transit: ISP A
#### Peering port
description Peering: Local Peer
#### Core port
description Core: Agg connection
Having these set will then enable the menu options in Ports within the top navigation.
The following config options can be set to enable more custom types:
```php
$config['customers_descr'] = 'cust'; // The description to look for in ifDescr. Can be an array as well array('cust','cid');
$config['transit_descr'] = ""; // Add custom transit descriptions (can be an array)
$config['peering_descr'] = ""; // Add custom peering descriptions (can be an array)
$config['core_descr'] = ""; // Add custom core descriptions (can be an array)
$config['custom_descr'] = ""; // Add custom interface descriptions (can be an array)
```
To further enhance the use of port descriptions with Circuit info, Notes and Speed then these can be done as follows:
#### Circuit information
{}
i.e:
description: Cust: Customer A {ID4321}
#### Notes
()
i.e:
description Cust: Customer A (This customer is gold)
#### Speed
[]
i.e:
description Cust: Customer A [100Mbps]
You can use any of these additional options like:
description Cust: Customer A (this customer is gold) [10Gbps]
description Cust: Customer A {ID4321} [1Gbps]
This information is then held within the ports table within the database, as an example:
description Core: NAS bond [1Gbps]
```sh
port_descr_type: core
port_descr_descr: NAS bond
port_descr_circuit: NULL
port_descr_speed: 1Gbps
port_descr_notes: NULL
```
### Custom interface parser
It's also possible to write your own parser, the existing one is: includes/port-descr-parser.inc.php
Once you've created your own then you can enable it with:
```php
$config['port_descr_parser'] = "includes/custom/my-port-descr-parser.inc.php";
```
<meta http-equiv="refresh" content="0; url=/Extensions/Interface-Description-Parsing/" />