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
@@ -61,9 +61,3 @@ Alert when:
|
||||
|
||||
## Procedure
|
||||
You can associate a rule to a procedure by giving the URL of the procedure when creating the rule. Only links like "http://" are supported, otherwise an error will be returned. Once configured, procedure can be opened from the Alert widget through the "Open" button, which can be shown/hidden from the widget configuration box.
|
||||
|
||||
## Testing alerts
|
||||
|
||||
You can test your transports by forcing an actual active alert to run regardless of the interval or delay values.
|
||||
|
||||
`./scripts/test-alert.php`. This script accepts -r for the rule id, -h for the device id or hostname and -d for debug.
|
||||
@@ -58,18 +58,6 @@ Limit: %value.sensor_limit_low / %value.sensor_limit
|
||||
|
||||
The Default Template is a 'one-size-fit-all'. We highly recommend defining your own templates for your rules to include more specific information.
|
||||
|
||||
## Testing
|
||||
|
||||
It's possible to test your new template before assigning it to a rule. To do so you can run `./scripts/test-template.php`. The script will provide the help
|
||||
info when ran without any parameters.
|
||||
|
||||
As an example, if you wanted to test template ID 10 against localhost running rule ID 2 then you would run:
|
||||
|
||||
`./scripts/test-template.php -t 10 -d -h localhost -r 2`
|
||||
|
||||
If the rule is currently alerting for localhost then you will get the full template as expected to see on email, if it's not then you will just see the
|
||||
template without any fault information.
|
||||
|
||||
## Examples
|
||||
|
||||
Default Template:
|
||||
|
||||
31
doc/Alerting/Testing.md
Normal file
31
doc/Alerting/Testing.md
Normal file
@@ -0,0 +1,31 @@
|
||||
source: Alerting/Testing.md
|
||||
|
||||
### Rules
|
||||
|
||||
The simplest way of testing if an alert rule will match a device is by going to the device, clicking edit (the cog),
|
||||
select Capture. From this new screen choose Alerts and click run.
|
||||
|
||||
The output will cycle through all alerts applicable to this device and show you the Rule name, rule,
|
||||
MySQL query and if the rule matches.
|
||||
|
||||
---
|
||||
|
||||
### Transports
|
||||
|
||||
You can test your transports by forcing an actual active alert to run regardless of the interval or delay values.
|
||||
|
||||
`./scripts/test-alert.php`. This script accepts -r for the rule id, -h for the device id or hostname and -d for debug.
|
||||
|
||||
---
|
||||
|
||||
### Templates
|
||||
|
||||
It's possible to test your new template before assigning it to a rule. To do so you can run `./scripts/test-template.php`. The script will provide the help
|
||||
info when ran without any parameters.
|
||||
|
||||
As an example, if you wanted to test template ID 10 against localhost running rule ID 2 then you would run:
|
||||
|
||||
`./scripts/test-template.php -t 10 -d -h localhost -r 2`
|
||||
|
||||
If the rule is currently alerting for localhost then you will get the full template as expected to see on email, if it's not then you will just see the
|
||||
template without any fault information.
|
||||
@@ -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 `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.
|
||||
|
||||
|
||||
|
||||
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/" />
|
||||
@@ -1,8 +1,9 @@
|
||||
source: General/Acknowledgement.md
|
||||
LibreNMS 3rd party acknowledgements
|
||||
-----------------------------------
|
||||
|
||||
#### 3rd Party GPLv3 Compliant
|
||||
LibreNMS would't be what it is today without the use of some other amazing projects.
|
||||
We list below what we make use of including the license compliance.
|
||||
|
||||
## 3rd Party GPLv3 Compliant
|
||||
|
||||
- [Bootstrap](http://getbootstrap.com/): MIT
|
||||
- [Font Awesome](http://fontawesome.io/icons/): MIT License
|
||||
@@ -27,13 +28,17 @@ LibreNMS 3rd party acknowledgements
|
||||
- [Pure PHP radius class](http://developer.sysco.ch/php/): GPLv3
|
||||
- [GeSHi - Generic Syntax Highlighter](http://qbnz.com/highlighter/): GPLv2+
|
||||
- MalaysiaMap.svg - By Exiang [CC BY 3.0 (http://creativecommons.org/licenses/by/3.0)], via Wikimedia Commons
|
||||
- Code for UBNT Devices Mark Gibbons <mgibbons@oemcomp.com> Initial code base submitted via PR721
|
||||
- [Jquery LazyLoad](http://www.appelsiini.net/projects/lazyload): MIT License
|
||||
- [influxdb-php](https://github.com/influxdb/influxdb-php): MIT License
|
||||
- [HTML Purifier](http://htmlpurifier.org/): LGPL v2.1
|
||||
- [Symfony Yaml](https://github.com/symfony/yaml): MIT
|
||||
- [PHPMailer](https://github.com/PHPMailer/PHPMailer): LGPL v2.1
|
||||
- [pbin](https://github.com/glensc/pbin): GPLv2 (or later - see script header)
|
||||
- [CorsSlim](https://github.com/palanik/CorsSlim): MIT
|
||||
|
||||
#### 3rd Party GPLv3 Non-compliant
|
||||
|
||||
## 3rd Party GPLv3 Non-compliant
|
||||
|
||||
- JpGraph (html/includes/jpgraph): QPL 1.0 license
|
||||
- MIBS (mibs): unknown/various
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
source: General/CODE_OF_CONDUCT.md
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
source: General/Changelog.md
|
||||
## 1.32
|
||||
*(2017-10-01)*
|
||||
|
||||
#### Features
|
||||
* Added more rules to the collection of alert rules ([#7363](https://github.com/librenms/librenms/issues/7363))
|
||||
* Added more rules to the collection of alert rules ([#7363](https://github.com/librenms/librenms/issues/763))
|
||||
* Allow ignore_mount, ignore_mount_string, ignore_mount_regex per OS ([#7304](https://github.com/librenms/librenms/issues/7304))
|
||||
* Added script to generate config for new OS ([#7161](https://github.com/librenms/librenms/issues/7161))
|
||||
* Added Syslog hook for ASA support ([#7268](https://github.com/librenms/librenms/issues/7268))
|
||||
@@ -93,7 +94,6 @@
|
||||
|
||||
---
|
||||
|
||||
source: General/Changelog.md
|
||||
## 1.31
|
||||
*(2017-08-26)*
|
||||
|
||||
|
||||
@@ -1,52 +1,2 @@
|
||||
source: General/Credits.md
|
||||
LibreNMS is a fork of the last GPL-licensed revision of Observium.
|
||||
http://observium.org/
|
||||
Copyright 2006-2012 Adam Armstrong <adama@memetic.org>.
|
||||
GPLv3
|
||||
|
||||
LibreNMS ships with the following software components:
|
||||
|
||||
- Bootstrap Datetime picker
|
||||
https://github.com/Eonasdan/bootstrap-datetimepicker
|
||||
Copyright (c) 2014 Eonasdan, nikoskalogridis
|
||||
MIT License
|
||||
|
||||
- Moment
|
||||
http://momentjs.com
|
||||
MIT License
|
||||
|
||||
- MKTree
|
||||
http://www.javascripttoolbox.com/lib/mktree/
|
||||
MIT and GPL License
|
||||
|
||||
- Jquery Bootgrid
|
||||
http://www.jquery-bootgrid.com/
|
||||
MIT License
|
||||
|
||||
- Font Awesome
|
||||
http://fontawesome.io/
|
||||
Varying licenses but GPL friendly
|
||||
|
||||
- Code for UBNT Devices
|
||||
Mark Gibbons <mgibbons@oemcomp.com>
|
||||
Initial code base submitted via PR721
|
||||
|
||||
- Jquery LazyLoad
|
||||
http://www.appelsiini.net/projects/lazyload
|
||||
Mika Tuupola <tuupola@appelsiini.net> (@tuupola on GitHub)
|
||||
MIT License
|
||||
|
||||
- influxdb-php
|
||||
https://github.com/influxdb/influxdb-php
|
||||
MIT License
|
||||
|
||||
Other components (needs details filled in):
|
||||
- JpGraph (html/includes/jpgraph): QPL 1.0 license
|
||||
|
||||
- MIBS (mibs): unknown/various
|
||||
|
||||
- html/graph-realtime.php: BSD (original?)
|
||||
|
||||
- html/includes/collectd/: GPLv2 only
|
||||
|
||||
- overLIB (html/js/overlib_mini.js): modified Artistic 1.0?
|
||||
<meta http-equiv="refresh" content="0; url=/General/Acknowledgement/" />
|
||||
@@ -1,5 +1,4 @@
|
||||
source: General/Releases.md
|
||||
# LibreNMS Releases
|
||||
|
||||
#### Introduction
|
||||
We try to ensure that breaking changes aren't introduced by utilising various automated
|
||||
@@ -7,6 +6,8 @@ code testing, syntax testing and unit testing along with manual code review. How
|
||||
bugs can and do get introduced as well as major refactoring to improve the quality of
|
||||
the code base.
|
||||
|
||||
We have two branches available for you to use. The default is the `master` branch.
|
||||
|
||||
#### Development branch
|
||||
Our `master` branch is our dev branch, this is actively commited to and it's not uncommon
|
||||
for multiple commits to be merged in daily. As such sometimes changes will be introduced
|
||||
@@ -24,10 +25,8 @@ With this in mind, we provide a monthly stable release which is released on or a
|
||||
the last Sunday of the month. Code pull requests (aside from Bug fixes) are stopped days
|
||||
leading up to the release to ensure that we have a clean working branch at that point.
|
||||
|
||||
The releases are titled after that month in the format `YYYYMM`, i.e `201608`. The
|
||||
Changelog is also updated and will reference the release number and date so you can see
|
||||
The changelog is also updated and will reference the release number and date so you can see
|
||||
what changes have been made since the last release.
|
||||
|
||||
To switch to using stable branches you can set `$config['update_channel'] = 'release';`
|
||||
in config.php and then switch to the latest release branch with `git fetch --tags && git checkout $(git describe --tags $(git rev-list --tags --max-count=1))`.
|
||||
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
source: General/Security.md
|
||||
# Security
|
||||
|
||||
### General
|
||||
Like any good software we take security seriously. However, bugs do make it into the software
|
||||
@@ -10,7 +9,7 @@ that should show that we take things seriously.
|
||||
As with any system of this nature, we highly recommend that you restrict access to the install via
|
||||
a firewall or VPN.
|
||||
|
||||
It is also highly recommended that the Web interface is protected with an SSL certificate such as one
|
||||
It is also highly recommended that the Web interface is protected with an SSL certificate such as ones
|
||||
provided by [LetsEncrypt](http://www.letsencrypt.org).
|
||||
|
||||
When using HTTPS, it is recommended that you use secure, encrypted cookies to prevent session
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
source: General/Updating.md
|
||||
## Updating your install ##
|
||||
|
||||
If you would like to perform a manual update
|
||||
then you can do this by running the following command as the **librenms** user:
|
||||
By default, LibreNMS is set to automatically update. If you have disabled this feature then you can
|
||||
perform a manual update.
|
||||
|
||||
#### Manual update
|
||||
|
||||
If you would like to perform a manual update then you can do this by running the following command
|
||||
as the `librenms` user:
|
||||
|
||||
`./daily.sh`
|
||||
|
||||
@@ -10,30 +14,13 @@ This will update both the core LibreNMS files but also update the database
|
||||
structure if updates are available.
|
||||
|
||||
#### Advanced users
|
||||
If you absolutely must update manually then you can do so by running the following commands:
|
||||
If you absolutely must update manually without using `./daily.sh` then you can do so by running the following commands:
|
||||
```bash
|
||||
cd /opt/librenms
|
||||
git pull
|
||||
php includes/sql-schema/update.php
|
||||
```
|
||||
|
||||
## Configuring the update channel ##
|
||||
LibreNMS follows the master branch on github for daily updates.
|
||||
|
||||
#### Stable branch
|
||||
You can change to the stable monthly branch by setting:
|
||||
|
||||
`$config['update_channel'] = 'release';`
|
||||
|
||||
> Choose this branch if you want to have a stable release
|
||||
|
||||
#### Development branch
|
||||
You can change to the development branch by setting:
|
||||
|
||||
`$config['update_channel'] = 'master';`
|
||||
|
||||
> Choose this branch if you want the latest features at the cost that sometimes bugs are inadvertently introduced.
|
||||
|
||||
## Disabling automatic updates ##
|
||||
LibreNMS by default performs updates on a daily basis. This can be disabled by setting:
|
||||
|
||||
|
||||
@@ -1,6 +1,4 @@
|
||||
source: General/Welcome-to-Observium-users.md
|
||||
Welcome to Observium users
|
||||
--------------------------
|
||||
|
||||
LibreNMS is a fork of Observium. The reason for the fork is nothing to do
|
||||
with Observium's [move to community vs. paid versions][1]. It is simply
|
||||
@@ -11,12 +9,6 @@ IT professionals. See [README.md][2] and the references there for more
|
||||
information about the kind of community we're trying to promote.
|
||||
|
||||
LibreNMS was forked from [the last GPL-licensed version of Observium][3].
|
||||
<del>This means you won't be able to take an existing Observium installation
|
||||
later than r3250 and just change it to LibreNMS. This would probably break
|
||||
(although if you were on a version between r3250 and the next database
|
||||
schema change, it might be feasible). Upgrades from versions earlier than
|
||||
r3251 might work. Please try it on an unimportant system and tell us your
|
||||
experiences!</del>
|
||||
|
||||
Thanks to one of our users Dan Brown who has written a migration script to be able move your Observium install over to LibreNMS [Dan Brown][10]. This also takes care of moving from one cpu architect to another. Give it a try :)
|
||||
|
||||
@@ -25,11 +17,9 @@ How LibreNMS will be different from Observium:
|
||||
- We will have an inclusive community, where it's OK to ask stupid
|
||||
questions, and OK to ask for things that aren't on the roadmap. If you'd
|
||||
like to see something added, add or comment on the relevant issue in our
|
||||
[GitHub issue database][9].
|
||||
[Community forum][9].
|
||||
- Development decisions will be community-driven. We want to make software
|
||||
that fulfills its users' needs. See the [ROADMAP][4] for more thoughts
|
||||
on our current plans.
|
||||
- <del>Development will probably proceed at a slower pace, at least initially.</del>
|
||||
that fulfills its users' needs.
|
||||
- There are no plans for a paid version, and we don't anticipate this ever
|
||||
changing.
|
||||
- There are no current plans for paid support, but this may be added later
|
||||
@@ -41,7 +31,6 @@ Reasons why you might want to use Observium instead of LibreNMS:
|
||||
|
||||
- You have a financial investment in Observium and aren't concerned about
|
||||
community contributions.
|
||||
- <del>You need functionality that has been added to Observium since r3250.</del> The beauty of LibreNMS is that you can contribute missing features.
|
||||
- You don't like the [GNU General Public License, version 3][5] or the
|
||||
[philosophy of Free Software/copyleft][6] in general.
|
||||
|
||||
@@ -65,9 +54,9 @@ Reasons why you might want to use LibreNMS instead of Observium:
|
||||
"Free Software Foundation - what is free software?"
|
||||
[7]: http://libertysys.com.au/blog/observium-and-gpl
|
||||
"Paul's blog on what the GPL offers users"
|
||||
[8]: https://github.com/librenms/librenms/blob/master/doc/General/Contributing.md
|
||||
[8]: https://docs.librenms.org/General/Contributing/
|
||||
"Contribution guidelines"
|
||||
[9]: https://github.com/librenms/librenms/issues
|
||||
[9]: https://community.librenms.org
|
||||
"LibreNMS issue database at GitHub"
|
||||
[10]: https://vlan50.com/2015/04/17/migrating-from-observium-to-librenms/
|
||||
"Migrating from Observium to LibreNMS"
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
source: Installation/Migrating-from-Observium.md
|
||||
## Migrating from Observium to LibreNMS
|
||||
|
||||
A LibreNMS user, [Dan](https://twitter.com/thedanbrown), has kindly provided full details and scripts to be able to migrate from Observium to LibreNMS.
|
||||
|
||||
|
||||
31
doc/Support/Adding-a-Device.md
Normal file
31
doc/Support/Adding-a-Device.md
Normal file
@@ -0,0 +1,31 @@
|
||||
source: Support/Adding-a-Device.md
|
||||
|
||||
You have two options for adding a new device into LibreNMS. You can add a device via the `cli` or by using the
|
||||
`WebUI`.
|
||||
|
||||
### CLI
|
||||
|
||||
Using the command line via ssh you can add a new device by changing to the directory of your LibreNMS install and typing (be sure to put the correct details).
|
||||
|
||||
```bash
|
||||
./addhost.php [community] [v1|v2c] [port] [udp|udp6|tcp|tcp6]
|
||||
```
|
||||
|
||||
As an example, if your device is configured to use the community `my_company` using snmp `v2c` then you would enter:
|
||||
|
||||
```bash
|
||||
./addhost.php my_company v2c
|
||||
```
|
||||
|
||||
> Please note that if the community contains special characters such as `$` then you will need to wrap it in `'`. I.e: `'Pa$$w0rd'`.
|
||||
|
||||
### WebUI
|
||||
|
||||
Using the web interface, go to Devices and click Add Device. Enter the details required for the device that you want to add and then click 'Add Host'.
|
||||
As an example, if your device is configured to use the community `my_company` using snmp `v2c` then you would enter:
|
||||
|
||||
|
||||
|
||||
If you would like to add devices automatically then you will probably want to read the [Auto-discovery Setup](/Extensions/Auto-Discovery.md) guide.
|
||||
|
||||
You may also want to add devices programatically, if so, take a look at our [API documentation](/API/#function-add_device)
|
||||
@@ -85,7 +85,6 @@ $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;
|
||||
```
|
||||
|
||||
#### OS based Discovery config
|
||||
@@ -200,35 +199,3 @@ The output will contain:
|
||||
DB Updates
|
||||
|
||||
SNMP Response
|
||||
|
||||
### 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.
|
||||
|
||||
Using the SNMP-Scanner may take a long time to finish depending on the size of your network. Tests have shown that a sparsely-populated /24 is scanned within 2 Minutes whereas a sparsely populated /16 will take about 11 Hours.
|
||||
|
||||
If possible, divide your network into smaller subnets and scan these subnets instead. You can use an utility like the GNU Screen or tmux to avoid aborting the scan when logging out of your Shell. You can run several instances of the SNMP-Scanner simultaneously.
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
|
||||
BIN
doc/img/device_groups.png
Normal file
BIN
doc/img/device_groups.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
BIN
doc/img/webui_add_device.png
Normal file
BIN
doc/img/webui_add_device.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 136 KiB |
@@ -10,6 +10,7 @@ $stage = isset($_POST['stage']) ? $_POST['stage'] : 0;
|
||||
|
||||
// Before we do anything, if we see config.php, redirect back to the homepage.
|
||||
if (file_exists('../config.php') && $stage != 6) {
|
||||
unset($_SESSION['stage']);
|
||||
header("Location: /");
|
||||
exit;
|
||||
}
|
||||
|
||||
105
mkdocs.yml
105
mkdocs.yml
@@ -1,6 +1,6 @@
|
||||
site_name: LibreNMS Docs
|
||||
docs_dir: doc
|
||||
theme_dir: 'librenms_theme'
|
||||
theme_dir: 'theme_v2'
|
||||
theme: null
|
||||
site_dir: out
|
||||
site_url: http://docs.librenms.org
|
||||
@@ -9,7 +9,6 @@ markdown_extensions:
|
||||
- pymdownx.tilde
|
||||
extra_css:
|
||||
- librenms.css
|
||||
include_next_prev: false
|
||||
site_author: LibreNMS
|
||||
site_description: LibreNMS user and developer documentation
|
||||
repo_url: https://github.com/librenms/librenms
|
||||
@@ -17,18 +16,13 @@ repo_name: GitHub
|
||||
google_analytics: ['UA-79149977-2', 'docs.librenms.org']
|
||||
pages:
|
||||
- Home: index.md
|
||||
- General:
|
||||
- General/Acknowledgement.md
|
||||
- General/Callback-Stats-and-Privacy.md
|
||||
- 1. General:
|
||||
- Acknowledgements: General/Acknowledgement.md
|
||||
- General/Changelog.md
|
||||
- Code of Conduct: General/CODE_OF_CONDUCT.md
|
||||
- General/Contributing.md
|
||||
- General/Credits.md
|
||||
- General/Updating.md
|
||||
- General/Releases.md
|
||||
- General/Security.md
|
||||
- Support/Features.md
|
||||
- General/Welcome-to-Observium-users.md
|
||||
- Installation:
|
||||
- 2. Installing:
|
||||
- Installing LibreNMS: Installation/Installing-LibreNMS.md
|
||||
- Ubuntu VM Image: Installation/Ubuntu-image.md
|
||||
- CentOS VM Image: Installation/CentOS-image.md
|
||||
@@ -36,72 +30,85 @@ pages:
|
||||
- Ubuntu 16.04 (Apache): Installation/Installation-Ubuntu-1604-Apache.md
|
||||
- CentOS 7 (Nginx): Installation/Installation-CentOS-7-Nginx.md
|
||||
- CentOS 7 (Apache): Installation/Installation-CentOS-7-Apache.md
|
||||
- Older Docs: Installation/Installing-LibreNMS.md
|
||||
- Migrating from Observium: Installation/Migrating-from-Observium.md
|
||||
- Extensions:
|
||||
- 3. Getting started:
|
||||
- Choosing a release: General/Releases.md
|
||||
- Adding a device: Support/Adding-a-Device.md
|
||||
- Grouping Devices: Extensions/Device-Groups.md
|
||||
- Submitting stats: General/Callback-Stats-and-Privacy.md
|
||||
- Updating an install: General/Updating.md
|
||||
- 4. Basic Setup:
|
||||
- Extensions/Applications.md
|
||||
- Extensions/Authentication.md
|
||||
- Extensions/Auto-Discovery.md
|
||||
- Extensions/Agent-Setup.md
|
||||
- Check_MK Setup: Extensions/Agent-Setup.md
|
||||
- Extensions/Billing-Module.md
|
||||
- Extensions/Component.md
|
||||
- Extensions/Dell-OpenManage.md
|
||||
- Extensions/Device-Groups.md
|
||||
- Extensions/Distributed-Poller.md
|
||||
- Extensions/Email-Alerting.md
|
||||
- Extensions/Globe-Frontpage.md
|
||||
- Extensions/Graylog.md
|
||||
- Extensions/Interface-Description-Parsing.md
|
||||
- Extensions/Network-Map.md
|
||||
- Extensions/Syslog.md
|
||||
- 5. Advanced Setup:
|
||||
- Support/1-Minute-Polling.md
|
||||
- Configuration docs: Support/Configuration.md
|
||||
- Authentication Options: Extensions/Authentication.md
|
||||
- Two-Factor Auth: Extensions/Two-Factor-Auth.md
|
||||
- Auto-discovery Setup: Extensions/Auto-Discovery.md
|
||||
- Scaling LibreNMS: Extensions/Distributed-Poller.md
|
||||
- Extensions/RRDCached.md
|
||||
- Memcached Config: Extensions/Memcached.md
|
||||
- Sub-directory Support: Extensions/Sub-Directory.md
|
||||
- Extensions/Varnish.md
|
||||
- Poller Service (BETA): Extensions/Poller-Service.md
|
||||
- Extensions/RRDTune.md
|
||||
- Extensions/IRC-Bot.md
|
||||
- Extensions/IRC-Bot-Extensions.md
|
||||
- Extensions/Interface-Description-Parsing.md
|
||||
- Extensions/MIB-based-polling.md
|
||||
- Extensions/Memcached.md
|
||||
- Extensions/Metric-Storage.md
|
||||
- Extensions/Network-Map.md
|
||||
- Extensions/SNMP-Proxy.md
|
||||
- Extensions/SNMP-Trap-Handler.md
|
||||
- 6. 3rd Party Integration:
|
||||
- Extensions/Graylog.md
|
||||
- Nagios Plugins: Extensions/Services.md
|
||||
- Extensions/NFSen.md
|
||||
- Extensions/Oxidized.md
|
||||
- Extensions/PeeringDB.md
|
||||
- Extensions/Plugin-System.md
|
||||
- Extensions/Poller-Service.md
|
||||
- Extensions/Port-Description-Parser.md
|
||||
- Extensions/Proxmox.md
|
||||
- Extensions/RRDCached.md
|
||||
- Extensions/RRDTune.md
|
||||
- Extensions/SNMP-Proxy.md
|
||||
- Extensions/SNMP-Trap-Handler.md
|
||||
- Extensions/Services.md
|
||||
- Storing Metrics: Extensions/Metric-Storage.md
|
||||
- Extensions/Smokeping.md
|
||||
- Extensions/Sub-Directory.md
|
||||
- Extensions/Syslog.md
|
||||
- Extensions/Two-Factor-Auth.md
|
||||
- Extensions/Varnish.md
|
||||
- API: API/index.md
|
||||
- Alerting: Alerting/index.md
|
||||
- Support:
|
||||
- Support/1-Minute-Polling.md
|
||||
- Support/Configuration.md
|
||||
- Support/Discovery Support.md
|
||||
- Support/Example-Hardware-Setup.md
|
||||
- 7. API:
|
||||
- API/index.md
|
||||
- 8. Alerting:
|
||||
- Alerting/Rules.md
|
||||
- Alerting/Templates.md
|
||||
- Alerting/Transports.md
|
||||
- Alerting/Entities.md
|
||||
- Alerting/Macros.md
|
||||
- Alerting/Testing.md
|
||||
- 9. Getting help:
|
||||
- Support/FAQ.md
|
||||
- Support/Features.md
|
||||
- Support/Install Validation.md
|
||||
- Support/Performance.md
|
||||
- Support/Discovery Support.md
|
||||
- Support/Poller Support.md
|
||||
- Support/Example-Hardware-Setup.md
|
||||
- Support/Remote-Monitoring-VPN.md
|
||||
- Support/SNMP-Configuration-Examples.md
|
||||
- Support/SSL-Configuration.md
|
||||
- Developing:
|
||||
- 10. Contributing + Developing:
|
||||
- General/Contributing.md
|
||||
- Developing/Using-Git.md
|
||||
- Developing/Code-Guidelines.md
|
||||
- Developing/Style-Guidelines.md
|
||||
- Developing/Validating-Code.md
|
||||
- Developing/Code-Structure.md
|
||||
- Developing/Creating-Documentation.md
|
||||
- Extensions/Component.md
|
||||
- Mib Based Polling (ALPHA): Extensions/MIB-based-polling.md
|
||||
- Adding support for a new OS: Developing/Support-New-OS.md
|
||||
- Developing/Dynamic-Config.md
|
||||
- Developing/Sensor-State-Support.md
|
||||
- Developing/Merging-Pull-Requests.md
|
||||
- Developing/Creating-Release.md
|
||||
- Extensions/Plugin-System.md
|
||||
- 11. Misc:
|
||||
- Security information: General/Security.md
|
||||
- hidden:
|
||||
- Alerting/Rules.md
|
||||
- Alerting/Templates.md
|
||||
@@ -118,10 +125,13 @@ pages:
|
||||
- Developing/os/Settings.md
|
||||
- Extensions/Agent-Setup.md
|
||||
- Extensions/Alerting.md
|
||||
- Extensions/Email-Alerting.md
|
||||
- Extensions/metrics/InfluxDB.md
|
||||
- Extensions/metrics/Graphite.md
|
||||
- Extensions/metrics/OpenTSDB.md
|
||||
- Parsing Port Descriptions: Extensions/Port-Description-Parser.md
|
||||
- Extensions/RRDCached-Security.md
|
||||
- General/Credits.md
|
||||
- Installation/Installation-Ubuntu-1404-Nginx.md
|
||||
- Installation/Installation-Ubuntu-1404-Apache.md
|
||||
- Installation/Installation-Ubuntu-1404-Lighttpd.md
|
||||
@@ -129,3 +139,4 @@ pages:
|
||||
- Installation/Installation-(Debian-Ubuntu).md
|
||||
- Installation/Installation-(RHEL-CentOS).md
|
||||
- Support/Support-New-OS.md
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
#!/usr/bin/env bash
|
||||
GH_REPO="@github.com/librenms-docs/librenms-docs.github.io.git"
|
||||
FULL_REPO="https://${GH_TOKEN}$GH_REPO"
|
||||
THEME_REPO="https://github.com/librenms-docs/librenms_theme.git"
|
||||
THEME_REPO="https://github.com/librenms-docs/theme_v2.git"
|
||||
|
||||
pip install --user 'jinja2<2.9'
|
||||
pip install --user mkdocs
|
||||
|
||||
Reference in New Issue
Block a user