mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
Docs refactor (#7389)
* 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
GitHub
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
|
||||
@@ -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 `[email protected]` 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 `[email protected]` 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.
|
||||
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
@@ -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``
|
||||
@@ -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`:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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/" />
|
||||
Reference in New Issue
Block a user