opensourcemirror
/
LibreNMS
mirror of https://github.com/librenms/librenms.git
1
0
Fork 0
Code Releases Activity

docs: more md linting (#10371) 

* clean 1-Minute-Polling.md formatting

* cleanup formatting for Adding-a-Device.md

* clean up formatting of Cleanup-options.md

* cleanup formatting some for CLI-Tools.md

* cleanup formatting for Syslog.md and Configuration.md

* cleanup formatting for Device-Sensors.md

* cleanup formatting for Device-Troubleshooting.md

* cleanup Discovery Support.md

* cleanup Environment-Variables.md

* cleanup Example-Hardware-Setup.md and FAQ.mg

* update Features.md, Install Validation.md, Perfermance.md, Poller Support.md, and index.md

* cleanup Remote-Monitoring-VPN.md, SNMP-Configuration-Examples.md, and SSL-Configuration.md

* lots of updates for Installation docs

* more installation doc cleanup

* more formatting cleanup

* clean Work-Map.md up some
This commit is contained in:
VVelox 2019-07-18 21:25:53 -05:00 committed by Tony Murray
parent cfdd23d2c2
commit 06b85f5b07
45 changed files with 3650 additions and 1801 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
doc/Extensions/Syslog.md
View File

@ -1,25 +1,30 @@
source: Extensions/Syslog.md
path: blob/master/doc/
# Setting up syslog support
This document will explain how to send syslog data to LibreNMS.
Please also refer to the file Graylog.md for an alternate way of integrating syslog with LibreNMS.
Please also refer to the file Graylog.md for an alternate way of
integrating syslog with LibreNMS.
### Syslog server installation
## Syslog server installation
#### syslog-ng
### syslog-ng
For Debian / Ubuntu:
```ssh
apt-get install syslog-ng
```
For CentOS / RedHat
```ssh
yum install syslog-ng
```
Once syslog-ng is installed, edit the relevant config file (most likely /etc/syslog-ng/syslog-ng.conf) and paste the following:
Once syslog-ng is installed, edit the relevant config file (most
likely /etc/syslog-ng/syslog-ng.conf) and paste the following:
```bash
@version:3.5
@ -47,18 +52,15 @@ options {
bad_hostname("^gconfd$");
};
source s_sys {
system();
internal();
};
source s_net {
tcp(port(514) flags(syslog-protocol));
udp(port(514) flags(syslog-protocol));
};
########################
# Destinations
@ -109,11 +111,13 @@ Add the following to your LibreNMS `config.php` file to enable the Syslog extens
$config['enable_syslog'] = 1;
```
#### rsyslog
### rsyslog
If you prefer rsyslog, here are some hints on how to get it working.
Add the following to your rsyslog config somewhere (could be at the top of the file in the step below, could be in `rsyslog.conf` if you are using remote logs for something else on this host)
Add the following to your rsyslog config somewhere (could be at the
top of the file in the step below, could be in `rsyslog.conf` if you
are using remote logs for something else on this host)
```
# Listen for syslog messages on UDP:514
@ -138,6 +142,7 @@ $template librenms,"%fromhost%||%syslogfacility%||%syslogpriority%||%syslogsever
Ancient versions of rsyslog may require different syntax.
This is an example for rsyslog 5 (default on Debian 7):
```bash
# Feed syslog messages to librenms
$ModLoad omprog
@ -147,7 +152,12 @@ $ActionOMProgBinary /opt/librenms/syslog.php
*.* :omprog:;librenms
```
If your rsyslog server is recieving messages relayed by another syslog server, you may try replacing `%fromhost%` with `%hostname%`, since `fromhost` is the host the message was received from, not the host that generated the message. The `fromhost` property is preferred as it avoids problems caused by devices sending incorrect hostnames in syslog messages.
If your rsyslog server is recieving messages relayed by another syslog
server, you may try replacing `%fromhost%` with `%hostname%`, since
`fromhost` is the host the message was received from, not the host
that generated the message. The `fromhost` property is preferred as
it avoids problems caused by devices sending incorrect hostnames in
syslog messages.
Add the following to your LibreNMS `config.php` file to enable the Syslog extension:
@ -155,9 +165,10 @@ Add the following to your LibreNMS `config.php` file to enable the Syslog extens
$config['enable_syslog'] = 1;
```
#### logstash
### logstash
If you prefer logstash, and it is installed on the same server as LibreNMS, here are some hints on how to get it working.
If you prefer logstash, and it is installed on the same server as
LibreNMS, here are some hints on how to get it working.
First, install the output-exec plugin for logstash:
@ -165,7 +176,9 @@ First, install the output-exec plugin for logstash:
/usr/share/logstash/bin/logstash-plugin install logstash-output-exec
```
Next, create a logstash configuration file (ex. /etc/logstash/conf.d/logstash-simple.conf), and add the following:
Next, create a logstash configuration file
(ex. /etc/logstash/conf.d/logstash-simple.conf), and add the
following:
```
input {
@ -186,7 +199,10 @@ output {
}
```
Replace 10.10.10.10 with your primary elasticsearch server IP, and set the incoming syslog port. Alternatively, if you already have a logstash config file that works except for the LibreNMS export, take only the "exec" section from output and add it.
Replace 10.10.10.10 with your primary elasticsearch server IP, and set
the incoming syslog port. Alternatively, if you already have a
logstash config file that works except for the LibreNMS export, take
only the "exec" section from output and add it.
Add the following to your LibreNMS `config.php` file to enable the Syslog extension:
@ -194,34 +210,43 @@ Add the following to your LibreNMS `config.php` file to enable the Syslog extens
$config['enable_syslog'] = 1;
```
#### Syslog Clean Up
# Syslog Clean Up
Can be set inside of `config.php`
```php
$config['syslog_purge'] = 30;
```
The cleanup is run by daily.sh and any entries over X days old are automatically purged. Values are in days.
See here for more Clean Up Options [Link](https://docs.librenms.org/#Support/Configuration/#cleanup-options)
### Client configuration
The cleanup is run by daily.sh and any entries over X days old are
automatically purged. Values are in days. See here for more Clean Up
Options
[Link](https://docs.librenms.org/#Support/Configuration/#cleanup-options)
Below are sample configurations for a variety of clients. You should understand the config before using it as you may want to make some slight changes.
Further configuration hints may be found in the file Graylog.md.
# Client configuration
Below are sample configurations for a variety of clients. You should
understand the config before using it as you may want to make some
slight changes. Further configuration hints may be found in the file Graylog.md.
Replace librenms.ip with IP or hostname of your LibreNMS install.
Replace any variables in <brackets> with the relevant information.
#### syslog
## syslog
```config
*.* @librenms.ip
```
#### rsyslog
## rsyslog
```config
*.* @librenms.ip:514
```
#### Cisco ASA
## Cisco ASA
```config
logging enable
logging timestamp
@ -231,19 +256,22 @@ logging trap notifications
logging host <outside interface name> librenms.ip
```
#### Cisco IOS
## Cisco IOS
```config
logging trap debugging
logging facility local6
logging librenms.ip
```
#### Cisco NXOS
## Cisco NXOS
```config
logging server librenms.ip 5 use-vrf default facility local6
```
#### Juniper Junos
## Juniper Junos
```config
set system syslog host librenms.ip authorization any
set system syslog host librenms.ip daemon any
@ -255,7 +283,8 @@ set system syslog host librenms.ip exclude-hostname
set system syslog time-format
```
#### Huawei VRP
## Huawei VRP
```config
info-center loghost librenms.ip
info-center timestamp debugging short-date without-timezone // Optional
@ -270,13 +299,15 @@ info-center filter-id bymodule-alias SNMP SNMP_IPUNLOCK
info-center filter-id bymodule-alias HTTP ACL_DENY
```
#### Huawei SmartAX (GPON OLT)
## Huawei SmartAX (GPON OLT)
```config
loghost add librenms.ip librenms
loghost activate name librenms
```
#### Allied Telesis Alliedware Plus
## Allied Telesis Alliedware Plus
```config
log date-format iso // Required so syslog-ng/LibreNMS can correctly interpret the log message formatting.
log host x.x.x.x
@ -286,79 +317,103 @@ log host x.x.x.x level notices program imi // Required for Oxidized Syslog hook
log host source <eth0>
```
If you have permitted udp and tcp 514 through any firewall then that
should be all you need. Logs should start appearing and displayed
within the LibreNMS web UI.
If you have permitted udp and tcp 514 through any firewall then that should be all you need. Logs should start appearing and displayed within the LibreNMS web UI.
### Windows
## Windows
By Default windows has no native way to send logs to a remote syslog server.
Using this how to you can download Datagram-Syslog Agent to send logs to a remote syslog server (LibreNMS).
Using this how to you can download Datagram-Syslog Agent to send logs
to a remote syslog server (LibreNMS).
#### Note
keep in mind you can use any agent or program to send the logs. We are just using this Datagram-Syslog Agent for this example.
#### Note
Keep in mind you can use any agent or program to send the logs. We are
just using this Datagram-Syslog Agent for this example.
[Link to How to](http://techgenix.com/configuring-syslog-agent-windows-server-2012/)
You will need to download and install "Datagram-Syslog Agent" for this how to
[Link to Download](http://download.cnet.com/Datagram-SyslogAgent/3001-2085_4-10370938.html)
# External hooks
### External hooks
Trigger external scripts based on specific syslog patterns being matched with syslog hooks. Add the following to your LibreNMS `config.php` to enable hooks:
Trigger external scripts based on specific syslog patterns being
matched with syslog hooks. Add the following to your LibreNMS
`config.php` to enable hooks:
```ssh
$config['enable_syslog_hooks'] = 1;
```
The below are some example hooks to call an external script in the event of a configuration change on Cisco ASA, IOS, NX-OS and IOS-XR devices. Add to your `config.php` file to enable.
The below are some example hooks to call an external script in the
event of a configuration change on Cisco ASA, IOS, NX-OS and IOS-XR
devices. Add to your `config.php` file to enable.
## Cisco ASA
#### Cisco ASA
```ssh
$config['os']['asa']['syslog_hook'][] = Array('regex' => '/%ASA-(config-)?5-111005/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
```
#### Cisco IOS
## Cisco IOS
```ssh
$config['os']['ios']['syslog_hook'][] = Array('regex' => '/%SYS-(SW[0-9]+-)?5-CONFIG_I/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
```
#### Cisco NXOS
## Cisco NXOS
```ssh
$config['os']['nxos']['syslog_hook'][] = Array('regex' => '/%VSHD-5-VSHD_SYSLOG_CONFIG_I/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
```
#### Cisco IOSXR
## Cisco IOSXR
```ssh
$config['os']['iosxr']['syslog_hook'][] = Array('regex' => '/%GBL-CONFIG-6-DB_COMMIT/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
```
#### Juniper Junos
## Juniper Junos
```ssh
$config['os']['junos']['syslog_hook'][] = Array('regex' => '/UI_COMMIT:/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
```
#### Juniper ScreenOS
## Juniper ScreenOS
```ssh
$config['os']['screenos']['syslog_hook'][] = Array('regex' => '/System configuration saved/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
```
#### Allied Telesis Alliedware Plus
**Note:** At least software version 5.4.8-2.1 is required. `log host x.x.x.x level notices program imi` may also be required depending on configuration. This is to ensure the syslog hook log message gets sent to the syslog server.
## Allied Telesis Alliedware Plus
**Note:** At least software version 5.4.8-2.1 is required. `log host
x.x.x.x level notices program imi` may also be required depending on
configuration. This is to ensure the syslog hook log message gets sent
to the syslog server.
```ssh
$config['os']['awplus']['syslog_hook'][] = Array('regex' => '/IMI.+.Startup-config saved on/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php');
```
### Configuration Options
# Configuration Options
#### Matching syslogs to hosts with different names
## Matching syslogs to hosts with different names
In some cases, you may get logs that aren't being associated with the device in LibreNMS. For example, in LibreNMS the device is known as "ne-core-01", and that's how DNS resolves. However, the received syslogs are for "loopback.core-nw".
In some cases, you may get logs that aren't being associated with the
device in LibreNMS. For example, in LibreNMS the device is known as
"ne-core-01", and that's how DNS resolves. However, the received
syslogs are for "loopback.core-nw".
To fix this issue, you can configure LibreNMS to translate the incoming syslog hostname into another hostname, so that the logs get associated with the correct device.
To fix this issue, you can configure LibreNMS to translate the
incoming syslog hostname into another hostname, so that the logs get
associated with the correct device.
Example:
```ssh
$config['syslog_xlate'] = array(
'loopback0.core7k1.noc.net' => 'n7k1-core7k1',

54
doc/Extensions/World-Map.md
View File

@ -1,19 +1,26 @@
source: Extensions/World-Map.md
path: blob/master/doc/
# World Map Configuration
LibreNMS comes with a configurable Geo Map based on World Map Widget to visualize where your equipment is located geographically.
LibreNMS comes with a configurable Geo Map based on World Map Widget
to visualize where your equipment is located geographically.
### World Map Widget
# World Map Widget
World Map Widget, requires you to have properly formatted addresses in sysLocation or sysLocation override. As part of the standard poller these addresses will be Geocoded by Google and stored in the database.
World Map Widget, requires you to have properly formatted addresses in
sysLocation or sysLocation override. As part of the standard poller
these addresses will be Geocoded by Google and stored in the database.
Location resolution happens as follows
1. If `device['location']` contains `[lat, lng]` (note the square brackets), that is used
1. If there is a location overide for the device in the WebUI and it contains `[lat, lng]` (note the square brackets), that is used.
1. If `device['location']` contains `[lat, lng]` (note the square
brackets), that is used
1. If there is a location overide for the device in the WebUI and it
contains `[lat, lng]` (note the square brackets), that is used.
1. Attempt to resolve lat, lng using `$config['geoloc']['engine']`
1. Properly formatted addresses in sysLocation or sysLocation override, under device settings.
1. Properly formatted addresses in sysLocation or sysLocation
override, under device settings.
Example:
@ -23,32 +30,37 @@ or
1100 Congress Ave, Austin, TX 78701
We have two current mapping engines available:
- Leaflet (default)
- Jquery-Mapael
# World Map Widget Settings
### World Map Widget Settings
- *Initial Latitude / Longitude*: The map will be centered on those coordinates.
- *Initial Zoom*: Initial zoom of the map. [More information about zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels).
- *Grouping radius*: Markers are grouped by area. This value define the maximum size of grouping areas.
- *Initial Latitude / Longitude*: The map will be centered on those
coordinates.
- *Initial Zoom*: Initial zoom of the map. [More information about
zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels).
- *Grouping radius*: Markers are grouped by area. This value define
the maximum size of grouping areas.
- *Show devices*: Show devices based on there status.
Example Settings:
![Example World Map Settings](/img/world-map-widget-settings.png)
# Offline OpenStreet Map
### Offline OpenStreet Map
If you can't access OpenStreet map directly you can run a local [tile server](http://wiki.openstreetmap.org/wiki/Tile_servers). To specify a different url you can set:
If you can't access OpenStreet map directly you can run a local [tile
server](http://wiki.openstreetmap.org/wiki/Tile_servers). To specify a
different url you can set:
```php
$config['leaflet']['tile_url'] = 'localhost.com';
```
### Additional Leaflet config
# Additional Leaflet config
```php
$config['map']['engine'] = "leaflet";
$config['leaflet']['default_lat'] = "51.981074";
@ -57,11 +69,13 @@ $config['leaflet']['default_zoom'] = 8;
$config['leaflet']['group_radius'] = 1; // Device grouping radius in KM default 80KM
```
### Geocode engine config
# Geocode engine config
```php
$config['geoloc']['engine'] = "google";// Valid options are google, mapquest or bing
$config['geoloc']['api_key'] = "abcdefghijklmnopqrstuvwxyz";
```
Google:
Pros: fast, accurate
Cons: requires a credit card even for a free account
@ -75,9 +89,11 @@ Pros: free, no credit card required, accurate
Cons: Microsoft(debatable)
### Jquery-Mapael config
Further custom options are available to load different maps of the world, set default coordinates of where the map will zoom and the zoom level by default. An example of
this is:
# Jquery-Mapael config
Further custom options are available to load different maps of the
world, set default coordinates of where the map will zoom and the zoom
level by default. An example of this is:
```php
$config['map']['engine'] = "jquery-mapael";

35
doc/Extensions/metrics/Graphite.md
View File

@ -1,15 +1,21 @@
source: Extensions/metrics/Graphite.md
path: blob/master/doc/
# Enabling support for Graphite.
This module sends all metrics to a remote graphite service. You need something like Grafana for graphing.
# Enabling support for Graphite
### What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to build your own graphs within Grafana.
This module sends all metrics to a remote graphite service. You need
something like Grafana for graphing.
RRD will continue to function as normal so LibreNMS itself should continue to function as normal.
# What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
RRD will continue to function as normal so LibreNMS itself should
continue to function as normal.
# Configuration
### Configuration
```php
$config['graphite']['enable'] = true;
$config['graphite']['host'] = 'your.graphite.server';
@ -17,14 +23,19 @@ $config['graphite']['port'] = 2003; // this defaults to 2003 and is usually not
$config['graphite']['prefix'] = 'your.metric.prefix';
```
Your metric path can be prefixed if required, otherwise the metric path for Graphite will be in the form of
`hostname.measurement.fieldname`, interfaces will be stored as `hostname.ports.ifName.fieldname`.
Your metric path can be prefixed if required, otherwise the metric
path for Graphite will be in the form of
`hostname.measurement.fieldname`, interfaces will be stored as
`hostname.ports.ifName.fieldname`.
The same data then stored within rrd will be sent to Graphite and recorded. You can then create graphs within Grafana
to display the information you need.
The same data then stored within rrd will be sent to Graphite and
recorded. You can then create graphs within Grafana to display the
information you need.
### Graphite Configuration
As LibreNMS updates its metrics every 5 minutes, the following addition to your storage-schemas.conf is suggested.
# Graphite Configuration
As LibreNMS updates its metrics every 5 minutes, the following
addition to your storage-schemas.conf is suggested.
```
[network]

46
doc/Extensions/metrics/InfluxDB.md
View File

@ -1,27 +1,36 @@
source: Extensions/metrics/InfluxDB.md
path: blob/master/doc/
# Enabling support for InfluxDB.
Before we get started it is important that you know and understand that InfluxDB support is currently alpha at best.
All it provides is the sending of data to a InfluxDB install. Due to the current changes that are constantly being
made to InfluxDB itself then we cannot guarantee that your data will be ok so enabling this support is at your own
risk!
# Enabling support for InfluxDB
### Requirements
- InfluxDB >= 0.94
- Grafana
- PHP 5.5 for InfluxDB-PHP
Before we get started it is important that you know and understand
that InfluxDB support is currently alpha at best. All it provides is
the sending of data to a InfluxDB install. Due to the current changes
that are constantly being made to InfluxDB itself then we cannot
guarantee that your data will be ok so enabling this support is at
your own risk!
The setup of the above is completely out of scope here and we aren't really able to provide any help with this side
of things.
# Requirements
### What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to build your own graphs within Grafana.
- Support for InfluxDB or Grafana, we would highly recommend that you have some level of experience with these.
- InfluxDB >= 0.94
- Grafana
- PHP 5.5 for InfluxDB-PHP
RRD will continue to function as normal so LibreNMS itself should continue to function as normal.
The setup of the above is completely out of scope here and we aren't
really able to provide any help with this side of things.
# What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
- Support for InfluxDB or Grafana, we would highly recommend that you
have some level of experience with these.
RRD will continue to function as normal so LibreNMS itself should
continue to function as normal.
# Configuration
### Configuration
```php
$config['influxdb']['enable'] = true;
$config['influxdb']['transport'] = 'http'; # Default, other options: https, udp
@ -36,5 +45,6 @@ $config['influxdb']['verifySSL'] = false; # Optional
No credentials are needed if you don't use InfluxDB authentication.
The same data then stored within rrd will be sent to InfluxDB and recorded. You can then create graphs within Grafana
to display the information you need.
The same data then stored within rrd will be sent to InfluxDB and
recorded. You can then create graphs within Grafana to display the
information you need.

32
doc/Extensions/metrics/OpenTSDB.md
View File

@ -1,20 +1,28 @@
source: Extensions/metrics/OpenTSDB.md
path: blob/master/doc/
# Enabling support for OpenTSDB.
This module sends all metrics to OpenTSDB server. You need something like Grafana for graphing.
# Enabling support for OpenTSDB
### Requirements
- OpenTSDB
- Grafana
This module sends all metrics to OpenTSDB server. You need something
like Grafana for graphing.
# Requirements
- OpenTSDB
- Grafana
# What you don't get
Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
### What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to build your own graphs within Grafana.
RRD will continue to function normally so LibreNMS itself should continue to function normally.
RRD will continue to function normally so LibreNMS itself should
continue to function normally.
You can add the following to `config.php`.
### Configuration
# Configuration
```php
// OpenTSDB default configuration
$config['opentsdb']['enable'] = true;
@ -22,4 +30,6 @@ $config['opentsdb']['host'] = '127.0.0.1'; // your OpenTSDB server
$config['opentsdb']['port'] = 4242;
```
The same data than the one stored within rrd will be sent to OpenTSDB and recorded. You can then create graphs within Grafana to display the information you need.
The same data than the one stored within rrd will be sent to OpenTSDB
and recorded. You can then create graphs within Grafana to display the
information you need.

47
doc/Extensions/metrics/Prometheus.md
View File

@ -1,35 +1,43 @@
source: Extensions/metrics/Prometheus.md
path: blob/master/doc/
# Enabling support for Prometheus.
Please be aware Prometheus support is alpha at best, It hasn't been extensively tested and is still in development
All it provides is the sending of data to a a Prometheus PushGateway. Please be careful when enabling this support
you use it at your own risk!
# Enabling support for Prometheus
### Requirements (Older versions may work but haven't been tested
- Prometheus >= 2.0
- PushGateway >= 0.4.0
- Grafana
- PHP-CURL
Please be aware Prometheus support is alpha at best, It hasn't been
extensively tested and is still in development All it provides is the
sending of data to a a Prometheus PushGateway. Please be careful when
enabling this support you use it at your own risk!
The setup of the above is completely out of scope here and we aren't really able to provide any help with this side
of things.
# Requirements (Older versions may work but haven't been tested
### What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to build your own graphs within Grafana.
- Support for Prometheus or Grafana, we would highly recommend that you have some level of experience with these.
- Prometheus >= 2.0
- PushGateway >= 0.4.0
- Grafana
- PHP-CURL
RRD will continue to function as normal so LibreNMS itself should continue to function as normal.
The setup of the above is completely out of scope here and we aren't
really able to provide any help with this side of things.
# What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
- Support for Prometheus or Grafana, we would highly recommend that
you have some level of experience with these.
RRD will continue to function as normal so LibreNMS itself should
continue to function as normal.
# Configuration
### Configuration
```php
$config['prometheus']['enable'] = true;
$config['prometheus']['url'] = 'http://127.0.0.1:9091';
$config['prometheus']['job'] = 'librenms'; # Optional
```
# Sample Prometheus Scrape Config (for scraping the Push Gateway)
### Sample Prometheus Scrape Config (for scraping the Push Gateway)
```yml
- job_name: pushgateway
scrape_interval: 300s
@ -38,5 +46,6 @@ $config['prometheus']['job'] = 'librenms'; # Optional
- targets: ['127.0.0.1:9091']
```
The same data then stored within rrd will be sent to Prometheus and recorded. You can then create graphs within Grafana
to display the information you need.
The same data then stored within rrd will be sent to Prometheus and
recorded. You can then create graphs within Grafana to display the
information you need.

98
doc/General/Acknowledgement.md
View File

@ -3,54 +3,60 @@ path: blob/master/doc/
path: blob/master/doc/
LibreNMS wouldn'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.
We list below what we make use of including the license compliance.
## 3rd Party GPLv3 Compliant
# 3rd Party GPLv3 Compliant
- [Bootstrap](http://getbootstrap.com/): MIT
- [Font Awesome](http://fontawesome.io/icons/): MIT License
- [Jquery Bootgrid](http://www.jquery-bootgrid.com/): MIT License
- [Pace](https://github.com/HubSpot/pace): Open License
- [Twitter typeahead](https://github.com/corejavascript/typeahead.js): Open License
- [Vis](http://visjs.org/): MIT / Apache 2.0
- [TCPDF](http://www.tcpdf.org): LGPLv3
- [Bootstrap 3 Datepicker](http://eonasdan.github.io/bootstrap-datetimepicker/): MIT
- [Bootstrap Dropdown Hover Plugin](https://github.com/CWSpear/bootstrap-hover-dropdown): MIT
- [Bootstrap Switch ](http://www.bootstrap-switch.org/): Apache 2.0
- [Handlebars](http://handlebarsjs.com/): Open License
- [Cycle2](http://jquery.malsup.com/cycle2/): MIT/GPL
- [Jquery](https://jquery.com/): MIT
- [Jquery UI](https://jqueryui.com/): MIT
- [Jquery QRCode](http://larsjung.de/jquery-qrcode/): MIT
- [Mktree](http://www.mattkruse.com/javascript/mktree/): Open License
- [Moment](http://momentjs.com/): MIT
- [Tag Manager](http://soliantconsulting.github.io/tagmanager/): MIT
- [TW Sack](https://code.google.com/p/tw-sack/): GPLv3
- [Gridster](http://gridster.net/): MIT
- [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
- [Confluence HTTP Authenticator](https://github.com/chauth/confluence_http_authenticator)
- [Graylog SSO Authentication Plugin](https://github.com/Graylog2/graylog-plugin-auth-sso)
- [Select2](https://select2.org): MIT License
- [JustGage](http://justgage.com): MIT
- [jQuery.extendext](https://github.com/mistic100/jQuery.extendext): MIT
- [doT](https://github.com/olado/doT): MIT
- [jQuery-queryBuilder](https://github.com/mistic100/jQuery-QueryBuilder/): MIT
- [sql-parser](https://github.com/mistic100/sql-parser/): MIT (Currently a custom build is used)
- [Bootstrap](http://getbootstrap.com/): MIT
- [Font Awesome](http://fontawesome.io/icons/): MIT License
- [Jquery Bootgrid](http://www.jquery-bootgrid.com/): MIT License
- [Pace](https://github.com/HubSpot/pace): Open License
- [Twitter typeahead](https://github.com/corejavascript/typeahead.js): Open License
- [Vis](http://visjs.org/): MIT / Apache 2.0
- [TCPDF](http://www.tcpdf.org): LGPLv3
- [Bootstrap 3
Datepicker](http://eonasdan.github.io/bootstrap-datetimepicker/):
MIT
- [Bootstrap Dropdown Hover
Plugin](https://github.com/CWSpear/bootstrap-hover-dropdown): MIT
- [Bootstrap Switch](http://www.bootstrap-switch.org/): Apache 2.0
- [Handlebars](http://handlebarsjs.com/): Open License
- [Cycle2](http://jquery.malsup.com/cycle2/): MIT/GPL
- [Jquery](https://jquery.com/): MIT
- [Jquery UI](https://jqueryui.com/): MIT
- [Jquery QRCode](http://larsjung.de/jquery-qrcode/): MIT
- [Mktree](http://www.mattkruse.com/javascript/mktree/): Open License
- [Moment](http://momentjs.com/): MIT
- [Tag Manager](http://soliantconsulting.github.io/tagmanager/): MIT
- [TW Sack](https://code.google.com/p/tw-sack/): GPLv3
- [Gridster](http://gridster.net/): MIT
- [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
- [Confluence HTTP Authenticator](https://github.com/chauth/confluence_http_authenticator)
- [Graylog SSO Authentication Plugin](https://github.com/Graylog2/graylog-plugin-auth-sso)
- [Select2](https://select2.org): MIT License
- [JustGage](http://justgage.com): MIT
- [jQuery.extendext](https://github.com/mistic100/jQuery.extendext): MIT
- [doT](https://github.com/olado/doT): MIT
- [jQuery-queryBuilder](https://github.com/mistic100/jQuery-QueryBuilder/): MIT
- [sql-parser](https://github.com/mistic100/sql-parser/): MIT
(Currently a custom build is used)
## 3rd Party GPLv3 Non-compliant
- 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?
- 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?

60
doc/General/CODE_OF_CONDUCT.md
View File

@ -1,11 +1,16 @@
source: General/CODE_OF_CONDUCT.md
path: blob/master/doc/
## Our Pledge
# Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our
project and our community a harassment-free experience for everyone,
regardless of age, body size, disability, ethnicity, gender identity
and expression, level of experience, nationality, personal appearance,
race, religion, or sexual identity and orientation.
## Our Standards
# Our Standards
Examples of behavior that contributes to creating a positive environment include:
@ -20,28 +25,53 @@ Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
* Publishing others' private information, such as a physical or
electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in
a professional setting
## Our Responsibilities
# Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers are responsible for clarifying the standards of
acceptable behavior and are expected to take appropriate and fair
corrective action in response to any instances of unacceptable
behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Project maintainers have the right and responsibility to remove, edit,
or reject comments, commits, code, wiki edits, issues, and other
contributions that are not aligned to this Code of Conduct, or to ban
temporarily or permanently any contributor for other behaviors that
they deem inappropriate, threatening, offensive, or harmful.
## Scope
# Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
This Code of Conduct applies both within project spaces and in public
spaces when an individual is representing the project or its
community. Examples of representing a project or community include
using an official project e-mail address, posting via an official
social media account, or acting as an appointed representative at an
online or offline event. Representation of a project may be further
defined and clarified by project maintainers.
## Enforcement
# Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at team@librenms.org. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Instances of abusive, harassing, or otherwise unacceptable behavior
may be reported by contacting the project team at
team@librenms.org. The project team will review and investigate all
complaints, and will respond in a way that it deems appropriate to the
circumstances. The project team is obligated to maintain
confidentiality with regard to the reporter of an incident. Further
details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
Project maintainers who do not follow or enforce the Code of Conduct
in good faith may face temporary or permanent repercussions as
determined by other members of the project's leadership.
## Attribution
# Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
This Code of Conduct is adapted from the [Contributor
Covenant][homepage], version 1.4, available at
[http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/

74
doc/General/Callback-Stats-and-Privacy.md
View File

@ -1,37 +1,75 @@
source: General/Callback-Stats-and-Privacy.md
path: blob/master/doc/
## Stats data and your privacy ##
This document has been put together to explain what LibreNMS does when it calls back home to report some anonymous statistics.
# Stats data and your privacy
Let's start off by saying, all of the code that processes the data and submits it is included in the standard LibreNMS branch you've installed, the code that accepts this data and in turn generates some pretty graphs is all open source and available on Git Hub. Please feel free to review the code, comment on it and suggest changes / improvements. Also, don't forget - by default installations DO NOT call back home, you need to opt into this.
This document has been put together to explain what LibreNMS does when
it calls back home to report some anonymous statistics.
Above all we respect users privacy which is why this system has been designed like it has.
Let's start off by saying, all of the code that processes the data and
submits it is included in the standard LibreNMS branch you've
installed, the code that accepts this data and in turn generates some
pretty graphs is all open source and available on Git Hub. Please feel
free to review the code, comment on it and suggest changes /
improvements. Also, don't forget - by default installations DO NOT
call back home, you need to opt into this.
Now onto the bit you're interested in, what is submitted and what we do with that data.
Above all we respect users privacy which is why this system has been
designed like it has.
Now onto the bit you're interested in, what is submitted and what we
do with that data.
# What is submitted
#### What is submitted ####
- All data is anonymous.
- Generic statistics are taken from the database, these include things like device count, device type, device OS, port types, port speeds, port count and BGP peer count. Take a look at the code for full details.
- Pairs of sysDescr and sysObjectID from devices with a small amount of sanitation to prevent things like hostnames from being submitted.
- Generic statistics are taken from the database, these include things
like device count, device type, device OS, port types, port speeds,
port count and BGP peer count. Take a look at the code for full
details.
- Pairs of sysDescr and sysObjectID from devices with a small amount
of sanitation to prevent things like hostnames from being submitted.
- We record version numbers of php, mysql, net-snmp and rrdtool
- A random UUID is generated on your own install.
- That's it!
- Your IP isn't logged, even via our web service accepting the data. We don't need to know who you are so we don't ask.
- Your IP isn't logged, even via our web service accepting the
data. We don't need to know who you are so we don't ask.
# What we do with the data
#### What we do with the data ####
- We store it, not for long - 3 months at the moment although this could change.
- We use it to generate pretty graphs for people to see.
- We use it to help prioritise issues and features that need to be worked on.
- We use sysDescr and sysObjectID to create unit tests and improve OS discovery
#### Questions? ####
- **Q.** How often is data submitted? **A.** We submit the data once a day according to running daily.sh via cron. If you disable this then opting in will not have any affect.
- **Q.** Where can I see the data I submitted? **A.** You can't see the data raw, but we collate all of the data together and provide a dynamic site so you can see the results of all contributed stats [here](https://stats.librenms.org)
- **Q.** I want my data removed. **A.** That's easy, simply press 'Clear remote stats' in the About LibreNMS page of your control panel, the next time the call back script is run it will remove all the data we have.
- **Q.** I clicked the 'Clear remote stats' button by accident. **A.** No problem, before daily.sh runs again - just opt back in, all of your existing data will stay.
# Questions?
Hopefully this answers the questions you might have on why and what we are doing here, if not, please pop into our [discord server](https://t.libren.ms/discord) or community forum and ask any questions you like.
- **Q.** How often is data submitted? **A.** We submit the data once a
day according to running daily.sh via cron. If you disable this then
opting in will not have any affect.
- **Q.** Where can I see the data I submitted? **A.** You can't see
the data raw, but we collate all of the data together and provide a
dynamic site so you can see the results of all contributed stats
[here](https://stats.librenms.org)
- **Q.** I want my data removed. **A.** That's easy, simply press
'Clear remote stats' in the About LibreNMS page of your control
panel, the next time the call back script is run it will remove all
the data we have.
- **Q.** I clicked the 'Clear remote stats' button by accident. **A.**
No problem, before daily.sh runs again - just opt back in, all of
your existing data will stay.
#### How do I enable stats submission? ####
If you're happy with all of this - please consider switching the call back system on, you can do this within the About LibreNMS page within your control panel. In the Statistics section you will find a toggle switch to enable / disable the feature. If you've previously had it switched on and want to opt out and remove your data, click the 'Clear remote stats' button and on the next submission all the data you've sent us will be removed!
Hopefully this answers the questions you might have on why and what we
are doing here, if not, please pop into our [discord
server](https://t.libren.ms/discord) or community forum and ask any
questions you like.
# How do I enable stats submission?
If you're happy with all of this - please consider switching the call
back system on, you can do this within the About LibreNMS page within
your control panel. In the Statistics section you will find a toggle
switch to enable / disable the feature. If you've previously had it
switched on and want to opt out and remove your data, click the 'Clear
remote stats' button and on the next submission all the data you've
sent us will be removed!

54
doc/General/Releases.md
View File

@ -1,37 +1,45 @@
source: General/Releases.md
path: blob/master/doc/
#### Introduction
We try to ensure that breaking changes aren't introduced by utilising various automated
code testing, syntax testing and unit testing along with manual code review. However
bugs can and do get introduced as well as major refactoring to improve the quality of
the code base.
# Introduction
We try to ensure that breaking changes aren't introduced by utilising
various automated code testing, syntax testing and unit testing along
with manual code review. However 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
which will cause unintended issues. If this happens we are usually quick to fix or
revert those changes.
# Development branch
We appreciate everyone that runs this branch as you are in essence secondary testers to
the automation and manually testing that is done during the merge stages.
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 which will cause unintended
issues. If this happens we are usually quick to fix or revert those changes.
You can configure your install (this is the default) to use this branch by setting `$config['update_channel'] = 'master';`
in `config.php` and ensuring you switch to the master branch with:
We appreciate everyone that runs this branch as you are in essence
secondary testers to the automation and manually testing that is done
during the merge stages.
You can configure your install (this is the default) to use this
branch by setting `$config['update_channel'] = 'master';` in
`config.php` and ensuring you switch to the master branch with:
`cd /opt/librenms && git checkout master`
#### Stable branch
With this in mind, we provide a monthly stable release which is released on or around
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.
# Stable branch
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.
With this in mind, we provide a monthly stable release which is
released on or around 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.
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:
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.
`cd /opt/librenms && git fetch --tags && git checkout $(git describe --tags $(git rev-list --tags --max-count=1))`
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:
`cd /opt/librenms && git fetch --tags && git checkout $(git describe
--tags $(git rev-list --tags --max-count=1))`

43
doc/General/Security.md
View File

@ -1,28 +1,35 @@
source: General/Security.md
path: blob/master/doc/
### General
Like any good software we take security seriously. However, bugs do make it into the software
along with the history of the code base we inherited. It's how we deal with identified vulnerabilities
that should show that we take things seriously.
# General
### Securing your install
As with any system of this nature, we highly recommend that you restrict access to the install via
a firewall or VPN.
Like any good software we take security seriously. However, bugs do
make it into the software along with the history of the code base we
inherited. It's how we deal with identified vulnerabilities that
should show that we take things seriously.
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).
# Securing your install
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 ones provided by [LetsEncrypt](http://www.letsencrypt.org).
Please ensure you keep your install [up to date](Updating.md).
### Reporting vulnerabilities
Like anyone, we appreciate the work people put in to find flaws in software and welcome anyone
to do so with LibreNMS, this will lead to better quality and more secure software for everyone.
# Reporting vulnerabilities
If you think you've found a vulnerability and want to discuss it with some of the core team then
you can email us at [team@librenms.org](mailto:team@librenms.org) and we will endeavour to get back to
as quick as we can, this is usually within 24 hours.
Like anyone, we appreciate the work people put in to find flaws in
software and welcome anyone to do so with LibreNMS, this will lead to
better quality and more secure software for everyone.
If you think you've found a vulnerability and want to discuss it with
some of the core team then you can email us at
[team@librenms.org](mailto:team@librenms.org) and we will endeavour to
get back to as quick as we can, this is usually within 24 hours.
We are happy to attribute credit to the findings but we ask that we're
given a chance to patch any vulnerability before public disclosure so
that our users can update as soon as a fix is available.
We are happy to attribute credit to the findings but we ask that we're given a chance to patch
any vulnerability before public disclosure so that our users can update as soon as a fix is
available.

24
doc/General/Updating.md
View File

@ -1,21 +1,24 @@
source: General/Updating.md
path: blob/master/doc/
By default, LibreNMS is set to automatically update. If you have disabled this feature then you can
perform a manual update.
By default, LibreNMS is set to automatically update. If you have
disabled this feature then you can perform a manual update.
#### 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:
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`
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 without using `./daily.sh` then you can do so by running the following commands:
# Advanced users
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
@ -24,9 +27,12 @@ composer install --no-dev
./validate.php
```
You should continue to run daily.sh. This does database cleanup and other processes in addition to updating. You can disable the daily.sh update process as described below.
You should continue to run daily.sh. This does database cleanup and
other processes in addition to updating. You can disable the daily.sh
update process as described below.
# Disabling automatic updates
## Disabling automatic updates ##
LibreNMS by default performs updates on a daily basis. This can be disabled by setting:
`$config['update'] = 0;`

7
doc/General/Welcome-to-Observium-users.md
View File

@ -11,7 +11,10 @@ information about the kind of community we're trying to promote.
LibreNMS was forked from [the last GPL-licensed version of Observium][3].
Thanks to one of our users, Dan Brown, who has written a [migration script][10], you can easily move your Observium install over to LibreNMS. This also takes care of moving from one CPU architecture to another. Give it a try :)
Thanks to one of our users, Dan Brown, who has written a [migration
script][10], you can easily move your Observium install over to
LibreNMS. This also takes care of moving from one CPU architecture to
another. Give it a try :)
How LibreNMS will be different from Observium:
@ -20,7 +23,7 @@ How LibreNMS will be different from Observium:
like to see something added, add or comment on the relevant issue in our
[Community forum][9].
- Development decisions will be community-driven. We want to make software
that fulfills its users' needs.
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

82
doc/Installation/Images.md
View File

@ -1,60 +1,70 @@
> NOTE: We highly advise that you change all passwords on this image when you deploy it!!
# CentOS
> NOTE: We highly advise that you change all passwords on this image
> when you deploy it!!
>
> NOTE: Read the above note again!
We have available for download a pre-built image based on CentOS 7 and Ubuntu 18.04. These images are built using [packer.io](https://packer.io).
We have available for download a pre-built image based on CentOS 7 and
Ubuntu 18.04. These images are built using
[packer.io](https://packer.io).
Details of the image and it's setup are:
At present we provide the following builds:
- OVA Built with VirtualBox.
- OVA Built with VirtualBox.
* Any issues and or help with these images should be reported via [Community Fourm](https://community.librenms.org) or our [Discord server](https://t.libren.ms/discord)
- Any issues and or help with these images should be reported via
[Community Fourm](https://community.librenms.org) or our [Discord
server](https://t.libren.ms/discord)
#### Setup
## Setup
- US Keyboard
- Etc/UTC Timezone
- 4 Poller Wrapper threads
- US Keyboard
- Etc/UTC Timezone
- 4 Poller Wrapper threads
#### Software
## Software
- PHP 7
- MariaDB
- Syslog-ng
- PHP 7
- MariaDB
- Syslog-ng
### Features
## Features
- Oxidized installed but not configured
- Weathermap plugin enabled
- Billing enabled
- RRDCached enabled
- Service checks enabled
- Syslog enabled
- Oxidized installed but not configured
- Weathermap plugin enabled
- Billing enabled
- RRDCached enabled
- Service checks enabled
- Syslog enabled
#### Download
## Download
All images can be downloaded from [GitHub](https://github.com/librenms/packer-builds/releases/latest). The tags follow the main LibreNMS repo.
When a new LibreNMS release is available we will push new images out running that version. Please do note that if you download an older
release with a view to running that specific version, you will need to disable updates in config.php.
All images can be downloaded from
[GitHub](https://github.com/librenms/packer-builds/releases/latest). The
tags follow the main LibreNMS repo. When a new LibreNMS release is
available we will push new images out running that version. Please do
note that if you download an older release with a view to running that
specific version, you will need to disable updates in config.php.
#### Credentials
## Credentials
- SSH
- username: librenms
- password: `CDne3fwdfds`
- SSH
- username: librenms
- password: `CDne3fwdfds`
- MySQL/MariaDB
- username: librenms
- password: `D42nf23rewD`
- MySQL/MariaDB
- username: librenms
- password: `D42nf23rewD`
- WebUI
- username: librenms
- password: `D32fwefwef`
- WebUI
- username: librenms
- password: `D32fwefwef`
## Contributing
#### Contributing
If you would like to help with these images whether it's add additional features or default software / settings then you can do so
If you would like to help with these images whether it's add
additional features or default software / settings then you can do so
on [GitHub](https://github.com/librenms/packer-builds/).

338
doc/Installation/Installation-CentOS-6-Apache-Nginx.md
View File

@ -1,31 +1,43 @@
source: Installation/Installation-CentOS-6-Apache-Nginx.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 5.6.4**
### On the DB Server ###
# On the DB Server
This host is where the MySQL database runs. It could be the same machine as your network management server (this is the most common initial deployment scenario).
This host is where the MySQL database runs. It could be the same
machine as your network management server (this is the most common
initial deployment scenario).
> ** Whilst we are working on ensuring LibreNMS is compatible with MySQL strict mode, for now, please disable this after mysql is installed.
> ** Whilst we are working on ensuring LibreNMS is compatible with
> MySQL strict mode, for now, please disable this after mysql is
> installed.
You are free to choose between using MySQL or MariaDB:
**MySQL**
## MySQL
```bash
yum install net-snmp mysql-server mysql-client
chkconfig mysqld on
service mysqld start
```
**MariaDB**
## MariaDB
```bash
yum install net-snmp mariadb-server mariadb-client
chkconfig mariadb on
service mariadb start
```
## Gneral
Now continue with the installation:
```bash
@ -47,65 +59,94 @@ FLUSH PRIVILEGES;
exit
```
Replace `<ip>` above with the IP of the server running LibreNMS. If your database is on the same server as LibreNMS, use `localhost` as the IP address.
Replace `<ip>` above with the IP of the server running LibreNMS. If
your database is on the same server as LibreNMS, use `localhost` as
the IP address.
Edit the mysql/mariadb configuration file:
```bash
vim /etc/my.cnf
```
Add the following line:
innodb_file_per_table=1
```
innodb_file_per_table=1
```
If you are deploying a separate database server, you also need to specify the `bind-address`. If your MySQL database resides on the same server as LibreNMS, you should skip this step.
If you are deploying a separate database server, you also need to
specify the `bind-address`. If your MySQL database resides on the
same server as LibreNMS, you should skip this step.
bind-address = <ip>
```
bind-address = <ip>
```
If you see a line that starts `sql-mode` then change this to `sql-mode=""`.
If you see a line that starts `sql-mode` then change this to
`sql-mode=""`.
Save, and restart MySQL/MariaDB to apply your changes:
service mysqld restart
```
service mysqld restart
```
or
service mariadb restart
### On the NMS ###
Install necessary software. The packages listed below are an all-inclusive list of packages that were necessary on a clean install of CentOS 6.x. It also requires the EPEL repository. Net_IPv6 is required even if your network environment does not support IPv6.
Note if not using HTTPd (Apache): RHEL requires `httpd` to be installed regardless of of `nginx`'s (or any other web-server's) presence.
```bash
yum install epel-release
yum install php php-cli php-gd php-mysql php-snmp php-pear php-curl httpd net-snmp graphviz graphviz-php mysql ImageMagick jwhois nmap mtr rrdtool MySQL-python net-snmp-utils vixie-cron php-mcrypt fping git
pear install Net_IPv4-1.3.4
pear install Net_IPv6-1.2.2b2
```
service mariadb restart
```
### Configure SNMPD on localhost ###
Edit `/etc/snmp/snmpd.conf` to enable self-polling. An absolute minimal config for snmpd is:
# On the NMS
rocommunity public 127.0.0.1
Install necessary software. The packages listed below are an
all-inclusive list of packages that were necessary on a clean install
of CentOS 6.x. It also requires the EPEL repository. Net_IPv6 is
required even if your network environment does not support IPv6.
You may either edit the default configuration file to your liking, or backup the default config file and replace it entirely with your own. To apply your changes, run `service snmpd restart` for Centos 6.x. If you have deployed a separate database server, you will likely want to configure snmpd on that host as well.
Note if not using HTTPd (Apache): RHEL requires `httpd` to be
installed regardless of of `nginx`'s (or any other web-server's)
presence.
```bash
yum install epel-release
yum install php php-cli php-gd php-mysql php-snmp php-pear php-curl httpd net-snmp graphviz graphviz-php mysql ImageMagick jwhois nmap mtr rrdtool MySQL-python net-snmp-utils vixie-cron php-mcrypt fping git
pear install Net_IPv4-1.3.4
pear install Net_IPv6-1.2.2b2
```
# Configure SNMPD on localhost
Edit `/etc/snmp/snmpd.conf` to enable self-polling. An absolute
minimal config for snmpd is:
```
rocommunity public 127.0.0.1
```
You may either edit the default configuration file to your liking, or
backup the default config file and replace it entirely with your
own. To apply your changes, run `service snmpd restart` for Centos
6.x. If you have deployed a separate database server, you will likely
want to configure snmpd on that host as well.
### Adding the librenms-user for Apache ###
# Adding the librenms-user for Apache
```bash
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms apache
```
### Adding the librenms-user for Nginx ###
# Adding the librenms-user for Nginx
```bash
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms nginx
```
### Using HTTPd (Apache2) ###
# Using HTTPd (Apache2)
Set `httpd` to start on system boot.
@ -113,13 +154,18 @@ Set `httpd` to start on system boot.
chkconfig --levels 235 httpd on
```
In `/etc/php.ini`, ensure `date.timezone` is set to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid
examples are: "America/New York", "Australia/Brisbane", "Etc/UTC".
Please also ensure that `allow_url_fopen` is enabled. Other functions needed for LibreNMS include `exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
In `/etc/php.ini`, ensure `date.timezone` is set to your preferred
time zone. See <http://php.net/manual/en/timezones.php> for a list of
supported timezones. Valid examples are: "America/New York",
"Australia/Brisbane", "Etc/UTC". Please also ensure that
`allow_url_fopen` is enabled. Other functions needed for LibreNMS
include
`exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
Next, add the following to `/etc/httpd/conf.d/librenms.conf`
If you are running Apache below version 2.2.18:
```apache
<VirtualHost *:80>
DocumentRoot /opt/librenms/html/
@ -134,8 +180,8 @@ If you are running Apache below version 2.2.18:
</VirtualHost>
```
If you are running Apache 2.2.18 or higher:
```apache
<VirtualHost *:80>
DocumentRoot /opt/librenms/html/
@ -150,14 +196,19 @@ If you are running Apache 2.2.18 or higher:
</Directory>
</VirtualHost>
```
If the file `/etc/httpd/conf.d/welcome.conf` exists, you will want to remove that as well unless you're familiar with [Name-based Virtual Hosts](https://httpd.apache.org/docs/2.2/vhosts/name-based.html).
If the file `/etc/httpd/conf.d/welcome.conf` exists, you will want to
remove that as well unless you're familiar with [Name-based Virtual
Hosts](https://httpd.apache.org/docs/2.2/vhosts/name-based.html).
```bash
rn /etc/httpd/conf.d/welcome.conf /etc/httpd/conf.d/welcome.conf.bak
```
### Using Nginx and PHP-FPM ###
# Using Nginx and PHP-FPM
If you choose to run Nginx, you will need to install necessary extra software and let it start on system boot.
If you choose to run Nginx, you will need to install necessary extra
software and let it start on system boot.
```bash
yum install nginx php-fpm
@ -167,12 +218,15 @@ If you choose to run Nginx, you will need to install necessary extra software an
Modify permissions and configuration for `php-fpm` to use nginx credentials.
mkdir /var/lib/php/session
chown root:nginx /var/lib/php -R
vim /etc/php-fpm.d/www.conf # At line #12: Change `listen` to `/var/run/php5-fpm.sock`
# At line #39-41: Change the `user` and `group` to `nginx`
```
mkdir /var/lib/php/session
chown root:nginx /var/lib/php -R
vim /etc/php-fpm.d/www.conf # At line #12: Change `listen` to `/var/run/php5-fpm.sock`
# At line #39-41: Change the `user` and `group` to `nginx`
```
Add configuration for `nginx` at `/etc/nginx/conf.d/librenms.conf` with the following content:
Add configuration for `nginx` at `/etc/nginx/conf.d/librenms.conf`
with the following content:
```nginx
server {
@ -201,35 +255,44 @@ server {
}
```
### Cloning ###
# Cloning
You can clone the repository via HTTPS or SSH. In either case, you need to ensure the appropriate port (443 for HTTPS, 22 for SSH) is open in the outbound direction for your server.
You can clone the repository via HTTPS or SSH. In either case, you
need to ensure the appropriate port (443 for HTTPS, 22 for SSH) is
open in the outbound direction for your server.
```bash
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
NOTE: The recommended method of cloning a git repository is HTTPS. If you would like to clone via SSH instead, use the command `git clone git@github.com:librenms/librenms.git librenms` instead.
### Prepare the Web Interface ###
NOTE: The recommended method of cloning a git repository is HTTPS. If
you would like to clone via SSH instead, use the command `git clone
git@github.com:librenms/librenms.git librenms` instead.
To prepare the web interface, you'll need to create and chown a directory as well as create an Apache vhost.
# Prepare the Web Interface
To prepare the web interface, you'll need to create and chown a
directory as well as create an Apache vhost.
First, create and chown the `rrd` directory and create the `logs` directory
```bash
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
If you're planing on running rrdcached, make sure that the path is also chmod'ed to 775 and chown'ed to librenms:librenms.
If you're planing on running rrdcached, make sure that the path is
also chmod'ed to 775 and chown'ed to librenms:librenms.
**SELinux**
> if you're using SELinux you need to allow web server user to write into logs directory.
> semanage tool is a part of policycoreutils-python, so if don't have it, you can install it
> **Please note that running LibreNMS with SELinux is still experimental and we cannot guarantee that everything will be working fine for now.**
> semanage tool is a part of policycoreutils-python, so if don't have
it, you can install it **Please note that running LibreNMS with
SELinux is still experimental and we cannot guarantee that everything
will be working fine for now.**
```bash
yum install policycoreutils-python
@ -242,112 +305,181 @@ If you're planing on running rrdcached, make sure that the path is also chmod'ed
```
Set selinux to allow httpd to sendmail
```bash
setsebool -P httpd_can_sendmail=1
```
### Start the web-server: ###
# Start the web-server
# For HTTPd (Apache):
service httpd restart
```
# For HTTPd (Apache):
service httpd restart
# For Nginx:
service nginx restart
# For Nginx:
service nginx restart
```
### Web Installer ###
# Web Installer
At this stage you can launch the web installer by going to `http://IP/install.php` and follow the on-screen instructions. Alternatively if you want to continue the setup manually then perform the manual install steps. If you cannot reach the installer, stop here and solve that problem before proceeding. Afterwards, Add the following line to the end of `config.php`:
At this stage you can launch the web installer by going to
`http://IP/install.php` and follow the on-screen
instructions. Alternatively if you want to continue the setup manually
then perform the manual install steps. If you cannot reach the
installer, stop here and solve that problem before
proceeding. Afterwards, Add the following line to the end of
`config.php`:
$config['fping'] = "/usr/sbin/fping";
```
$config['fping'] = "/usr/sbin/fping";
```
### Manual Install ###
# Manual Install
You may skip this section if the web installer succeeded.
```bash
cp config.php.default config.php
vi config.php
cp config.php.default config.php
vi config.php
```
Change the values to the right of the equal sign for lines beginning with `$config[db_]` to match your database information as previously configured.
Change the values to the right of the equal sign for lines beginning
with `$config[db_]` to match your database information as previously
configured.
Change the value of `$config['snmp']['community']` from `public` to whatever your default read-only SNMP community is. If you have multiple existing communities in your environment, set it to the most common.
Change the value of `$config['snmp']['community']` from `public` to
whatever your default read-only SNMP community is. If you have
multiple existing communities in your environment, set it to the most
common.
Add the following line to the end of `config.php`:
$config['fping'] = "/usr/sbin/fping";
```
$config['fping'] = "/usr/sbin/fping";
```
Important: Be sure you have no characters (including whitespace like: newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your graphs will break otherwise and there will be no error messages to indicate otherwise!
Important: Be sure you have no characters (including whitespace like:
newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your
graphs will break otherwise and there will be no error messages to
indicate otherwise!
**Initialize the database**
# Initialize the database
Initiate the follow database with the following command:
php build-base.php
```
php build-base.php
```
**Create admin user**
# Create admin user
Create the admin user - priv should be 10
php adduser.php <name> <pass> 10 <email>
```
php adduser.php <name> <pass> 10 <email>
```
Substitute your desired username, password and email address--and leave the angled brackets off.
Substitute your desired username, password and email address--and
leave the angled brackets off.
# Validate your install
### Validate your install ###
After performing the manual install or web install, be sure to run validate.php as root in the librenms directory:
After performing the manual install or web install, be sure to run
validate.php as root in the librenms directory:
php validate.php
```
php validate.php
```
This will check your install to verify it is set up correctly.
### Add localhost ###
# Add localhost
php addhost.php localhost public v2c
```
php addhost.php localhost public v2c
```
Replace `public` to match what you set in `/etc/snmp/snmpd.conf`. This command also assumes you are using SNMP v2c. If you're using v3, there are additional steps (NOTE: instructions for SNMPv3 to come).
Replace `public` to match what you set in `/etc/snmp/snmpd.conf`.
This command also assumes you are using SNMP v2c. If you're using v3,
there are additional steps (NOTE: instructions for SNMPv3 to come).
Discover localhost:
php discovery.php -h all
```
php discovery.php -h all
```
### Create cronjob ###
# Create cronjob
The polling method used by LibreNMS is `poller-wrapper.py`, which was placed in the public domain by its author. By default, the LibreNMS cronjob runs `poller-wrapper.py` with 16 threads. The current LibreNMS recommendation is to use 4 threads per core. The default if no thread count is `16 threads`.
The polling method used by LibreNMS is `poller-wrapper.py`, which was
placed in the public domain by its author. By default, the LibreNMS
cronjob runs `poller-wrapper.py` with 16 threads. The current
LibreNMS recommendation is to use 4 threads per core. The default if
no thread count is `16 threads`.
If the thread count needs to be changed, you can do so by editing the cron file (`/etc/cron.d/librenms`).
Just add a number after `poller-wrapper.py`, as in the below example:
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
Create the cronjob
cp librenms.nonroot.cron /etc/cron.d/librenms
```
cp librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
### Copy logrotate config ###
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
### Daily Updates ###
# Daily Updates
LibreNMS performs daily updates by default. At 00:15 system time every day, a `git pull --no-edit --quiet` is performed. You can override this default by editing
your `config.php` file. Remove the comment (the `#` mark) on the line:
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
#$config['update'] = 0;
```
#$config['update'] = 0;
```
so that it looks like this:
$config['update'] = 0;
```
$config['update'] = 0;
```
### Install complete ###
# Install complete
Please allow for 2-3 runs of the poller-wrapper for data to start appearing in the WebUI.
If you don't see data after this, please refer to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
Please allow for 2-3 runs of the poller-wrapper for data to start
appearing in the WebUI. If you don't see data after this, please refer
to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
It would be great if you would consider opting into the stats system
we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
It would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.

283
doc/Installation/Installation-CentOS-7-Apache.md
View File

@ -1,48 +1,66 @@
source: Installation/Installation-CentOS-7-Apache.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 7.1.3**
## Install Required Packages ##
# Install Required Packages
yum install epel-release
```
yum install epel-release
```
rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
```
rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
yum install composer cronie fping git httpd ImageMagick jwhois mariadb mariadb-server mtr MySQL-python net-snmp net-snmp-utils nmap php72w php72w-cli php72w-common php72w-curl php72w-gd php72w-mbstring php72w-mysqlnd php72w-process php72w-snmp php72w-xml php72w-zip python-memcached rrdtool
```
yum install composer cronie fping git httpd ImageMagick jwhois mariadb mariadb-server mtr MySQL-python net-snmp net-snmp-utils nmap php72w php72w-cli php72w-common php72w-curl php72w-gd php72w-mbstring php72w-mysqlnd php72w-process php72w-snmp php72w-xml php72w-zip python-memcached rrdtool
# Add librenms user
#### Add librenms user
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms apache
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms apache
# Download LibreNMS
#### Download LibreNMS
```
cd /opt
git clone https://github.com/librenms/librenms.git
```
cd /opt
git clone https://github.com/librenms/librenms.git
#### Set permissions
# Set permissions
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
````
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
#### Install PHP dependencies
# Install PHP dependencies
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
```
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
```
## DB Server ##
# DB Server
#### Configure MySQL
## Configure MySQL
systemctl start mariadb
mysql -u root
```
systemctl start mariadb
mysql -u root
```
> NOTE: Please change the 'password' below to something secure.
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
@ -51,7 +69,9 @@ FLUSH PRIVILEGES;
exit
```
vi /etc/my.cnf
```
vi /etc/my.cnf
```
Within the `[mysqld]` section please add:
@ -59,22 +79,32 @@ Within the `[mysqld]` section please add:
innodb_file_per_table=1
lower_case_table_names=0
```
systemctl enable mariadb
systemctl restart mariadb
## Web Server ##
```
systemctl enable mariadb
systemctl restart mariadb
```
### Configure PHP
# Web Server
Ensure date.timezone is set in php.ini to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
## Configure PHP
vi /etc/php.ini
Ensure date.timezone is set in php.ini to your preferred time zone.
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York",
"Australia/Brisbane", "Etc/UTC".
### Configure Apache
```
vi /etc/php.ini
```
## Configure Apache
Create the librenms.conf:
vi /etc/httpd/conf.d/librenms.conf
```
vi /etc/httpd/conf.d/librenms.conf
```
Add the following config, edit `ServerName` as required:
@ -92,36 +122,47 @@ Add the following config, edit `ServerName` as required:
</VirtualHost>
```
> NOTE: If this is the only site you are hosting on this server (it should be :)) then you will need to disable the default site.
`rm -f /etc/httpd/conf.d/welcome.conf`
> NOTE: If this is the only site you are hosting on this server (it
> should be :)) then you will need to disable the default site. `rm -f /etc/httpd/conf.d/welcome.conf`
systemctl enable httpd
systemctl restart httpd
```
systemctl enable httpd
systemctl restart httpd
```
#### SELinux
# SELinux
Install the policy tool for SELinux:
yum install policycoreutils-python
```
yum install policycoreutils-python
```
##### Configure the contexts needed by LibreNMS:
## Configure the contexts needed by LibreNMS
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/logs(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/logs(/.*)?'
restorecon -RFvv /opt/librenms/logs/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/rrd(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/rrd(/.*)?'
restorecon -RFvv /opt/librenms/rrd/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/storage(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/storage(/.*)?'
restorecon -RFvv /opt/librenms/storage/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/bootstrap/cache(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/bootstrap/cache(/.*)?'
restorecon -RFvv /opt/librenms/bootstrap/cache/
setsebool -P httpd_can_sendmail=1
```
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/logs(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/logs(/.*)?'
restorecon -RFvv /opt/librenms/logs/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/rrd(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/rrd(/.*)?'
restorecon -RFvv /opt/librenms/rrd/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/storage(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/storage(/.*)?'
restorecon -RFvv /opt/librenms/storage/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/bootstrap/cache(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/bootstrap/cache(/.*)?'
restorecon -RFvv /opt/librenms/bootstrap/cache/
setsebool -P httpd_can_sendmail=1
```
# Allow fping
Create the file http_fping.tt with the following contents. You can
create this file anywhere, as it is a throw-away file. The last step
in this install procedure will install the module in the proper
location.
##### Allow fping
Create the file http_fping.tt with the following contents. You can create this file anywhere, as it is a throw-away file. The last step in this install procedure will install the module in the proper location.
```
module http_fping 1.0;
@ -138,84 +179,126 @@ allow httpd_t self:rawip_socket { getopt create setopt write read };
Then run these commands
checkmodule -M -m -o http_fping.mod http_fping.tt
semodule_package -o http_fping.pp -m http_fping.mod
semodule -i http_fping.pp
```
checkmodule -M -m -o http_fping.mod http_fping.tt
semodule_package -o http_fping.pp -m http_fping.mod
semodule -i http_fping.pp
```
#### Allow access through firewall
# Allow access through firewall
firewall-cmd --zone public --add-service http
firewall-cmd --permanent --zone public --add-service http
firewall-cmd --zone public --add-service https
firewall-cmd --permanent --zone public --add-service https
```
firewall-cmd --zone public --add-service http
firewall-cmd --permanent --zone public --add-service http
firewall-cmd --zone public --add-service https
firewall-cmd --permanent --zone public --add-service https
```
### Configure snmpd
# Configure snmpd
Copy the example snmpd.conf from the LibreNMS install.
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
```
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
```
vi /etc/snmp/snmpd.conf
```
vi /etc/snmp/snmpd.conf
```
Edit the text which says `RANDOMSTRINGGOESHERE` and set your own community string.
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl enable snmpd
systemctl restart snmpd
```
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl enable snmpd
systemctl restart snmpd
```
### Cron job
# Cron job
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
#### Copy logrotate config
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
## Web installer ##
# Web installer
Now head to the web installer and follow the on-screen instructions.
http://librenms.example.com/install.php
<http://librenms.example.com/install.php>
The web installer might prompt you to create a `config.php` file in your librenms install location manually, copying the content displayed on-screen to the file. If you have to do this, please remember to set the permissions on config.php after you copied the on-screen contents to the file. Run:
The web installer might prompt you to create a `config.php` file in
your librenms install location manually, copying the content displayed
on-screen to the file. If you have to do this, please remember to set
the permissions on config.php after you copied the on-screen contents
to the file. Run:
chown librenms:librenms /opt/librenms/config.php
```
chown librenms:librenms /opt/librenms/config.php
```
# Final steps
### Final steps
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
#### Add the first device
# Add the first device
We now suggest that you add localhost as your first device from within the WebUI.
#### Troubleshooting
# Troubleshooting
If you ever have issues with your install, run validate.php as root in the librenms directory:
If you ever have issues with your install, run validate.php as root in
the librenms directory:
cd /opt/librenms
./validate.php
```
cd /opt/librenms
./validate.php
```
There are various options for getting help listed on the LibreNMS web site: https://www.librenms.org/#support
There are various options for getting help listed on the LibreNMS web
site: <https://www.librenms.org/#support>
### What next?
# What next?
Now that you've installed LibreNMS, we'd suggest that you have a read of a few other docs to get you going:
Now that you've installed LibreNMS, we'd suggest that you have a read
of a few other docs to get you going:
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
### Closing
# Closing
We hope you enjoy using LibreNMS. If you do, it would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
We hope you enjoy using LibreNMS. If you do, it would be great if you
would consider opting into the stats system we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
If you would like to help make LibreNMS better there are [many ways to help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You can also [back LibreNMS on Open Collective](https://t.libren.ms/donations).
If you would like to help make LibreNMS better there are [many ways to
help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You
can also [back LibreNMS on Open
Collective](https://t.libren.ms/donations).

300
doc/Installation/Installation-CentOS-7-Nginx.md
View File

@ -1,49 +1,70 @@
source: Installation/Installation-CentOS-7-Nginx.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 7.1.3**
## Install Required Packages ##
# Install Required Packages
yum install epel-release
```
yum install epel-release
```
rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
```
rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
```
yum install composer cronie fping git ImageMagick jwhois mariadb mariadb-server mtr MySQL-python net-snmp net-snmp-utils nginx nmap php72w php72w-cli php72w-common php72w-curl php72w-fpm php72w-gd php72w-mbstring php72w-mysqlnd php72w-process php72w-snmp php72w-xml php72w-zip python-memcached rrdtool
```
yum install composer cronie fping git ImageMagick jwhois mariadb mariadb-server mtr MySQL-python net-snmp net-snmp-utils nginx nmap php72w php72w-cli php72w-common php72w-curl php72w-fpm php72w-gd php72w-mbstring php72w-mysqlnd php72w-process php72w-snmp php72w-xml php72w-zip python-memcached rrdtool
```
#### Add librenms user
# Add librenms user
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms nginx
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms nginx
```
#### Download LibreNMS
# Download LibreNMS
cd /opt
git clone https://github.com/librenms/librenms.git
#### Set permissions
```
cd /opt
git clone https://github.com/librenms/librenms.git
```
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
chgrp apache /var/lib/php/session/
# Set permissions
#### Install PHP dependencies
```
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
chgrp apache /var/lib/php/session/
```
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
# Install PHP dependencies
## DB Server ##
```
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
```
#### Configure MySQL
# DB Server
systemctl start mariadb
mysql -u root
## Configure MySQL
```
systemctl start mariadb
mysql -u root
```
> NOTE: Please change the 'password' below to something secure.
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
@ -52,7 +73,9 @@ FLUSH PRIVILEGES;
exit
```
vi /etc/my.cnf
```
vi /etc/my.cnf
```
Within the `[mysqld]` section please add:
@ -60,20 +83,30 @@ Within the `[mysqld]` section please add:
innodb_file_per_table=1
lower_case_table_names=0
```
systemctl enable mariadb
systemctl restart mariadb
## Web Server ##
```
systemctl enable mariadb
systemctl restart mariadb
```
### Configure and Start PHP-FPM
# Web Server
Ensure date.timezone is set in php.ini to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
## Configure and Start PHP-FPM
vi /etc/php.ini
Ensure date.timezone is set in php.ini to your preferred time zone.
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York",
"Australia/Brisbane", "Etc/UTC".
```
vi /etc/php.ini
```
In `/etc/php-fpm.d/www.conf` make these changes:
vi /etc/php-fpm.d/www.conf
```
vi /etc/php-fpm.d/www.conf
```
```nginx
;user = apache
@ -89,12 +122,16 @@ listen.group = nginx
listen.mode = 0660
```
systemctl enable php-fpm
systemctl restart php-fpm
```
systemctl enable php-fpm
systemctl restart php-fpm
```
### Configure NGINX
## Configure NGINX
vi /etc/nginx/conf.d/librenms.conf
```
vi /etc/nginx/conf.d/librenms.conf
```
Add the following config, edit `server_name` as required:
@ -125,37 +162,50 @@ server {
}
```
> NOTE: If this is the only site you are hosting on this server (it should be :)) then you will need to disable the default site.
> NOTE: If this is the only site you are hosting on this server (it
> should be :)) then you will need to disable the default site.
Delete the `server` section from `/etc/nginx/nginx.conf`
systemctl enable nginx
systemctl restart nginx
```
systemctl enable nginx
systemctl restart nginx
```
#### SELinux
# SELinux
Install the policy tool for SELinux:
yum install policycoreutils-python
```
yum install policycoreutils-python
```
##### Configure the contexts needed by LibreNMS:
## Configure the contexts needed by LibreNMS:
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/logs(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/logs(/.*)?'
restorecon -RFvv /opt/librenms/logs/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/rrd(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/rrd(/.*)?'
restorecon -RFvv /opt/librenms/rrd/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/storage(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/storage(/.*)?'
restorecon -RFvv /opt/librenms/storage/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/bootstrap/cache(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/bootstrap/cache(/.*)?'
restorecon -RFvv /opt/librenms/bootstrap/cache/
setsebool -P httpd_can_sendmail=1
setsebool -P httpd_execmem 1
```
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/logs(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/logs(/.*)?'
restorecon -RFvv /opt/librenms/logs/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/rrd(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/rrd(/.*)?'
restorecon -RFvv /opt/librenms/rrd/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/storage(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/storage(/.*)?'
restorecon -RFvv /opt/librenms/storage/
semanage fcontext -a -t httpd_sys_content_t '/opt/librenms/bootstrap/cache(/.*)?'
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/librenms/bootstrap/cache(/.*)?'
restorecon -RFvv /opt/librenms/bootstrap/cache/
setsebool -P httpd_can_sendmail=1
setsebool -P httpd_execmem 1
```
# Allow fping
Create the file http_fping.tt with the following contents. You can
create this file anywhere, as it is a throw-away file. The last step
in this install procedure will install the module in the proper
location.
##### Allow fping
Create the file http_fping.tt with the following contents. You can create this file anywhere, as it is a throw-away file. The last step in this install procedure will install the module in the proper location.
```
module http_fping 1.0;
@ -172,80 +222,124 @@ allow httpd_t self:rawip_socket { getopt create setopt write read };
Then run these commands
checkmodule -M -m -o http_fping.mod http_fping.tt
semodule_package -o http_fping.pp -m http_fping.mod
semodule -i http_fping.pp
```
checkmodule -M -m -o http_fping.mod http_fping.tt
semodule_package -o http_fping.pp -m http_fping.mod
semodule -i http_fping.pp
```
#### Allow access through firewall
# Allow access through firewall
firewall-cmd --zone public --add-service http
firewall-cmd --permanent --zone public --add-service http
firewall-cmd --zone public --add-service https
firewall-cmd --permanent --zone public --add-service https
```
firewall-cmd --zone public --add-service http
firewall-cmd --permanent --zone public --add-service http
firewall-cmd --zone public --add-service https
firewall-cmd --permanent --zone public --add-service https
```
### Configure snmpd
# Configure snmpd
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
```
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
```
vi /etc/snmp/snmpd.conf
```
vi /etc/snmp/snmpd.conf
```
Edit the text which says `RANDOMSTRINGGOESHERE` and set your own community string.
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl enable snmpd
systemctl restart snmpd
```
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl enable snmpd
systemctl restart snmpd
```
### Cron job
# Cron job
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
#### Copy logrotate config
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
## Web installer ##
# Web installer
Now head to the web installer and follow the on-screen instructions.
http://librenms.example.com/install.php
The web installer might prompt you to create a `config.php` file in your librenms install location manually, copying the content displayed on-screen to the file. If you have to do this, please remember to set the permissions on config.php after you copied the on-screen contents to the file. Run:
<http://librenms.example.com/install.php>
chown librenms:librenms /opt/librenms/config.php
The web installer might prompt you to create a `config.php` file in
your librenms install location manually, copying the content displayed
on-screen to the file. If you have to do this, please remember to set
the permissions on config.php after you copied the on-screen contents
to the file. Run:
### Final steps
```
chown librenms:librenms /opt/librenms/config.php
```
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
# Final steps
#### Add the first device
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure
by default. Please do not expose it to the public Internet unless
you have configured HTTPS and taken appropriate web server hardening
steps.
# Add the first device
We now suggest that you add localhost as your first device from within the WebUI.
#### Troubleshooting
# Troubleshooting
If you ever have issues with your install, run validate.php as root in the librenms directory:
If you ever have issues with your install, run validate.php as root in
the librenms directory:
cd /opt/librenms
./validate.php
```
cd /opt/librenms
./validate.php
```
There are various options for getting help listed on the LibreNMS web site: https://www.librenms.org/#support
There are various options for getting help listed on the LibreNMS web
site: https://www.librenms.org/#support
### What next?
# What next?
Now that you've installed LibreNMS, we'd suggest that you have a read of a few other docs to get you going:
Now that you've installed LibreNMS, we'd suggest that you have a read
of a few other docs to get you going:
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
### Closing
# Closing
We hope you enjoy using LibreNMS. If you do, it would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
We hope you enjoy using LibreNMS. If you do, it would be great if you
would consider opting into the stats system we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
If you would like to help make LibreNMS better there are [many ways to help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You can also [back LibreNMS on Open Collective](https://t.libren.ms/donations).
If you would like to help make LibreNMS better there are [many ways to
help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You
can also [back LibreNMS on Open
Collective](https://t.libren.ms/donations).

319
doc/Installation/Installation-Ubuntu-1404-Apache.md
View File

@ -1,29 +1,41 @@
source: Installation/Installation-Ubuntu-1404-Apache.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 5.6.4**
### On the DB Server ###
# On the DB Server
This host is where the MySQL database runs. It could be the same machine as your network management server (this is the most common initial deployment scenario).
This host is where the MySQL database runs. It could be the same
machine as your network management server (this is the most common
initial deployment scenario).
> ** Whilst we are working on ensuring LibreNMS is compatible with MySQL strict mode, for now, please disable this after mysql is installed.
> ** Whilst we are working on ensuring LibreNMS is compatible with
> MySQL strict mode, for now, please disable this after mysql is
> installed.
You are free to choose between using MySQL or MariaDB:
**MySQL**
## MySQL
```bash
apt-get install mysql-server mysql-client
mysql -uroot -p
```
**MariaDB**
## MariaDB
```bash
apt-get install mariadb-server mariadb-client
mysql -uroot -p
```
## General
Input the MySQL root password to enter the MySQL command-line interface.
Create the database:
@ -36,80 +48,130 @@ FLUSH PRIVILEGES;
exit
```
Replace `<ip>` above with the IP or DNS name of the server running LibreNMS. If your database is on the same server as LibreNMS, you can use `localhost`.
Replace `<ip>` above with the IP or DNS name of the server running
LibreNMS. If your database is on the same server as LibreNMS, you can
use `localhost`.
If you are deploying a separate database server, you need to change the `bind-address`. If your MySQL database resides on the same server as LibreNMS, you should skip this step.
If you are deploying a separate database server, you need to change
the `bind-address`. If your MySQL database resides on the same server
as LibreNMS, you should skip this step.
vim /etc/mysql/my.cnf
```
vim /etc/mysql/my.cnf
```
Within the [mysqld] section please add:
innodb_file_per_table=1
```
innodb_file_per_table=1
```
Find the line: `bind-address = 127.0.0.1`
Change `127.0.0.1` to the IP address that your MySQL server should listen on. Restart MySQL:
Change `127.0.0.1` to the IP address that your MySQL server should
listen on. Restart MySQL:
If you see a line that starts `sql-mode` then change this to `sql-mode=""`.
service mysql restart
```
service mysql restart
```
### On the NMS ###
# On the NMS
This host is where the web server and SNMP poller run. It could be the same machine as your database server.
This host is where the web server and SNMP poller run. It could be
the same machine as your database server.
Install the required software:
apt-get install libapache2-mod-php5 php5-cli php5-mysql php5-gd php5-snmp php-pear php5-curl snmp graphviz php5-mcrypt php5-json apache2 fping imagemagick whois mtr-tiny nmap python-mysqldb snmpd php-net-ipv4 php-net-ipv6 rrdtool git
```
apt-get install libapache2-mod-php5 php5-cli php5-mysql php5-gd php5-snmp php-pear php5-curl snmp graphviz php5-mcrypt php5-json apache2 fping imagemagick whois mtr-tiny nmap python-mysqldb snmpd php-net-ipv4 php-net-ipv6 rrdtool git
```
The packages listed above are an all-inclusive list of packages that were necessary on a clean install of Ubuntu 12.04/14.04.
The packages listed above are an all-inclusive list of packages that
were necessary on a clean install of Ubuntu 12.04/14.04.
You need to configure snmpd appropriately if you have not already done so. An absolute minimal config for snmpd is:
You need to configure snmpd appropriately if you have not already done
so. An absolute minimal config for snmpd is:
rocommunity public 127.0.0.1
```
rocommunity public 127.0.0.1
```
Adding the above line to `/etc/snmp/snmpd.conf` and running `service snmpd restart` will activate this config.
Adding the above line to `/etc/snmp/snmpd.conf` and running `service
snmpd restart` will activate this config.
In `/etc/php5/apache2/php.ini` and `/etc/php5/cli/php.ini`, ensure date.timezone is set to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid
examples are: "America/New York", "Australia/Brisbane", "Etc/UTC".
Please also ensure that `allow_url_fopen` is enabled. Other functions needed for LibreNMS include `exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
In `/etc/php5/apache2/php.ini` and `/etc/php5/cli/php.ini`, ensure
date.timezone is set to your preferred time zone. See
< http://php.net/manual/en/timezones.php> for a list of
supported timezones. Valid examples are: "America/New York",
"Australia/Brisbane", "Etc/UTC".
### Adding the librenms-user ###
Please also ensure that `allow_url_fopen` is enabled. Other functions
needed for LibreNMS include
`exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
# Adding the librenms-user
### Cloning ###
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
LibreNMS is installed using git. If you're not familiar with git, check out the [git book][2] or the tips at [git ready][3]. The initial install from github.com is called a `git clone`; subsequent updates are done through `git pull`.
# Cloning
You can clone the repository via HTTPS or SSH. In either case, you need to ensure that the appropriate port (443 for HTTPS, 22 for SSH) is open in the outbound direction for your server.
LibreNMS is installed using git. If you're not familiar with git,
check out the [git book][2] or the tips at [git ready][3]. The
initial install from github.com is called a `git clone`; subsequent
updates are done through `git pull`.
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
You can clone the repository via HTTPS or SSH. In either case, you
need to ensure that the appropriate port (443 for HTTPS, 22 for SSH)
is open in the outbound direction for your server.
The recommended method of cloning a git repository is HTTPS. If you would like to clone via SSH instead, use the command `git clone git@github.com:librenms/librenms.git librenms` instead.
```
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
Sometimes the initial clone can take quite a while (nearly 3 minutes on a 10 Mbps fibre connection in Australia is a recent example). If it's a big problem to you, you can save about 50% of the bandwidth by not pulling down the full git history. This comes with some limitations (namely that you can't use it as the basis for further git repos), but if you're not planning to develop for LibreNMS it's an acceptable option. To perform the initial clone without full history, run the following instead:
The recommended method of cloning a git repository is HTTPS. If you
would like to clone via SSH instead, use the command `git clone
git@github.com:librenms/librenms.git librenms` instead.
cd /opt
git clone --depth 1 https://github.com/librenms/librenms.git librenms
cd /opt/librenms
Sometimes the initial clone can take quite a while (nearly 3 minutes
on a 10 Mbps fibre connection in Australia is a recent example). If
it's a big problem to you, you can save about 50% of the bandwidth by
not pulling down the full git history. This comes with some
limitations (namely that you can't use it as the basis for further git
repos), but if you're not planning to develop for LibreNMS it's an
acceptable option. To perform the initial clone without full history,
run the following instead:
```
cd /opt
git clone --depth 1 https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
### Web Interface ###
# Web Interface
To prepare the web interface (and adding devices shortly), you'll need to create and chown a directory as well as create an Apache vhost.
To prepare the web interface (and adding devices shortly), you'll need
to create and chown a directory as well as create an Apache vhost.
First, create and chown the `rrd` directory and create the `logs` directory:
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
> NOTE: If you're not running Ubuntu or Debian, you will need to change `www-data` to the user and group which run the Apache web server.
> If you're planing on running rrdcached, make sure that the path is also chmod'ed to 775 and chown'ed to librenms:librenms.
> NOTE: If you're not running Ubuntu or Debian, you will need to
> change `www-data` to the user and group which run the Apache web
> server.
> If you're planing on running rrdcached, make sure that the path is
> also chmod'ed to 775 and chown'ed to librenms:librenms.
Next, add the following to `/etc/apache2/sites-available/librenms.conf`:
@ -127,109 +189,184 @@ Next, add the following to `/etc/apache2/sites-available/librenms.conf`:
</VirtualHost>
```
If you are running Apache 2.2.18 or higher then change `AllowEncodedSlashes On` to `AllowEncodedSlashes NoDecode`
If you are running Apache 2.2.18 or higher then change
`AllowEncodedSlashes On` to `AllowEncodedSlashes NoDecode`
If you have Apache 2.3 or newer then please add the following line before `AllowOverride All`:
If you have Apache 2.3 or newer then please add the following line
before `AllowOverride All`:
Require all granted
```
Require all granted
```
On at least Ubuntu 14.04 (and possibly other distributions and versions as well), mcrypt is not enabled on install. Run the following to enable it:
On at least Ubuntu 14.04 (and possibly other distributions and
versions as well), mcrypt is not enabled on install. Run the
following to enable it:
php5enmod mcrypt
```
php5enmod mcrypt
```
Change `librenms.example.com` to the appropriate hostname for your domain, then enable the vhost and restart Apache:
Change `librenms.example.com` to the appropriate hostname for your
domain, then enable the vhost and restart Apache:
a2ensite librenms.conf
a2enmod rewrite
service apache2 restart
```
a2ensite librenms.conf
a2enmod rewrite
service apache2 restart
```
If this is the only site you are hosting on this server (it should be :)) then you will need to disable the default site setup in Ubuntu:
If this is the only site you are hosting on this server (it should be
:)) then you will need to disable the default site setup in Ubuntu:
a2dissite 000-default
```
a2dissite 000-default
```
(To get to your LibreNMS install externally, you'll also need add it to your DNS or hosts file.)
(To get to your LibreNMS install externally, you'll also need add it
to your DNS or hosts file.)
### Manual vs. web installer ###
# Manual vs. web installer
At this stage you can either launch the web installer by going to http://librenms.example.com/install.php, follow the onscreen instructions then skip to the 'Add localhost' section. Alternatively if you want to continue the setup manually then just keep following these instructions.
At this stage you can either launch the web installer by going to
<http://librenms.example.com/install.php>, follow the onscreen
instructions then skip to the 'Add localhost' section. Alternatively
if you want to continue the setup manually then just keep following
these instructions.
cp config.php.default config.php
vim config.php
```
cp config.php.default config.php
vim config.php
```
Change the values to the right of the equal sign for lines beginning with `$config[db_]` to match your database information as setup above.
Change the values to the right of the equal sign for lines beginning
with `$config[db_]` to match your database information as setup above.
Change the value of `$config['snmp']['community']` from `public` to whatever your read-only SNMP community is. If you have multiple communities, set it to the most common.
Change the value of `$config['snmp']['community']` from `public` to
whatever your read-only SNMP community is. If you have multiple
communities, set it to the most common.
** Be sure you have no characters (including whitespace like: newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your graphs will break otherwise. **
** Be sure you have no characters (including whitespace like:
newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your
graphs will break otherwise. **
### Initialise the database ###
# Initialise the database
Initiate the follow database with the following command:
php build-base.php
```
php build-base.php
```
### Create admin user ###
# Create admin user
Create the admin user - priv should be 10
php adduser.php <name> <pass> 10 <email>
```
php adduser.php <name> <pass> 10 <email>
```
Substitute your desired username, password and email address--and leave the angled brackets off.
Substitute your desired username, password and email address--and
leave the angled brackets off.
### Validate your install ###
# Validate your install
Run validate.php as root in the librenms directory
php validate.php
```
php validate.php
```
This will check your install to verify it is set up correctly.
### Add localhost ###
# Add localhost
php addhost.php localhost public v2c
```
php addhost.php localhost public v2c
```
This assumes you haven't made community changes--if you have, replace `public` with your community. It also assumes SNMP v2c. If you're using v3, there are additional steps (NOTE: instructions for SNMPv3 to come).
This assumes you haven't made community changes--if you have, replace
`public` with your community. It also assumes SNMP v2c. If you're
using v3, there are additional steps (NOTE: instructions for SNMPv3 to
come).
Discover localhost::
php discovery.php -h all
```
php discovery.php -h all
```
### Create cronjob ###
# Create cronjob
LibreNMS uses Job Snijders' [poller-wrapper.py][1]. By default, the cron job runs `poller-wrapper.py` with 16 threads. The current recommendation is to use 4 threads per core as a rule of thumb. If the thread count needs to be changed, you can do so by editing the cron file (`/etc/cron.d/librenms`). Just add a number after `poller-wrapper.py`, as in the example below:
LibreNMS uses Job Snijders' [poller-wrapper.py][1]. By default, the
cron job runs `poller-wrapper.py` with 16 threads. The current
recommendation is to use 4 threads per core as a rule of thumb. If
the thread count needs to be changed, you can do so by editing the
cron file (`/etc/cron.d/librenms`). Just add a number after
`poller-wrapper.py`, as in the example below:
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
Create the cronjob
cp librenms.nonroot.cron /etc/cron.d/librenms
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
```
cp librenms.nonroot.cron /etc/cron.d/librenms
```
### Copy logrotate config ###
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
# Copy logrotate config
cp misc/librenms.logrotate /etc/logrotate.d/librenms
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
### Daily Updates ###
```
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
LibreNMS performs daily updates by default. At 00:15 system time every day, a `git pull --no-edit --quiet` is performed. You can override this default by editing your `config.php` file. Remove the comment (the `#` mark) on the line:
# Daily Updates
#$config['update'] = 0;
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
```
#$config['update'] = 0;
```
so that it looks like this:
$config['update'] = 0;
```
$config['update'] = 0;
```
### Install complete ###
Install complete
Please allow for 2-3 runs of the poller-wrapper for data to start appearing in the WebUI.
If you don't see data after this, please refer to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
Please allow for 2-3 runs of the poller-wrapper for data to start
appearing in the WebUI. If you don't see data after this, please refer
to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
It would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
It would be great if you would consider opting into the stats system
we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
[1]: https://github.com/Atrato/observium-poller-wrapper
[2]: http://git-scm.com/book

259
doc/Installation/Installation-Ubuntu-1404-Lighttpd.md
View File

@ -1,29 +1,41 @@
source: Installation/Installation-Ubuntu-1404-Lighttpd.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
are not, prepend `sudo` to the shell commands (the ones that aren't at
`mysql>` prompts) or temporarily become a user with root privileges
with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 5.6.4**
### On the DB Server ###
# On the DB Server
This host is where the MySQL database runs. It could be the same machine as your network management server (this is the most common initial deployment scenario).
This host is where the MySQL database runs. It could be the same
machine as your network management server (this is the most common
initial deployment scenario).
> ** Whilst we are working on ensuring LibreNMS is compatible with MySQL strict mode, for now, please disable this after mysql is installed.
> ** Whilst we are working on ensuring LibreNMS is compatible with
> MySQL strict mode, for now, please disable this after mysql is
> installed.
You are free to choose between using MySQL or MariaDB:
**MySQL**
## MySQL
```bash
apt-get install mysql-server mysql-client
mysql -uroot -p
```
**MariaDB**
## MariaDN
```bash
apt-get install mariadb-server mariadb-client
mysql -uroot -p
```
## General
Enter the MySQL root password to enter the MySQL command-line interface.
Create database.
@ -36,84 +48,128 @@ FLUSH PRIVILEGES;
exit
```
Replace `<ip>` above with the IP of the server running LibreNMS. If your database is on the same server as LibreNMS, you can just use `localhost` as the IP address.
Replace `<ip>` above with the IP of the server running LibreNMS. If
your database is on the same server as LibreNMS, you can just use
`localhost` as the IP address.
If you are deploying a separate database server, you need to change the `bind-address`. If your MySQL database resides on the same server as LibreNMS, you should skip this step.
If you are deploying a separate database server, you need to change
the `bind-address`. If your MySQL database resides on the same server
as LibreNMS, you should skip this step.
vim /etc/mysql/my.cnf
```
vim /etc/mysql/my.cnf
```
Within the [mysqld] section please add:
```
innodb_file_per_table=1
```
Find the line: `bind-address = 127.0.0.1`
Change `127.0.0.1` to the IP address that your MySQL server should listen on. Restart MySQL:
Change `127.0.0.1` to the IP address that your MySQL server should
listen on. Restart MySQL:
If you see a line that starts `sql-mode` then change this to `sql-mode=""`.
service mysql restart
```
service mysql restart
```
### On the NMS ###
# On the NMS
Install necessary software. The packages listed below are an all-inclusive list of packages that were necessary on a clean install of Debian 7.
Install necessary software. The packages listed below are an
all-inclusive list of packages that were necessary on a clean install
of Debian 7.
apt-get install lighttpd php5-cli php5-mysql php5-gd php5-snmp php5-cgi php-pear php5-curl snmp graphviz rrdtool sendmail fping imagemagick whois mtr-tiny nmap ipmitool php5-mcrypt php5-json python-mysqldb snmpd php-net-ipv4 php-net-ipv6 rrdtool git
```
apt-get install lighttpd php5-cli php5-mysql php5-gd php5-snmp php5-cgi php-pear php5-curl snmp graphviz rrdtool sendmail fping imagemagick whois mtr-tiny nmap ipmitool php5-mcrypt php5-json python-mysqldb snmpd php-net-ipv4 php-net-ipv6 rrdtool git
```
### Adding the librenms-user ###
# Adding the librenms-user
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
### Cloning ###
# Cloning
You can clone the repository via HTTPS or SSH. In either case, you need to ensure the appropriate port (443 for HTTPS, 22 for SSH) is open in the outbound direction for your server.
You can clone the repository via HTTPS or SSH. In either case, you
need to ensure the appropriate port (443 for HTTPS, 22 for SSH) is
open in the outbound direction for your server.
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
At this stage you can either launch the web installer by going to http://IP/install.php, follow the onscreen instructions then skip to the 'Web Interface' section further down. Alternatively if you want to continue the setup manually then just keep following these instructions.
At this stage you can either launch the web installer by going to
<http://IP/install.php>, follow the onscreen instructions then skip to
the 'Web Interface' section further down. Alternatively if you want to
continue the setup manually then just keep following these
instructions.
cp config.php.default config.php
vim config.php
```
cp config.php.default config.php
vim config.php
```
> NOTE: The recommended method of cloning a git repository is HTTPS. If you would like to clone via SSH instead, use the command `git clone git@github.com:librenms/librenms.git librenms` instead.
> NOTE: The recommended method of cloning a git repository is HTTPS.
> If you would like to clone via SSH instead, use the command `git
> clone git@github.com:librenms/librenms.git librenms` instead.
Change the values to the right of the equal sign for lines beginning with `$config[db_]` to match your database information as setup above.
Change the values to the right of the equal sign for lines beginning
with `$config[db_]` to match your database information as setup above.
Change the value of `$config['snmp']['community']` from `public` to whatever your read-only SNMP community is. If you have multiple communities, set it to the most common.
Change the value of `$config['snmp']['community']` from `public` to
whatever your read-only SNMP community is. If you have multiple
communities, set it to the most common.
** Be sure you have no characters (including whitespace like: newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your graphs will break otherwise. **
** Be sure you have no characters (including whitespace like:
newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your
graphs will break otherwise. **
### Initialise the database ###
# Initialise the database
Initiate the follow database with the following command:
php build-base.php
```
php build-base.php
```
### Create admin user ###
# Create admin user
Create the admin user - priv should be 10
php adduser.php <name> <pass> 10 <email>
```
php adduser.php <name> <pass> 10 <email>
```
Substitute your desired username, password and email address--and leave the angled brackets off.
Substitute your desired username, password and email address--and
leave the angled brackets off.
### Web Interface ###
# Web Interface
To prepare the web interface (and adding devices shortly), you'll need to set up Lighttpd.
To prepare the web interface (and adding devices shortly), you'll need
to set up Lighttpd.
First, create and chown the `rrd` directory and create the `logs` directory
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
mkdir rrd logs
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
```
> NOTE: If you're planing on running rrdcached, make sure that the path is also chmod'ed to 775 and chown'ed to librenms:librenms.
> NOTE: If you're planing on running rrdcached, make sure that the
> path is also chmod'ed to 775 and chown'ed to librenms:librenms.
Next, add the following to `/etc/lighttpd/librenms.conf`
```
server.document-root = "/opt/librenms/html"
url.rewrite-once = (
"^/(.*)\.(gif|jpg|jpeg|tiff|svg|png|css|php)$" => "/$0",
@ -128,85 +184,146 @@ Next, add the following to `/etc/lighttpd/librenms.conf`
"^/([a-z|0-9\-]+)/(.+)/" => "/?page=$1&$2",
"^/([a-z|0-9\-]+)/$" => "/?page=$1"
)
```
Next, add the following to `/etc/lighttpd/lighttpd.conf`
```
$HTTP["host"] == "example.com" { include "librenms.conf" }
```
And enable mod_rewrite by uncommenting
# "mod_rewrite",
```
# "mod_rewrite",
```
to
"mod_rewrite",
```
"mod_rewrite",
```
Don't forget to change 'example.com' to your domain
Enable fastcgi in Lighttpd by running the following commands,
lighty-enable-mod fastcgi
lighty-enable-mod fastcgi-php
```
lighty-enable-mod fastcgi
lighty-enable-mod fastcgi-php
```
And add the following to /etc/php5/cgi/php.ini
cgi.fix_pathinfo = 1
```
cgi.fix_pathinfo = 1
```
then restart Lighttpd:
service lighttpd restart
```
service lighttpd restart
```
### Validate your install ###
# Validate your install
Run validate.php as root in the librenms directory
php validate.php
```
php validate.php
```
This will check your install to verify it is set up correctly.
### Add localhost ###
# Add localhost
php addhost.php localhost public v2c
```
php addhost.php localhost public v2c
```
This assumes you haven't made community changes--if you have, replace `public` with your community. It also assumes SNMP v2c. If you're using v3, there are additional steps (NOTE: instructions for SNMPv3 to come).
This assumes you haven't made community changes--if you have, replace
`public` with your community. It also assumes SNMP v2c. If you're
using v3, there are additional steps (NOTE: instructions for SNMPv3 to
come).
Discover localhost:
php discovery.php -h all
```
php discovery.php -h all
```
### Create cronjob ###
# Create cronjob
The polling method used by LibreNMS is `poller-wrapper.py`, which was placed in the public domain by its author. By default, the LibreNMS cronjob runs `poller-wrapper.py` with 16 threads. The current LibreNMS recommendation is to use 4 threads per core. The default if no thread count is `16 threads`.
The polling method used by LibreNMS is `poller-wrapper.py`, which was
placed in the public domain by its author. By default, the LibreNMS
cronjob runs `poller-wrapper.py` with 16 threads. The current
LibreNMS recommendation is to use 4 threads per core. The default if
no thread count is `16 threads`.
If the thread count needs to be changed, you can do so by editing the cron file (`/etc/cron.d/librenms`).
Just add a number after `poller-wrapper.py`, as in the below example:
If the thread count needs to be changed, you can do so by editing the
cron file (`/etc/cron.d/librenms`). Just add a number after
`poller-wrapper.py`, as in the below example:
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
Create the cronjob
cp librenms.nonroot.cron /etc/cron.d/librenms
```
cp librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
### Copy logrotate config ###
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
### Daily Updates ###
# Daily Updates
LibreNMS performs daily updates by default. At 00:15 system time every day, a `git pull --no-edit --quiet` is performed. You can override this default by editing your `config.php` file. Remove the comment (the `#` mark) on the line:
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
#$config['update'] = 0;
```
#$config['update'] = 0;
```
so that it looks like this:
$config['update'] = 0;
```
$config['update'] = 0;
```
### Install complete ###
# Install complete
Please allow for 2-3 runs of the poller-wrapper for data to start appearing in the WebUI.
If you don't see data after this, please refer to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
Please allow for 2-3 runs of the poller-wrapper for data to start
appearing in the WebUI. If you don't see data after this, please refer
to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
It would be great if you would consider opting into the stats system
we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
It would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.

286
doc/Installation/Installation-Ubuntu-1404-Nginx.md
View File

@ -1,24 +1,34 @@
source: Installation/Installation-Ubuntu-1404-Nginx.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 5.6.4**
### On the DB Server ###
# On the DB Server
This host is where the MySQL database runs. It could be the same machine as your network management server (this is the most common initial deployment scenario).
This host is where the MySQL database runs. It could be the same
machine as your network management server (this is the most common
initial deployment scenario).
> ** Whilst we are working on ensuring LibreNMS is compatible with MySQL strict mode, for now, please disable this after mysql is installed.
> ** Whilst we are working on ensuring LibreNMS is compatible with
> MySQL strict mode, for now, please disable this after mysql is
> installed.
You are free to choose between using MySQL or MariaDB:
**MySQL**
## MySQL
```bash
apt-get install mysql-server mysql-client
mysql -uroot -p
```
**MariaDB**
## MariaDB
```bash
apt-get install mariadb-server mariadb-client
mysql -uroot -p
@ -36,71 +46,114 @@ FLUSH PRIVILEGES;
exit
```
Replace `<ip>` above with the IP or DNS name of the server running LibreNMS. If your database is on the same server as LibreNMS, you can use `localhost`.
Replace `<ip>` above with the IP or DNS name of the server running
LibreNMS. If your database is on the same server as LibreNMS, you can
use `localhost`.
If you are deploying a separate database server, you need to change the `bind-address`. If your MySQL database resides on the same server as LibreNMS, you should skip this step.
If you are deploying a separate database server, you need to change
the `bind-address`. If your MySQL database resides on the same server
as LibreNMS, you should skip this step.
vim /etc/mysql/my.cnf
```
vim /etc/mysql/my.cnf
```
Within the [mysqld] section please add:
innodb_file_per_table=1
```
innodb_file_per_table=1
```
Find the line: `bind-address = 127.0.0.1`
Change `127.0.0.1` to the IP address that your MySQL server should listen on. Restart MySQL:
Change `127.0.0.1` to the IP address that your MySQL server should
listen on. Restart MySQL:
If you see a line that starts `sql-mode` then change this to `sql-mode=""`.
service mysql restart
```
service mysql restart
```
### On the NMS ###
# On the NMS
This host is where the web server and SNMP poller run. It could be the same machine as your database server.
This host is where the web server and SNMP poller run. It could be
the same machine as your database server.
Install the required software:
apt-get install nginx-full php5-fpm php5-cli php5-mysql php5-gd php5-snmp php-pear php5-curl php5-mcrypt php5-json php-net-ipv4 php-net-ipv6 snmp snmpd graphviz fping imagemagick whois mtr-tiny nmap python-mysqldb rrdtool git
```
apt-get install nginx-full php5-fpm php5-cli php5-mysql php5-gd php5-snmp php-pear php5-curl php5-mcrypt php5-json php-net-ipv4 php-net-ipv6 snmp snmpd graphviz fping imagemagick whois mtr-tiny nmap python-mysqldb rrdtool git
```
The packages listed above are an all-inclusive list of packages that were necessary on a clean install of Ubuntu 12.04/14.04.
The packages listed above are an all-inclusive list of packages that
were necessary on a clean install of Ubuntu 12.04/14.04.
You need to configure snmpd appropriately if you have not already done so. An absolute minimal config for snmpd is:
You need to configure snmpd appropriately if you have not already done
so. An absolute minimal config for snmpd is:
```
rocommunity public 127.0.0.1
```
Adding the above line to `/etc/snmp/snmpd.conf` and running `service snmpd restart` will activate this config.
Adding the above line to `/etc/snmp/snmpd.conf` and running `service
snmpd restart` will activate this config.
In `/etc/php5/fpm/php.ini` and `/etc/php5/cli/php.ini`, ensure date.timezone is set to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid
examples are: "America/New York", "Australia/Brisbane", "Etc/UTC".
Please also ensure that `allow_url_fopen` is enabled. Other functions needed for LibreNMS include `exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
In `/etc/php5/fpm/php.ini` and `/etc/php5/cli/php.ini`, ensure
date.timezone is set to your preferred time zone. See
<http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New York", "Australia/Brisbane", "Etc/UTC".
Please also ensure that `allow_url_fopen` is enabled. Other functions
needed for LibreNMS include
`exec,passthru,shell_exec,escapeshellarg,escapeshellcmd,proc_close,proc_open,popen`.
### Adding the librenms-user ###
# Adding the librenms-user
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
### Cloning ###
# Cloning
LibreNMS is installed using git. If you're not familiar with git, check out the [git book][2] or the tips at [git ready][3]. The initial install from github.com is called a `git clone`; subsequent updates are done through `git pull`.
LibreNMS is installed using git. If you're not familiar with git,
check out the [git book][2] or the tips at [git ready][3]. The
initial install from github.com is called a `git clone`; subsequent
updates are done through `git pull`.
You can clone the repository via HTTPS or SSH. In either case, you need to ensure that the appropriate port (443 for HTTPS, 22 for SSH) is open in the outbound direction for your server.
You can clone the repository via HTTPS or SSH. In either case, you
need to ensure that the appropriate port (443 for HTTPS, 22 for SSH)
is open in the outbound direction for your server.
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
cd /opt
git clone https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
The recommended method of cloning a git repository is HTTPS. If you would like to clone via SSH instead, use the command `git clone git@github.com:librenms/librenms.git librenms` instead.
The recommended method of cloning a git repository is HTTPS. If you
would like to clone via SSH instead, use the command `git clone
git@github.com:librenms/librenms.git librenms` instead.
Sometimes the initial clone can take quite a while (nearly 3 minutes on a 10 Mbps fibre connection in Australia is a recent example). If it's a big problem to you, you can save about 50% of the bandwidth by not pulling down the full git history. This comes with some limitations (namely that you can't use it as the basis for further git repos), but if you're not planning to develop for LibreNMS it's an acceptable option. To perform the initial clone without full history, run the following instead:
Sometimes the initial clone can take quite a while (nearly 3 minutes
on a 10 Mbps fibre connection in Australia is a recent example). If
it's a big problem to you, you can save about 50% of the bandwidth by
not pulling down the full git history. This comes with some
limitations (namely that you can't use it as the basis for further git
repos), but if you're not planning to develop for LibreNMS it's an
acceptable option. To perform the initial clone without full history,
run the following instead:
cd /opt
git clone --depth 1 https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
cd /opt
git clone --depth 1 https://github.com/librenms/librenms.git librenms
cd /opt/librenms
```
# Web Interface
### Web Interface ###
To prepare the web interface (and adding devices shortly), you'll need to create and chown a directory as well as create a Nginx vhost.
To prepare the web interface (and adding devices shortly), you'll need
to create and chown a directory as well as create a Nginx vhost.
First, create and chown the `rrd` directory and create the `logs` directory:
@ -108,10 +161,13 @@ First, create and chown the `rrd` directory and create the `logs` directory:
chown -R librenms:librenms /opt/librenms
chmod 775 rrd
> NOTE: If you're not running Ubuntu or Debian, you will need to change `www-data` to the user and group which run the Nginx web server.
> If you're planing on running rrdcached, make sure that the path is also chmod'ed to 775 and chown'ed to librenms:librenms.
> NOTE: If you're not running Ubuntu or Debian, you will need to
> change `www-data` to the user and group which run the Nginx web
> server. If you're planing on running rrdcached, make sure that the path is
> also chmod'ed to 775 and chown'ed to librenms:librenms.
Add configuration for `nginx` at `/etc/nginx/conf.d/librenms.conf` with the following content:
Add configuration for `nginx` at `/etc/nginx/conf.d/librenms.conf`
with the following content:
```nginx
server {
@ -141,103 +197,173 @@ server {
}
}
```
On at least Ubuntu 14.04 (and possibly other distributions and versions as well), mcrypt is not enabled on install. Run the following to enable it:
php5enmod mcrypt
On at least Ubuntu 14.04 (and possibly other distributions and
versions as well), mcrypt is not enabled on install. Run the
following to enable it:
(To get to your LibreNMS install externally, you'll also need add it to your DNS or hosts file.)
```
php5enmod mcrypt
```
### Start the web-server: ###
(To get to your LibreNMS install externally, you'll also need add it
to your DNS or hosts file.)
# Start the web-server
Restart nginx:
service nginx restart
```
service nginx restart
```
Restart php5-fpm:
service php5-fpm restart
```
service php5-fpm restart
```
### Manual vs. web installer ###
# Manual vs. web installer
At this stage you can either launch the web installer by going to http://librenms.example.com/install.php, follow the onscreen instructions then skip to the 'Add localhost' section. Alternatively if you want to continue the setup manually then just keep following these instructions.
At this stage you can either launch the web installer by going to
<http://librenms.example.com/install.php>, follow the onscreen
instructions then skip to the 'Add localhost' section. Alternatively
if you want to continue the setup manually then just keep following
these instructions.
cp config.php.default config.php
vim config.php
```
cp config.php.default config.php
vim config.php
```
Change the values to the right of the equal sign for lines beginning with `$config[db_]` to match your database information as setup above.
Change the values to the right of the equal sign for lines beginning
with `$config[db_]` to match your database information as setup above.
Change the value of `$config['snmp']['community']` from `public` to whatever your read-only SNMP community is. If you have multiple communities, set it to the most common.
Change the value of `$config['snmp']['community']` from `public` to
whatever your read-only SNMP community is. If you have multiple
communities, set it to the most common.
** Be sure you have no characters (including whitespace like: newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your graphs will break otherwise. **
** Be sure you have no characters (including whitespace like:
newlines, spaces, tabs, etc) outside of the `<?php?>` blocks. Your
graphs will break otherwise. **
### Initialise the database ###
# Initialise the database
Initiate the follow database with the following command:
php build-base.php
```
php build-base.php
```
### Create admin user ###
# Create admin user
Create the admin user - priv should be 10
php adduser.php <name> <pass> 10 <email>
```
php adduser.php <name> <pass> 10 <email>
```
Substitute your desired username, password and email address--and leave the angled brackets off.
Substitute your desired username, password and email address--and
leave the angled brackets off.
### Validate your install ###
# Validate your install
Run validate.php as root in the librenms directory
php validate.php
```
php validate.php
```
This will check your install to verify it is set up correctly.
### Add localhost ###
# Add localhost
php addhost.php localhost public v2c
```
php addhost.php localhost public v2c
```
This assumes you haven't made community changes--if you have, replace `public` with your community. It also assumes SNMP v2c. If you're using v3, there are additional steps (NOTE: instructions for SNMPv3 to come).
This assumes you haven't made community changes--if you have, replace
`public` with your community. It also assumes SNMP v2c. If you're
using v3, there are additional steps (NOTE: instructions for SNMPv3 to
come).
Discover localhost::
php discovery.php -h all
```
php discovery.php -h all
```
### Create cronjob ###
# Create cronjob
LibreNMS uses Job Snijders' [poller-wrapper.py][1]. By default, the cron job runs `poller-wrapper.py` with 16 threads. The current recommendation is to use 4 threads per core as a rule of thumb. If the thread count needs to be changed, you can do so by editing the cron file (`/etc/cron.d/librenms`). Just add a number after `poller-wrapper.py`, as in the example below:
LibreNMS uses Job Snijders' [poller-wrapper.py][1]. By default, the
cron job runs `poller-wrapper.py` with 16 threads. The current
recommendation is to use 4 threads per core as a rule of thumb. If
the thread count needs to be changed, you can do so by editing the
cron file (`/etc/cron.d/librenms`). Just add a number after
`poller-wrapper.py`, as in the example below:
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
/opt/librenms/poller-wrapper.py 12 >> /dev/null 2>&1
```
Create the cronjob
cp librenms.nonroot.cron /etc/cron.d/librenms
```
cp librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
### Copy logrotate config ###
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp misc/librenms.logrotate /etc/logrotate.d/librenms
```
### Daily Updates ###
# Daily Updates
LibreNMS performs daily updates by default. At 00:15 system time every day, a `git pull --no-edit --quiet` is performed. You can override this default by editing your `config.php` file. Remove the comment (the `#` mark) on the line:
LibreNMS performs daily updates by default. At 00:15 system time
every day, a `git pull --no-edit --quiet` is performed. You can
override this default by editing your `config.php` file. Remove the
comment (the `#` mark) on the line:
#$config['update'] = 0;
```
#$config['update'] = 0;
```
so that it looks like this:
$config['update'] = 0;
```
$config['update'] = 0;
```
### Install complete ###
# Install complete
Please allow for 2-3 runs of the poller-wrapper for data to start appearing in the WebUI.
If you don't see data after this, please refer to the [FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
Please allow for 2-3 runs of the poller-wrapper for data to start
appearing in the WebUI. If you don't see data after this, please refer to the
[FAQ](http://docs.librenms.org/Support/FAQ/) for assistance.
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
It would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
It would be great if you would consider opting into the stats system
we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
[1]: https://github.com/Atrato/observium-poller-wrapper
[2]: http://git-scm.com/book

192
doc/Installation/Installation-Ubuntu-1604-Apache.md
View File

@ -1,32 +1,40 @@
source: Installation/Installation-Ubuntu-1604-Apache.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 5.6.4**
## Install Required Packages ##
# Install Required Packages
apt install acl apache2 composer fping git graphviz imagemagick libapache2-mod-php7.0 mariadb-client mariadb-server mtr-tiny nmap php7.0-cli php7.0-curl php7.0-gd php7.0-json php7.0-mbstring php7.0-mcrypt php7.0-mysql php7.0-snmp php7.0-xml php7.0-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
#### Add librenms user
# Add librenms user
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
#### Install LibreNMS
# Install LibreNMS
cd /opt
composer create-project --no-dev --keep-vcs librenms/librenms librenms dev-master
## DB Server ##
# DB Server
#### Configure MySQL
systemctl restart mysql
mysql -uroot -p
## Configure MySQL
```
systemctl restart mysql
mysql -uroot -p
```
> NOTE: Please change the 'password' below to something secure.
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
@ -35,7 +43,9 @@ FLUSH PRIVILEGES;
exit
```
vi /etc/mysql/mariadb.conf.d/50-server.cnf
```
vi /etc/mysql/mariadb.conf.d/50-server.cnf
```
Within the `[mysqld]` section please add:
@ -43,25 +53,37 @@ Within the `[mysqld]` section please add:
innodb_file_per_table=1
lower_case_table_names=0
```
systemctl restart mysql
## Web Server ##
```
systemctl restart mysql
```
### Configure PHP
# Web Server
Ensure date.timezone is set in php.ini to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
## Configure PHP
vi /etc/php/7.0/apache2/php.ini
vi /etc/php/7.0/cli/php.ini
Ensure date.timezone is set in php.ini to your preferred time zone.
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York",
"Australia/Brisbane", "Etc/UTC".
a2enmod php7.0
a2dismod mpm_event
a2enmod mpm_prefork
phpenmod mcrypt
```
vi /etc/php/7.0/apache2/php.ini
vi /etc/php/7.0/cli/php.ini
```
### Configure Apache
```
a2enmod php7.0
a2dismod mpm_event
a2enmod mpm_prefork
phpenmod mcrypt
```
vi /etc/apache2/sites-available/librenms.conf
## Configure Apache
```
vi /etc/apache2/sites-available/librenms.conf
```
Add the following config, edit `ServerName` as required:
@ -79,80 +101,124 @@ Add the following config, edit `ServerName` as required:
</VirtualHost>
```
> NOTE: If this is the only site you are hosting on this server (it should be :)) then you will need to disable the default site.
`a2dissite 000-default`
> NOTE: If this is the only site you are hosting on this server (it
> should be :)) then you will need to disable the default
> site. `a2dissite 000-default`
a2ensite librenms.conf
a2enmod rewrite
systemctl restart apache2
```
a2ensite librenms.conf
a2enmod rewrite
systemctl restart apache2
```
#### Configure snmpd
# Configure snmpd
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf
```
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf
```
Edit the text which says `RANDOMSTRINGGOESHERE` and set your own community string.
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
```
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
```
### Cron job
## Cron job
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
#### Copy logrotate config
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
### Set permissions
# Set permissions
chown -R librenms:librenms /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
chown -R librenms:librenms /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
## Web installer ##
# Web installer
Now head to the web installer and follow the on-screen instructions.
http://librenms.example.com/install.php
<http://librenms.example.com/install.php>
The web installer might prompt you to create a `config.php` file in your librenms install location manually, copying the content displayed on-screen to the file. If you have to do this, please remember to set the permissions on config.php after you copied the on-screen contents to the file. Run:
chown librenms:librenms /opt/librenms/config.php
The web installer might prompt you to create a `config.php` file in
your librenms install location manually, copying the content displayed
on-screen to the file. If you have to do this, please remember to set
the permissions on config.php after you copied the on-screen contents
to the file. Run:
### Final steps
```
chown librenms:librenms /opt/librenms/config.php
```
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
# Final steps
#### Add the first device
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
# Add the first device
We now suggest that you add localhost as your first device from within the WebUI.
#### Troubleshooting
# Troubleshooting
If you ever have issues with your install, run validate.php as root in the librenms directory:
If you ever have issues with your install, run validate.php as root in
the librenms directory:
cd /opt/librenms
./validate.php
```
cd /opt/librenms
./validate.php
```
There are various options for getting help listed on the LibreNMS web site: https://www.librenms.org/#support
There are various options for getting help listed on the LibreNMS web
site: <https://www.librenms.org/#support>
### What next?
# What next?
Now that you've installed LibreNMS, we'd suggest that you have a read of a few other docs to get you going:
Now that you've installed LibreNMS, we'd suggest that you have a read
of a few other docs to get you going:
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
### Closing
# Closing
We hope you enjoy using LibreNMS. If you do, it would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
We hope you enjoy using LibreNMS. If you do, it would be great if you
would consider opting into the stats system we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
If you would like to help make LibreNMS better there are [many ways to help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You can also [back LibreNMS on Open Collective](https://t.libren.ms/donations).
If you would like to help make LibreNMS better there are [many ways to
help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You
can also [back LibreNMS on Open
Collective](https://t.libren.ms/donations).

188
doc/Installation/Installation-Ubuntu-1604-Nginx.md
View File

@ -1,31 +1,40 @@
source: Installation/Installation-Ubuntu-1604-Nginx.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 5.6.4**
## Install Required Packages ##
# Install Required Packages
apt install acl composer fping git graphviz imagemagick mariadb-client mariadb-server mtr-tiny nginx-full nmap php7.0-cli php7.0-curl php7.0-fpm php7.0-gd php7.0-mbstring php7.0-mcrypt php7.0-mysql php7.0-snmp php7.0-xml php7.0-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
```
apt install acl composer fping git graphviz imagemagick mariadb-client mariadb-server mtr-tiny nginx-full nmap php7.0-cli php7.0-curl php7.0-fpm php7.0-gd php7.0-mbstring php7.0-mcrypt php7.0-mysql php7.0-snmp php7.0-xml php7.0-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
```
#### Add librenms user
# Add librenms user
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
#### Install LibreNMS
# Install LibreNMS
cd /opt
composer create-project --no-dev --keep-vcs librenms/librenms librenms dev-master
## DB Server ##
# DB Server
#### Configure MySQL
systemctl restart mysql
mysql -uroot -p
## Configure MySQL
```
systemctl restart mysql
mysql -uroot -p
```
> NOTE: Please change the 'password' below to something secure.
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
@ -34,7 +43,9 @@ FLUSH PRIVILEGES;
exit
```
vim /etc/mysql/mariadb.conf.d/50-server.cnf
```
vim /etc/mysql/mariadb.conf.d/50-server.cnf
```
Within the `[mysqld]` section please add:
@ -42,22 +53,35 @@ Within the `[mysqld]` section please add:
innodb_file_per_table=1
lower_case_table_names=0
```
systemctl restart mysql
## Web Server ##
```
systemctl restart mysql
```
### Configure and Start PHP-FPM
Ensure date.timezone is set in php.ini to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
# Web Server
vim /etc/php/7.0/fpm/php.ini
vim /etc/php/7.0/cli/php.ini
## Configure and Start PHP-FPM
phpenmod mcrypt
systemctl restart php7.0-fpm
Ensure date.timezone is set in php.ini to your preferred time zone.
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York",
"Australia/Brisbane", "Etc/UTC".
#### Configure NGINX
```
vim /etc/php/7.0/fpm/php.ini
vim /etc/php/7.0/cli/php.ini
```
vim /etc/nginx/conf.d/librenms.conf
```
phpenmod mcrypt
systemctl restart php7.0-fpm
```
## Configure NGINX
```
vim /etc/nginx/conf.d/librenms.conf
```
Add the following config, edit `server_name` as required:
@ -88,76 +112,120 @@ server {
}
```
rm /etc/nginx/sites-enabled/default
systemctl restart nginx
```
rm /etc/nginx/sites-enabled/default
systemctl restart nginx
```
#### Configure snmpd
# Configure snmpd
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vim /etc/snmp/snmpd.conf
```
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vim /etc/snmp/snmpd.conf
```
Edit the text which says `RANDOMSTRINGGOESHERE` and set your own community string.
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
```
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
```
### Cron job
# Cron job
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
#### Copy logrotate config
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
### Set permissions
# Set permissions
chown -R librenms:librenms /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
chown -R librenms:librenms /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
## Web installer ##
# Web installer
Now head to the web installer and follow the on-screen instructions.
http://librenms.example.com/install.php
```
http://librenms.example.com/install.php
```
The web installer might prompt you to create a `config.php` file in your librenms install location manually, copying the content displayed on-screen to the file. If you have to do this, please remember to set the permissions on config.php after you copied the on-screen contents to the file. Run:
The web installer might prompt you to create a `config.php` file in
your librenms install location manually, copying the content displayed
on-screen to the file. If you have to do this, please remember to set
the permissions on config.php after you copied the on-screen contents
to the file. Run:
chown librenms:librenms /opt/librenms/config.php
```
chown librenms:librenms /opt/librenms/config.php
```
### Final steps
# Final steps
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
#### Add the first device
# Add the first device
We now suggest that you add localhost as your first device from within the WebUI.
#### Troubleshooting
# Troubleshooting
If you ever have issues with your install, run validate.php as root in the librenms directory:
If you ever have issues with your install, run validate.php as root in
the librenms directory:
cd /opt/librenms
./validate.php
```
cd /opt/librenms
./validate.php
```
There are various options for getting help listed on the LibreNMS web site: https://www.librenms.org/#support
There are various options for getting help listed on the LibreNMS web
site: <https://www.librenms.org/#support>
### What next?
# What next?
Now that you've installed LibreNMS, we'd suggest that you have a read of a few other docs to get you going:
Now that you've installed LibreNMS, we'd suggest that you have a read
of a few other docs to get you going:
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
### Closing
# Closing
We hope you enjoy using LibreNMS. If you do, it would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
We hope you enjoy using LibreNMS. If you do, it would be great if you
would consider opting into the stats system we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
If you would like to help make LibreNMS better there are [many ways to help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You can also [back LibreNMS on Open Collective](https://t.libren.ms/donations).
If you would like to help make LibreNMS better there are [many ways to
help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You
can also [back LibreNMS on Open
Collective](https://t.libren.ms/donations).

215
doc/Installation/Installation-Ubuntu-1804-Apache.md
View File

@ -1,45 +1,64 @@
source: Installation/Installation-Ubuntu-1804-Apache.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 7.1.3**
## Install Required Packages ##
apt install software-properties-common
add-apt-repository universe
apt update
apt install curl apache2 composer fping git graphviz imagemagick libapache2-mod-php7.2 mariadb-client mariadb-server mtr-tiny nmap php7.2-cli php7.2-curl php7.2-gd php7.2-json php7.2-mbstring php7.2-mysql php7.2-snmp php7.2-xml php7.2-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
# Install Required Packages
#### Add librenms user
```
apt install software-properties-common
add-apt-repository universe
apt update
apt install curl apache2 composer fping git graphviz imagemagick libapache2-mod-php7.2 mariadb-client mariadb-server mtr-tiny nmap php7.2-cli php7.2-curl php7.2-gd php7.2-json php7.2-mbstring php7.2-mysql php7.2-snmp php7.2-xml php7.2-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
# Add librenms user
#### Download LibreNMS
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
cd /opt
git clone https://github.com/librenms/librenms.git
#### Set permissions
# Download LibreNMS
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
cd /opt
git clone https://github.com/librenms/librenms.git
```
#### Install PHP dependencies
# Set permissions
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
```
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
## DB Server ##
# Install PHP dependencies
#### Configure MySQL
systemctl restart mysql
mysql -uroot -p
```
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
```
# DB Server
## Configure MySQL
```
systemctl restart mysql
mysql -uroot -p
```
> NOTE: Please change the 'password' below to something secure.
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
@ -48,7 +67,9 @@ FLUSH PRIVILEGES;
exit
```
vi /etc/mysql/mariadb.conf.d/50-server.cnf
```
vi /etc/mysql/mariadb.conf.d/50-server.cnf
```
Within the `[mysqld]` section please add:
@ -56,13 +77,19 @@ Within the `[mysqld]` section please add:
innodb_file_per_table=1
lower_case_table_names=0
```
systemctl restart mysql
## Web Server ##
```
systemctl restart mysql
```
### Configure PHP
# Web Server
Ensure date.timezone is set in php.ini to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
## Configure PHP
Ensure date.timezone is set in php.ini to your preferred time zone.
See <http://php.net/manual/en/timezones.php> for a list of supported
timezones. Valid examples are: "America/New_York",
"Australia/Brisbane", "Etc/UTC".
vi /etc/php/7.2/apache2/php.ini
vi /etc/php/7.2/cli/php.ini
@ -71,9 +98,11 @@ Ensure date.timezone is set in php.ini to your preferred time zone. See http://
a2dismod mpm_event
a2enmod mpm_prefork
### Configure Apache
## Configure Apache
vi /etc/apache2/sites-available/librenms.conf
```
vi /etc/apache2/sites-available/librenms.conf
```
Add the following config, edit `ServerName` as required:
@ -91,75 +120,117 @@ Add the following config, edit `ServerName` as required:
</VirtualHost>
```
> NOTE: If this is the only site you are hosting on this server (it should be :)) then you will need to disable the default site.
`a2dissite 000-default`
> NOTE: If this is the only site you are hosting on this server (it
> should be :)) then you will need to disable the default
> site. `a2dissite 000-default`
a2ensite librenms.conf
a2enmod rewrite
systemctl restart apache2
```
a2ensite librenms.conf
a2enmod rewrite
systemctl restart apache2
```
### Configure snmpd
# Configure snmpd
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf
```
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf
```
Edit the text which says `RANDOMSTRINGGOESHERE` and set your own community string.
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
```
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
```
### Cron job
# Cron job
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
#### Copy logrotate config
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
## Web installer ##
# Web installer ##
Now head to the web installer and follow the on-screen instructions.
http://librenms.example.com/install.php
```
http://librenms.example.com/install.php
```
The web installer might prompt you to create a `config.php` file in your librenms install location manually, copying the content displayed on-screen to the file. If you have to do this, please remember to set the permissions on config.php after you copied the on-screen contents to the file. Run:
The web installer might prompt you to create a `config.php` file in
your librenms install location manually, copying the content displayed
on-screen to the file. If you have to do this, please remember to set
the permissions on config.php after you copied the on-screen contents
to the file. Run:
chown librenms:librenms /opt/librenms/config.php
```
chown librenms:librenms /opt/librenms/config.php
```
### Final steps
# Final steps
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
#### Add the first device
# Add the first device
We now suggest that you add localhost as your first device from within the WebUI.
#### Troubleshooting
# Troubleshooting
If you ever have issues with your install, run validate.php as root in the librenms directory:
If you ever have issues with your install, run validate.php as root in
the librenms directory:
cd /opt/librenms
./validate.php
```
cd /opt/librenms
./validate.php
```
There are various options for getting help listed on the LibreNMS web site: https://www.librenms.org/#support
There are various options for getting help listed on the LibreNMS web
site: <https://www.librenms.org/#support>
### What next?
# What next?
Now that you've installed LibreNMS, we'd suggest that you have a read of a few other docs to get you going:
Now that you've installed LibreNMS, we'd suggest that you have a read
of a few other docs to get you going:
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
### Closing
# Closing
We hope you enjoy using LibreNMS. If you do, it would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
We hope you enjoy using LibreNMS. If you do, it would be great if you
would consider opting into the stats system we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
If you would like to help make LibreNMS better there are [many ways to help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You can also [back LibreNMS on Open Collective](https://t.libren.ms/donations).
If you would like to help make LibreNMS better there are [many ways to
help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You
can also [back LibreNMS on Open
Collective](https://t.libren.ms/donations).

234
doc/Installation/Installation-Ubuntu-1804-Nginx.md
View File

@ -1,45 +1,65 @@
source: Installation/Installation-Ubuntu-1804-Nginx.md
path: blob/master/doc/
> NOTE: These instructions assume you are the **root** user. If you are not, prepend `sudo` to the shell commands (the ones that aren't at `mysql>` prompts) or temporarily become a user with root privileges with `sudo -s` or `sudo -i`.
> NOTE: These instructions assume you are the **root** user. If you
> are not, prepend `sudo` to the shell commands (the ones that aren't
> at `mysql>` prompts) or temporarily become a user with root
> privileges with `sudo -s` or `sudo -i`.
**Please note the minimum supported PHP version is 7.1.3**
## Install Required Packages ##
apt install software-properties-common
add-apt-repository universe
apt update
apt install curl composer fping git graphviz imagemagick mariadb-client mariadb-server mtr-tiny nginx-full nmap php7.2-cli php7.2-curl php7.2-fpm php7.2-gd php7.2-json php7.2-mbstring php7.2-mysql php7.2-snmp php7.2-xml php7.2-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
#### Add librenms user
# Install Required Packages
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
apt install software-properties-common
add-apt-repository universe
apt update
apt install curl composer fping git graphviz imagemagick mariadb-client mariadb-server mtr-tiny nginx-full nmap php7.2-cli php7.2-curl php7.2-fpm php7.2-gd php7.2-json php7.2-mbstring php7.2-mysql php7.2-snmp php7.2-xml php7.2-zip python-memcache python-mysqldb rrdtool snmp snmpd whois
```
#### Download LibreNMS
# Add librenms user
cd /opt
git clone https://github.com/librenms/librenms.git
#### Set permissions
```
useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data
```
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
# Download LibreNMS
#### Install PHP dependencies
```
cd /opt
git clone https://github.com/librenms/librenms.git
```
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
# Set permissions
## DB Server ##
```
chown -R librenms:librenms /opt/librenms
chmod 770 /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs
/opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
#### Configure MySQL
systemctl restart mysql
mysql -uroot -p
# Install PHP dependencies
```
su - librenms
./scripts/composer_wrapper.php install --no-dev
exit
```
# DB Server
## Configure MySQL
```
systemctl restart mysql
mysql -uroot -p
```
> NOTE: Please change the 'password' below to something secure.
```sql
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'password';
@ -48,7 +68,9 @@ FLUSH PRIVILEGES;
exit
```
vi /etc/mysql/mariadb.conf.d/50-server.cnf
```
vi /etc/mysql/mariadb.conf.d/50-server.cnf
```
Within the `[mysqld]` section please add:
@ -56,21 +78,34 @@ Within the `[mysqld]` section please add:
innodb_file_per_table=1
lower_case_table_names=0
```
systemctl restart mysql
## Web Server ##
```
systemctl restart mysql
```
### Configure and Start PHP-FPM
Ensure date.timezone is set in php.ini to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid examples are: "America/New_York", "Australia/Brisbane", "Etc/UTC".
# Web Server
vi /etc/php/7.2/fpm/php.ini
vi /etc/php/7.2/cli/php.ini
## Configure and Start PHP-FPM
systemctl restart php7.2-fpm
Ensure date.timezone is set in php.ini to your preferred time zone.
See http://php.net/manual/en/timezones.php for a list of supported
timezones. Valid examples are: "America/New_York",
"Australia/Brisbane", "Etc/UTC".
#### Configure NGINX
```
vi /etc/php/7.2/fpm/php.ini
vi /etc/php/7.2/cli/php.ini
```
vi /etc/nginx/conf.d/librenms.conf
```
systemctl restart php7.2-fpm
```
## Configure NGINX
```
vi /etc/nginx/conf.d/librenms.conf
```
Add the following config, edit `server_name` as required:
@ -101,76 +136,119 @@ server {
}
```
rm /etc/nginx/sites-enabled/default
systemctl restart nginx
```
rm /etc/nginx/sites-enabled/default
systemctl restart nginx
```
### Configure snmpd
# Configure snmpd
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf
```
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
vi /etc/snmp/snmpd.conf
```
Edit the text which says `RANDOMSTRINGGOESHERE` and set your own community string.
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
systemctl restart snmpd
```
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
hmod +x /usr/bin/distro
systemctl restart snmpd
```
### Cron job
# Cron job
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
```
> NOTE: Keep in mind that cron, by default, only uses a very limited set of environment variables. You may need to configure proxy variables for the cron invocation. Alternatively adding the proxy settings in config.php is possible too. The config.php file will be created in the upcoming steps. Review the following URL after you finished librenms install steps: https://docs.librenms.org/Support/Configuration/#proxy-support
> NOTE: Keep in mind that cron, by default, only uses a very limited
> set of environment variables. You may need to configure proxy
> variables for the cron invocation. Alternatively adding the proxy
> settings in config.php is possible too. The config.php file will be
> created in the upcoming steps. Review the following URL after you
> finished librenms install steps:
> <https://docs.librenms.org/Support/Configuration/#proxy-support>
#### Copy logrotate config
# Copy logrotate config
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can become large and be rotated out. To rotate out the old logs you can use the provided logrotate config file:
LibreNMS keeps logs in `/opt/librenms/logs`. Over time these can
become large and be rotated out. To rotate out the old logs you can
use the provided logrotate config file:
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
```
### Set permissions
# Set permissions
chown -R librenms:librenms /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
chown -R librenms:librenms /opt/librenms
setfacl -d -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
```
## Web installer ##
# Web installer
Now head to the web installer and follow the on-screen instructions.
http://librenms.example.com/install.php
<http://librenms.example.com/install.php>
The web installer might prompt you to create a `config.php` file in your librenms install location manually, copying the content displayed on-screen to the file. If you have to do this, please remember to set the permissions on config.php after you copied the on-screen contents to the file. Run:
The web installer might prompt you to create a `config.php` file in
your librenms install location manually, copying the content displayed
on-screen to the file. If you have to do this, please remember to set
the permissions on config.php after you copied the on-screen contents
to the file. Run:
chown librenms:librenms /opt/librenms/config.php
### Final steps
```
chown librenms:librenms /opt/librenms/config.php
```
That's it! You now should be able to log in to http://librenms.example.com/. Please note that we have not covered HTTPS setup in this example, so your LibreNMS install is not secure by default. Please do not expose it to the public Internet unless you have configured HTTPS and taken appropriate web server hardening steps.
# Final steps
#### Add the first device
That's it! You now should be able to log in to
<http://librenms.example.com/>. Please note that we have not covered
HTTPS setup in this example, so your LibreNMS install is not secure by
default. Please do not expose it to the public Internet unless you
have configured HTTPS and taken appropriate web server hardening
steps.
We now suggest that you add localhost as your first device from within the WebUI.
# Add the first device
#### Troubleshooting
We now suggest that you add localhost as your first device from within
the WebUI.
If you ever have issues with your install, run validate.php as root in the librenms directory:
# Troubleshooting
cd /opt/librenms
./validate.php
If you ever have issues with your install, run validate.php as root in
the librenms directory:
There are various options for getting help listed on the LibreNMS web site: https://www.librenms.org/#support
```
cd /opt/librenms
./validate.php
```
### What next?
There are various options for getting help listed on the LibreNMS web
site: <https://www.librenms.org/#support>
Now that you've installed LibreNMS, we'd suggest that you have a read of a few other docs to get you going:
# What next?
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
Now that you've installed LibreNMS, we'd suggest that you have a read
of a few other docs to get you going:
### Closing
- [Performance tuning](http://docs.librenms.org/Support/Performance)
- [Alerting](http://docs.librenms.org/Extensions/Alerting/)
- [Device Groups](http://docs.librenms.org/Extensions/Device-Groups/)
- [Auto discovery](http://docs.librenms.org/Extensions/Auto-Discovery/)
We hope you enjoy using LibreNMS. If you do, it would be great if you would consider opting into the stats system we have, please see [this page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on what it is and how to enable it.
# Closing
If you would like to help make LibreNMS better there are [many ways to help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You can also [back LibreNMS on Open Collective](https://t.libren.ms/donations).
We hope you enjoy using LibreNMS. If you do, it would be great if you
would consider opting into the stats system we have, please see [this
page](http://docs.librenms.org/General/Callback-Stats-and-Privacy/) on
what it is and how to enable it.
If you would like to help make LibreNMS better there are [many ways to
help](http://docs.librenms.org/Support/FAQ/#what-can-i-do-to-help). You
can also [back LibreNMS on Open
Collective](https://t.libren.ms/donations).

11
doc/Installation/Migrating-from-Observium.md
View File

@ -1,8 +1,15 @@
source: Installation/Migrating-from-Observium.md
path: blob/master/doc/
A LibreNMS user, [Dan](https://twitter.com/thedanbrown), has kindly provided full details and scripts to be able to migrate from Observium to LibreNMS. ***Note this guide is no longer mantain and the link below is from Web Archive.***
A LibreNMS user, [Dan](https://twitter.com/thedanbrown), has kindly
provided full details and scripts to be able to migrate from Observium
to LibreNMS.
See
[his](https://vlan50.com/2015/04/17/migrating-from-observium-to-librenms/)
blog for full details.
See [Link Here](https://web.archive.org/web/20180815212723/https://vlan50.com/2015/04/17/migrating-from-observium-to-librenms/) Web Archived Site full details.
We have mirrored the scripts he's provided with consent, these are available in the `scripts\Migration` folder of your installation..
We have mirrored the scripts he's provided with consent, these are
available in the `scripts\Migration` folder of your installation..

44
doc/Support/1-Minute-Polling.md
View File

@ -1,28 +1,44 @@
source: Support/1-Minute-Polling.md
path: blob/master/doc/
### Information
# Information
We now have support for polling data at intervals to fit your needs.
> Please be aware of the following:
- You must also change your cron entry for `poller-wrapper.py` for this to work (if you change from the default 300 seconds).
- Your polling _MUST_ complete in the time you configure for the heartbeat step value. See `/pollers/tab=pollers/` in your WebUI for your current value.
- This will only affect RRD files created from the moment you change your settings.
- This change will affect all data storage mechanisms such as MySQL, RRD and InfluxDB. If you decrease the values then please be aware of the increase in space use for MySQL and InfluxDB.
- It's **highly recommended** to configure some [performance optimizations](Performance.md). Keep in mind that all your devices will write all graphs every minute to the disk and that every device has many graphs. The most important thing is probably the [RRDCached](../Extensions/RRDCached.md) configuration that can save a lot of write IOPS.
To make the changes, please navigate to `/settings/sub=external/` within your WebUI. Select RRDTool Setup and then update the two values for step and heartbeat intervals:
- You must also change your cron entry for `poller-wrapper.py` for
this to work (if you change from the default 300 seconds).
- Your polling _MUST_ complete in the time you configure for the
heartbeat step value. See `/pollers/tab=pollers/` in your WebUI for
your current value.
- This will only affect RRD files created from the moment you change
your settings.
- This change will affect all data storage mechanisms such as MySQL,
RRD and InfluxDB. If you decrease the values then please be aware of
the increase in space use for MySQL and InfluxDB.
- It's **highly recommended** to configure some [performance
optimizations](Performance.md). Keep in mind that all your devices
will write all graphs every minute to the disk and that every device
has many graphs. The most important thing is probably the
[RRDCached](../Extensions/RRDCached.md) configuration that can save
a lot of write IOPS.
- Step is how often you want to insert data, so if you change to 1 minute polling then this should be 60.
- Heartbeat is how long to wait for data before registering a null value, i.e 120 seconds.
To make the changes, please navigate to `/settings/sub=external/`
within your WebUI. Select RRDTool Setup and then update the two values
for step and heartbeat intervals:
- Step is how often you want to insert data, so if you change to 1
minute polling then this should be 60.
- Heartbeat is how long to wait for data before registering a null
value, i.e 120 seconds.
### Converting existing RRD files
# Converting existing RRD files
We provide a basic script to convert the default rrd files we generate to utilise your configured step and heartbeat
values. Please do ensure that you backup your RRD files before running this just in case. The script runs on a per
device basis or all devices at once.
We provide a basic script to convert the default rrd files we generate
to utilise your configured step and heartbeat values. Please do ensure
that you backup your RRD files before running this just in case. The
script runs on a per device basis or all devices at once.
> The rrd files must be accessible from the server you run this script from.

39
doc/Support/Adding-a-Device.md
View File

@ -3,37 +3,45 @@ path: blob/master/doc/
# Adding Device
You have two options for adding a new device into LibreNMS. You can add a device via the `cli` or by using the
`WebUI`.
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
## 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).
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 yourhostname [community] [v1|v2c] [port] [udp|udp6|tcp|tcp6]
```
As an example, if your device with the name `mydevice.example.com` is configured to use the community `my_company` using snmp `v2c` then you would enter:
As an example, if your device with the name `mydevice.example.com` is
configured to use the community `my_company` using snmp `v2c` then you
would enter:
```bash
./addhost.php mydevice.example.com 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'`.
> Please note that if the community contains special characters such
> as `$` then you will need to wrap it in `'`. I.e: `'Pa$$w0rd'`.
### WebUI
## 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:
SNMP Port defaults to 161
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: SNMP
Port defaults to 161
![Add device](/img/webui_add_device.png)
### Ping Only Device
You can add ping only devices into LibreNMS through the WebUI. When adding the device switch the SNMP button to "off".
Device will be added into LibreNMS as Ping Only Device and will show ICMP Response Graph.
You can add ping only devices into LibreNMS through the WebUI. When
adding the device switch the SNMP button to "off". Device will be
added into LibreNMS as Ping Only Device and will show ICMP Response Graph.
- Hostname: IP address or DNS name.
- Hardware: Optional you can type in whatever you like.
@ -43,6 +51,9 @@ Device will be added into LibreNMS as Ping Only Device and will show ICMP Respon
![Ping Only](/img/add-ping-only.png)
If you would like to add devices automatically then you will probably want to read the [Auto-discovery Setup](../Extensions/Auto-Discovery.md) guide.
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/index.md)
You may also want to add devices programatically, if so, take a look
at our [API documentation](../API/index.md)

16
doc/Support/CLI-Tools.md
View File

@ -1,24 +1,25 @@
source: Support/CLI-Tools.md
path: blob/master/doc/
### Command line tools
# Command line tools
Here's a brief list of command line tools, some might be missing.
If you think something is missing, feel free to ask us or send a pull request :-)
### purge-ports.php
# purge-ports.php
This script provides CLI access to the "delete port" function of the WebUI.
This might come in handy when trying to clean up old ports after large changes
within the network or when hacking on the poller/discovery functions.
<pre><code>
```
LibreNMS Port purge tool
-p port_id Purge single port by it's port-id
-f file Purge a list of ports, read port-ids from _file_, one on each line
A filename of - means reading from STDIN.
</code></pre>
```
#### Querying port IDs from the database
# Querying port IDs from the database
One simple way to obtain port IDs is by querying the SQL database.
@ -29,8 +30,9 @@ this with the following query:
echo 'SELECT port_id, hostname, ifDescr FROM ports, devices WHERE devices.device_id = ports.device_id AND deleted = 1' | mysql -h your_DB_server -u your_DB_user -p --skip-column-names your_DB_name
```
When you are sure that the list of ports is correct and you want to delete all of them,
you can write the list into a file and call purge-ports.php with that file as input:
When you are sure that the list of ports is correct and you want to
delete all of them, you can write the list into a file and call
purge-ports.php with that file as input:
```
echo 'SELECT port_id FROM ports, devices WHERE devices.device_id = ports.device_id AND deleted = 1' | mysql -h your_DB_server -u your_DB_user -p --skip-column-names your_DB_name > ports_to_delete

44
doc/Support/Cleanup-options.md
View File

@ -1,31 +1,45 @@
source: Support/Cleanup-options.md
path: blob/master/doc/
# Cleanup Options
As the number of devices starts to grow in your LibreNMS install, so will things such as the RRD files, MySQL database containing eventlogs, Syslogs and performance data etc. Your LibreNMS install could become quite large so it becomes necessary to clean up those entries. With Cleanup Options, you can keep in crontrol.
# Cleanup Options
As the number of devices starts to grow in your LibreNMS install, so
will things such as the RRD files, MySQL database containing
eventlogs, Syslogs and performance data etc. Your LibreNMS install
could become quite large so it becomes necessary to clean up those
entries. With Cleanup Options, you can keep in crontrol.
These options rely on ```daily.sh``` running from cron as per the installation instructions.
Cleanup Options are set in ```config.php```
```php
$config['syslog_purge'] = 30;
$config['eventlog_purge'] = 30;
$config['authlog_purge'] = 30;
$config['perf_times_purge'] = 30;
$config['device_perf_purge'] = 7;
$config['rrd_purge'] = 90;// Not set by default
$config['ports_purge'] = true;// Set to false by default
$config['syslog_purge'] = 30;
$config['eventlog_purge'] = 30;
$config['authlog_purge'] = 30;
$config['perf_times_purge'] = 30;
$config['device_perf_purge'] = 7;
$config['rrd_purge'] = 90;// Not set by default
$config['ports_purge'] = true;// Set to false by default
```
These options will ensure data within LibreNMS over X days old is automatically purged. You can alter these individually, values are in days.
**NOTE**: Please be aware that ```$config['rrd_purge']``` is NOT set by default. This option will remove any rrd files that have not been updated for the set amount of days automatically - only enable this if you are comfortable with that happening. (all active rrd files are updated every polling period)
These options will ensure data within LibreNMS over X days old is
automatically purged. You can alter these individually, values are in
days.
**NOTE**: Please be aware that ```$config['rrd_purge']``` is NOT set
by default. This option will remove any rrd files that have not been
updated for the set amount of days automatically - only enable this if
you are comfortable with that happening. (all active rrd files are
updated every polling period)
### Ports Purge
# Ports Purge
Over time as you add devices some interfaces will need to be purged as they are set to be ignored or bad interfaces or marked as deleted.
Over time as you add devices some interfaces will need to be purged as
they are set to be ignored or bad interfaces or marked as deleted.
You can purge all deleted ports from the WebUI (see below) or by setting `$config['ports_purge'] = true;` in `config.php`
You can purge all deleted ports from the WebUI (see below) or by
setting `$config['ports_purge'] = true;` in `config.php`
In the Web UI Under the Ports Tab in the Nav Bar, Click on "Deleted" then click on "Purge all deleted". This will purge all the ports.
In the Web UI Under the Ports Tab in the Nav Bar, Click on "Deleted"
then click on "Purge all deleted". This will purge all the ports.

394
doc/Support/Configuration.md
View File

@ -4,24 +4,29 @@ The options shown below also contain the default values.
If you would like to alter any of these then please add your config option to `config.php`.
### Directories
# Directories
```php
$config['install_dir'] = "/opt/librenms";
```
Set the installation directory (defaults to /opt/librenms), if you clone the GitHub branch to another location ensure you alter this.
Set the installation directory (defaults to /opt/librenms), if you
clone the GitHub branch to another location ensure you alter this.
```php
$config['temp_dir'] = "/tmp";
```
The temporary directory is where images and other temporary files are created on your filesystem.
The temporary directory is where images and other temporary files are
created on your filesystem.
```php
$config['log_dir'] = "/opt/librenms/logs";
```
Log files created by LibreNMS will be stored within this directory.
### Database config
# Database config
These are the configuration options you will need to use to specify to get started.
@ -34,38 +39,44 @@ $config['db_name'] = '';
```
If you use a unix socket, you can specify it with these options:
```php
$config['db_host'] = NULL;
$config['db_port'] = NULL;
$config['db_socket'] = '/run/mysqld/mysqld.sock';
```
### Core
# Core
#### PHP Settings
## PHP Settings
You can change the memory limits for php within `config.php`. The value is in Megabytes and should just be an int value:
You can change the memory limits for php within `config.php`. The
value is in Megabytes and should just be an int value:
`$config['php_memory_limit'] = 128;`
### Programs
## Programs
A lot of these are self explanatory so no further information may be provided. Any extensions that have dedicated
documentation page will be linked to rather than having the config provided.
A lot of these are self explanatory so no further information may be
provided. Any extensions that have dedicated documentation page will
be linked to rather than having the config provided.
#### RRDTool
> You can configure these options within the WebUI now, please avoid setting these options within config.php
### RRDTool
> You can configure these options within the WebUI now, please avoid
> setting these options within config.php
>
> Settings -> External Settings -> RRDTool Setup
```php
$config['rrdtool'] = "/usr/bin/rrdtool";
```
Please see [1 Minute polling](1-Minute-Polling.md) for information on configuring your install to record data more frequently.
Please see [1 Minute polling](1-Minute-Polling.md) for information on
configuring your install to record data more frequently.
### fping
#### fping
```php
$config['fping'] = "/usr/bin/fping";
$config['fping6'] = "fping6";
@ -73,13 +84,19 @@ $config['fping_options']['timeout'] = 500;
$config['fping_options']['count'] = 3;
$config['fping_options']['interval'] = 500;
```
`fping` configuration options:
* `timeout` (`fping` parameter `-t`): Amount of time that fping waits for a response to its first request (in milliseconds). **See note below**
* `count` (`fping` parameter `-c`): Number of request packets to send to each target.
* `interval` (`fping` parameter `-p`): Time in milliseconds that fping waits between successive packets to an individual target.
* `timeout` (`fping` parameter `-t`): Amount of time that fping waits
for a response to its first request (in milliseconds). **See note
below**
* `count` (`fping` parameter `-c`): Number of request packets to send
to each target.
* `interval` (`fping` parameter `-p`): Time in milliseconds that fping
waits between successive packets to an individual target.
> NOTE: Setting a higher timeout value than the interval value can lead to slowing down poller. Example:
> NOTE: Setting a higher timeout value than the interval value can
> lead to slowing down poller. Example:
>
> timeout: 3000
>
@ -87,35 +104,46 @@ $config['fping_options']['interval'] = 500;
>
> interval: 500
>
> In this example, interval will be overwritten by the timeout value of 3000 which is 3 seconds. As we send three icmp packets (count: 3), each one is delayed by 3 seconds which will result in fping taking > 6 seconds to return results.
> In this example, interval will be overwritten by the timeout value
> of 3000 which is 3 seconds. As we send three icmp packets (count:
> 3), each one is delayed by 3 seconds which will result in fping
> taking > 6 seconds to return results.
You can disable the fping / icmp check that is done for a device to be determined to be up on a global or per device basis.
**We don't advise disabling the fping / icmp check unless you know the impact, at worst if you have a large number of devices down
then it's possible that the poller would no longer complete in 5 minutes due to waiting for snmp to timeout.**
You can disable the fping / icmp check that is done for a device to be
determined to be up on a global or per device basis. **We don't advise
disabling the fping / icmp check unless you know the impact, at worst
if you have a large number of devices down then it's possible that the
poller would no longer complete in 5 minutes due to waiting for snmp
to timeout.**
Globally disable fping / icmp check:
```php
$config['icmp_check'] = false;
```
If you would like to do this on a per device basis then you can do so under Device -> Edit -> Misc -> Disable ICMP Test? On
If you would like to do this on a per device basis then you can do so
under Device -> Edit -> Misc -> Disable ICMP Test? On
#### traceroute
LibreNMS uses traceroute / traceroute6 to record debug information when a device is down due to icmp AND you have `$config['debug']['run_trace'] = true;`
set.
### traceroute
LibreNMS uses traceroute / traceroute6 to record debug information
when a device is down due to icmp AND you have
`$config['debug']['run_trace'] = true;` set.
```php
$config['traceroute'] = '/usr/bin/traceroute';
$config['traceroute6'] = '/usr/bin/traceroute6';
```
#### SNMP
### SNMP
```php
$config['snmpwalk'] = "/usr/bin/snmpwalk";
$config['snmpget'] = "/usr/bin/snmpget";
$config['snmpbulkwalk'] = "/usr/bin/snmpbulkwalk";
```
SNMP program locations.
```php
@ -131,7 +159,8 @@ $config['unflatten'] = "/usr/bin/unflatten";
$config['neato'] = "/usr/bin/neato";
$config['sfdp'] = "/usr/bin/sfdp";
```
### Authentication
# Authentication
Generic Authentication settings.
@ -139,10 +168,10 @@ Generic Authentication settings.
$config['password']['min_length'] = 8; // password minimum length for auth that allows user creation
```
### Proxy support
# Proxy support
For alerting and the callback functionality, we support the use of a http proxy setting.
These can be any one of the following:
For alerting and the callback functionality, we support the use of a
http proxy setting. These can be any one of the following:
```php
$config['callback_proxy'] = 'proxy.domain.com';
@ -156,38 +185,48 @@ http_proxy=proxy.domain.com
https_proxy=proxy.domain.com
```
### RRDCached
# RRDCached
[RRDCached](../Extensions/RRDCached.md)
### WebUI Settings
# WebUI Settings
```php
$config['base_url'] = "http://demo.librenms.org";
```
LibreNMS will attempt to detect the URL you are using but you can override that here.
```php
$config['site_style'] = "light";
```
Currently we have a number of styles which can be set which will alter the navigation bar look. dark, light and mono with light being the default.
Currently we have a number of styles which can be set which will alter
the navigation bar look. dark, light and mono with light being the default.
```php
$config['webui']['custom_css'][] = "css/custom/styles.css";
```
You can override a large number of visual elements by creating your own css stylesheet and referencing it here, place any custom css files into
`html/css/custom` so they will be ignored by auto updates. You can specify as many css files as you like, the order they are within your config
will be the order they are loaded in the browser.
You can override a large number of visual elements by creating your
own css stylesheet and referencing it here, place any custom css files
into `html/css/custom` so they will be ignored by auto updates. You
can specify as many css files as you like, the order they are within
your config will be the order they are loaded in the browser.
```php
$config['title_image'] = "images/custom/yourlogo.png";
```
You can override the default logo with yours, place any custom images files into `html/images/custom` so they will be ignored by auto updates.
You can override the default logo with yours, place any custom images
files into `html/images/custom` so they will be ignored by auto updates.
```php
$config['page_refresh'] = "300";
```
Set how often pages are refreshed in seconds. The default is every 5 minutes. Some pages don't refresh at all by design.
Set how often pages are refreshed in seconds. The default is every 5
minutes. Some pages don't refresh at all by design.
```php
$config['front_page'] = "pages/front/default.php";
@ -198,13 +237,17 @@ $config['vertical_summary'] = 0; // Enable to use vertical summary on front page
$config['top_ports'] = 1; // This enables the top X ports box
$config['top_devices'] = 1; // This enables the top X devices box
```
A number of home pages are provided within the install and can be found in html/pages/front/. You can change the default by
setting `front_page`. The other options are used to alter the look of those pages that support it (default.php supports these options).
A number of home pages are provided within the install and can be
found in html/pages/front/. You can change the default by setting
`front_page`. The other options are used to alter the look of those
pages that support it (default.php supports these options).
```php
// This option exists in the web UI, edit it under Global Settings -> webui
$config['webui']['default_dashboard_id'] = 0;
```
Allows the specification of a global default dashboard page for any user who
has not set one in their user preferences. Should be set to dashboard_id of an
existing dashboard that is shared or shared(read). Otherwise, the system will
@ -214,11 +257,13 @@ first login.
```php
$config['login_message'] = "Unauthorised access or use shall render the user liable to criminal and/or civil prosecution.";
```
This is the default message on the login page displayed to users.
```php
$config['public_status'] = false;
```
If this is set to true then an overview will be shown on the login page of devices and the status.
```php
@ -237,11 +282,14 @@ $config['int_peering'] = 1; # Enable Peering Types
$config['int_core'] = 1; # Enable Core Port Types
$config['int_l2tp'] = 0; # Enable L2TP Port Types
```
Enable / disable certain menus from being shown in the WebUI.
You are able to adjust the number and time frames of the quick select time options for graphs and the mini graphs shown per row.
You are able to adjust the number and time frames of the quick select
time options for graphs and the mini graphs shown per row.
Quick select:
```php
$config['graphs']['mini']['normal'] = array(
'day' => '24 Hours',
@ -263,6 +311,7 @@ $config['graphs']['mini']['widescreen'] = array(
```
Mini graphs:
```php
$config['graphs']['row']['normal'] = array(
'sixhour' => '6 Hours',
@ -280,48 +329,67 @@ $config['graphs']['row']['normal'] = array(
```php
$config['web_mouseover'] = true;
```
You can disable the mouseover popover for mini graphs by setting this to false.
```php
$config['enable_lazy_load'] = true;
```
You can disable image lazy loading by setting this to false.
```php
$config['show_overview_tab'] = true;
```
Enable or disable the overview tab for a device.
```php
$config['overview_show_sysDescr'] = true;
```
Enable or disable the sysDescr output for a device.
```php
$config['force_ip_to_sysname'] = false;
```
When using IP addresses as a hostname you can instead represent the devices on the WebUI by its SNMP sysName resulting in an easier to read overview of your network. This would apply on networks where you don't have DNS records for most of your devices.
When using IP addresses as a hostname you can instead represent the
devices on the WebUI by its SNMP sysName resulting in an easier to
read overview of your network. This would apply on networks where you
don't have DNS records for most of your devices.
```php
$config['force_hostname_to_sysname'] = false;
```
When using a dynamic DNS hostname or one that does not resolve, this option would allow you to make use of the SNMP sysName instead as the preferred reference to the device.
When using a dynamic DNS hostname or one that does not resolve, this
option would allow you to make use of the SNMP sysName instead as the
preferred reference to the device.
```php
$config['device_traffic_iftype'][] = '/loopback/';
```
Interface types that aren't graphed in the WebUI. The default array contains more items, please see includes/defaults.inc.php for the full list.
Interface types that aren't graphed in the WebUI. The default array
contains more items, please see includes/defaults.inc.php for the full list.
```php
$config['enable_clear_discovery'] = 1;
```
Administrators are able to clear the last discovered time of a device which will force a full discovery run within the configured 5 minute cron window.
Administrators are able to clear the last discovered time of a device
which will force a full discovery run within the configured 5 minute cron window.
```php
$config['enable_footer'] = 1;
```
Disable the footer of the WebUI by setting `enable_footer` to 0.
You can enable the old style network map (only available for individual devices with links discovered via xDP) by setting:
You can enable the old style network map (only available for
individual devices with links discovered via xDP) by setting:
```php
$config['gui']['network-map']['style'] = 'old';
```
@ -329,50 +397,66 @@ $config['gui']['network-map']['style'] = 'old';
```php
$config['percentile_value'] = X;
```
Show the `X`th percentile in the graph instead of the default 95th percentile.
```php
$config['shorthost_target_length'] = X;
```
The target maximum hostname length when applying the shorthost() function.
You can increase this if you want to try and fit more of the hostname in graph titles.
The default value is 12
However, this can possibly break graph generation if this is very long.
The default value is 12 However, this can possibly break graph
generation if this is very long.
You can enable dynamic graphs within the WebUI under Global Settings -> Webui Settings -> Graph Settings.
You can enable dynamic graphs within the WebUI under Global Settings
-> Webui Settings -> Graph Settings.
Graphs will be movable/scalable without reloading the page:
![Example dynamic graph usage](img/dynamic-graph-usage.gif)
### Stacked Graphs
You can enable stacked graphs instead of the default inverted graphs.
Enabling them is possible via webui Global Settings -> Webui Settings -> Graph settings -> Use stacked graphs
## Stacked Graphs
You can enable stacked graphs instead of the default inverted
graphs. Enabling them is possible via webui Global Settings -> Webui
Settings -> Graph settings -> Use stacked graphs
## Add host settings
The following setting controls how hosts are added. If a host is
added as an ip address it is checked to ensure the ip is not already
present. If the ip is present the host is not added. If host is added
by hostname this check is not performed. If the setting is true
hostnames are resolved and the check is also performed. This helps
prevents accidental duplicate hosts.
### Add host settings
The following setting controls how hosts are added. If a host is added as an ip address it is checked to ensure the ip is not already present. If the ip is present the host is not added.
If host is added by hostname this check is not performed. If the setting is true hostnames are resolved and the check is also performed. This helps prevents accidental duplicate hosts.
```php
$config['addhost_alwayscheckip'] = false; #true - check for duplicate ips even when adding host by name.
#false- only check when adding host by ip.
```
By default we allow hosts to be added with duplicate sysName's, you can disable this with the following config:
By default we allow hosts to be added with duplicate sysName's, you
can disable this with the following config:
```php
$config['allow_duplicate_sysName'] = false;
```
### Global poller and discovery modules
Generally, it is a better to set these [per OS](../Developing/os/Settings.md#poller-and-discovery-modules) or device.
# Global poller and discovery modules
Generally, it is a better to set these [per
OS](../Developing/os/Settings.md#poller-and-discovery-modules) or
device.
```php
$config['discovery_modules]['arp-table'] = true;
$config['poller_modules']['bgp-peers'] = false;
```
### SNMP Settings
# SNMP Settings
Default SNMP options including retry and timeout settings and also default version and port.
Default SNMP options including retry and timeout settings and also
default version and port.
```php
$config['snmp']['timeout'] = 1; # timeout in seconds
@ -382,15 +466,19 @@ $config['snmp']['version'] = ['v2c', 'v3', 'v1']; # Default versions t
$config['snmp']['port'] = 161; # Default port
$config['snmp']['exec_timeout'] = 1200; # execution time limit in seconds
```
>NOTE: `timeout` is the time to wait for an answer and `exec_timeout` is the max time to run a query.
The default v1/v2c snmp community to use, you can expand this array with `[1]`, `[2]`, `[3]`, etc.
>NOTE: `timeout` is the time to wait for an answer and `exec_timeout`
>is the max time to run a query.
The default v1/v2c snmp community to use, you can expand this array
with `[1]`, `[2]`, `[3]`, etc.
```php
$config['snmp']['community'][0] = "public";
```
The default v3 snmp details to use, you can expand this array with `[1]`, `[2]`, `[3]`, etc.
The default v3 snmp details to use, you can expand this array with
`[1]`, `[2]`, `[3]`, etc.
```php
$config['snmp']['v3'][0]['authlevel'] = "noAuthNoPriv"; # noAuthNoPriv | authNoPriv | authPriv
@ -401,13 +489,14 @@ $config['snmp']['v3'][0]['cryptopass'] = ""; # Privacy (Encryption)
$config['snmp']['v3'][0]['cryptoalgo'] = "AES"; # AES | DES
```
### Auto discovery settings
# Auto discovery settings
[Auto-Discovery](../Extensions/Auto-Discovery.md)
### Email configuration
# Email configuration
> You can configure these options within the WebUI now, please avoid setting these options within config.php
> You can configure these options within the WebUI now, please avoid
> setting these options within config.php
```php
$config['email_backend'] = 'mail';
@ -422,18 +511,20 @@ $config['email_smtp_auth'] = false;
$config['email_smtp_username'] = NULL;
$config['email_smtp_password'] = NULL;
```
What type of mail transport to use for delivering emails. Valid options for `email_backend` are mail, sendmail or smtp.
The varying options after that are to support the different transports.
### Alerting
What type of mail transport to use for delivering emails. Valid
options for `email_backend` are mail, sendmail or smtp. The varying
options after that are to support the different transports.
# Alerting
[Alerting](../Alerting/index.md)
### Billing
# Billing
[Billing](../Extensions/Billing-Module.md)
### Global module support
# Global module support
```php
$config['enable_bgp'] = 1; # Enable BGP session collection and display
@ -444,7 +535,7 @@ $config['enable_vrfs'] = 1; # Enable VRFs
$config['enable_sla'] = 0; # Enable Cisco SLA collection and display
```
### Port extensions
# Port extensions
[Port-Description-Parser](../Extensions/Port-Description-Parser.md)
@ -454,29 +545,36 @@ $config['enable_ports_junoseatmvp'] = 0;
$config['enable_ports_adsl'] = 1;
$config['enable_ports_poe'] = 0;
```
Enable / disable additional port statistics.
### External integration
# External integration
#### Rancid
## Rancid
```php
$config['rancid_configs'][] = '/var/lib/rancid/network/configs/';
$config['rancid_repo_type'] = 'svn';
$config['rancid_ignorecomments'] = 0;
```
Rancid configuration, `rancid_configs` is an array containing all of the locations of your rancid files.
Setting `rancid_ignorecomments` will disable showing lines that start with #
#### Oxidized
Rancid configuration, `rancid_configs` is an array containing all of
the locations of your rancid files. Setting `rancid_ignorecomments`
will disable showing lines that start with #
## Oxidized
[Oxidized](../Extensions/Oxidized.md)
#### CollectD
## CollectD
```php
$config['collectd_dir'] = '/var/lib/collectd/rrd';
```
Specify the location of the collectd rrd files. Note that the location in config.php should be consistent with the location set in /etc/collectd.conf and etc/collectd.d/rrdtool.conf
Specify the location of the collectd rrd files. Note that the location
in config.php should be consistent with the location set in
/etc/collectd.conf and etc/collectd.d/rrdtool.conf
```php
<Plugin rrdtool>
@ -487,6 +585,7 @@ Specify the location of the collectd rrd files. Note that the location in config
WritesPerSecond 50
</Plugin>
```
/etc/collectd.conf
```php
@ -497,42 +596,58 @@ LoadPlugin rrdtool
CacheFlush 900
</Plugin>
```
/etc/collectd.d/rrdtool.conf
```php
$config['collectd_sock'] = 'unix:///var/run/collectd.sock';
```
Specify the location of the collectd unix socket. Using a socket allows the collectd graphs to be flushed to disk before being drawn. Be sure that your web server has permissions to write to this socket.
#### Smokeping
Specify the location of the collectd unix socket. Using a socket
allows the collectd graphs to be flushed to disk before being
drawn. Be sure that your web server has permissions to write to this socket.
## Smokeping
[Smokeping](../Extensions/Smokeping.md)
#### NFSen
## NFSen
[NFSen](../Extensions/NFSen.md)
### Location mapping
## Location mapping
If you just want to set GPS coordinates on a location, you should visit Devices > Geo Locations > All Locations and edit the coordinates there.
If you just want to set GPS coordinates on a location, you should
visit Devices > Geo Locations > All Locations and edit the coordinates
there.
Exact Matching:
```php
$config['location_map']['Under the Sink'] = "Under The Sink, The Office, London, UK";
```
Regex Matching:
```php
$config['location_map_regex']['/Sink/'] = "Under The Sink, The Office, London, UK";
```
Regex Match Substitution:
```php
$config['location_map_regex_sub']['/Sink/'] = "Under The Sink, The Office, London, UK [lat, long]";
```
If you have an SNMP SysLocation of "Rack10,Rm-314,Sink", Regex Match Substition yields "Rack10,Rm-314,Under The Sink, The Office, London, UK [lat, long]". This allows you to keep the SysLocation string short and keeps Rack/Room/Building information intact after the substitution.
The above are examples, these will rewrite device snmp locations so you don't need to configure full location within snmp.
If you have an SNMP SysLocation of "Rack10,Rm-314,Sink", Regex Match
Substition yields "Rack10,Rm-314,Under The Sink, The Office, London,
UK [lat, long]". This allows you to keep the SysLocation string short
and keeps Rack/Room/Building information intact after the substitution.
### Interfaces to be ignored
The above are examples, these will rewrite device snmp locations so
you don't need to configure full location within snmp.
# Interfaces to be ignored
Examples:
@ -541,7 +656,9 @@ $config['bad_if'][] = "voip-null";
$config['bad_iftype'][] = "voiceEncap";
$config['bad_if_regexp'][] = '/^lo[0-9].*/'; // loopback
```
Numerous defaults exist for this array already (see includes/defaults.inc.php for the full list). You can expand this list
Numerous defaults exist for this array already (see
includes/defaults.inc.php for the full list). You can expand this list
by continuing the array.
`bad_if` is matched against the ifDescr value.
@ -554,7 +671,7 @@ by continuing the array.
`bad_ifalias_regexp` is matched against the ifAlias value as a regular expression.
### Interfaces that shouldn't be ignored
# Interfaces that shouldn't be ignored
Examples:
@ -563,44 +680,51 @@ $config['good_if'][] = 'FastEthernet';
$config['os']['ios']['good_if'][] = 'FastEthernet';
```
`good_if` is matched against ifDescr value. This can be a bad_if value as well which would stop that port from being ignored.
I.e If bad_if and good_if both contained FastEthernet then ports with this value in the ifDescr will be valid.
`good_if` is matched against ifDescr value. This can be a bad_if value
as well which would stop that port from being ignored. I.e If bad_if
and good_if both contained FastEthernet then ports with this value in
the ifDescr will be valid.
### Interfaces to be rewritten
# Interfaces to be rewritten
```php
$config['rewrite_if']['cpu'] = 'Management Interface';
$config['rewrite_if_regexp']['/cpu /'] = 'Management ';
```
Entries defined in `rewrite_if` are being replaced completely.
Entries defined in `rewrite_if_regexp` only replace the match.
Matches are compared case-insensitive.
### Entity sensors to be ignored
# Entity sensors to be ignored
Some devices register bogus sensors as they are returned via SNMP but either don't exist or just don't return data.
This allows you to ignore those based on the descr field in the database. You can either ignore globally or on a per
os basis.
Some devices register bogus sensors as they are returned via SNMP but
either don't exist or just don't return data. This allows you to
ignore those based on the descr field in the database. You can either
ignore globally or on a per os basis.
```php
$config['bad_entity_sensor_regex'][] = '/Physical id [0-9]+/';
$config['os']['cisco']['bad_entity_sensor_regex'] = '/Physical id [0-9]+/';
```
### Entity sensors limit values
# Entity sensors limit values
Vendors may give some limit values (or thresholds) for the discovered sensors. By default, when no such value is given,
both high and low limit values are guessed, based on the value measured during the initial discovery.
Vendors may give some limit values (or thresholds) for the discovered
sensors. By default, when no such value is given, both high and low
limit values are guessed, based on the value measured during the initial discovery.
When it is preferred to have no high and/or low limit values at all if
these are not provided by the vendor, the guess method can be disabled:
When it is preferred to have no high and/or low limit values at all if these are not provided by the vendor, the guess
method can be disabled:
```php
$config['sensors']['guess_limits'] = false;
```
### Storage configuration
# Storage configuration
Mounted storage / mount points to ignore in discovery and polling.
```php
$config['ignore_mount_removable'] = 1;
$config['ignore_mount_network'] = 1;
@ -630,20 +754,21 @@ $config['ignore_mount_regexp'][] = "/UMA/";
```
Custom storage warning percentage
```php
$config['storage_perc_warn'] = 60;
$config['os']['linux']['storage_perc_warn'] = 60;
```
### IRC Bot
# IRC Bot
[IRC Bot](../Extensions/IRC-Bot.md)
### Authentication
# Authentication
[Authentication](../Extensions/Authentication.md)
### Cleanup options
# Cleanup options
These options rely on daily.sh running from cron as per the installation instructions.
@ -657,51 +782,58 @@ $config['alert_log_purge'] = 365;
$config['port_fdb_purge'] = 10;
$config['rrd_purge'] = 90;// Not set by default
```
These options will ensure data within LibreNMS over X days old is automatically purged. You can alter these individually.
values are in days.
> NOTE: Please be aware that `$config['rrd_purge']` is _NOT_ set by default. This option will remove any old data within
the rrd directory automatically - only enable this if you are comfortable with that happening.
These options will ensure data within LibreNMS over X days old is
automatically purged. You can alter these individually. values are in days.
### Syslog options
> NOTE: Please be aware that `$config['rrd_purge']` is _NOT_ set by
> default. This option will remove any old data within the rrd
> directory automatically - only enable this if you are comfortable
> with that happening.
# Syslog options
[Syslog](../Extensions/Syslog.md)
### Virtualization
# Virtualization
```php
$config['enable_libvirt'] = 1;
$config['libvirt_protocols'] = array("qemu+ssh","xen+ssh");
$config['libvirt_username'] = 'root';
```
Enable this to switch on support for libvirt along with `libvirt_protocols`
to indicate how you connect to libvirt. You also need to:
1. Generate a non-password-protected ssh key for use by LibreNMS, as the
1. Generate a non-password-protected ssh key for use by LibreNMS, as the
user which runs polling & discovery (usually `librenms`).
2. On each VM host you wish to monitor:
- Configure public key authentication from your LibreNMS server/poller by
adding the librenms public key to `~root/.ssh/authorized_keys`.
- (xen+ssh only) Enable libvirtd to gather data from xend by setting
`(xend-unix-server yes)` in `/etc/xen/xend-config.sxp` and
restarting xend and libvirtd.
1. On each VM host you wish to monitor:
1. Configure public key authentication from your LibreNMS server/poller by
adding the librenms public key to `~root/.ssh/authorized_keys`.
1. (xen+ssh only) Enable libvirtd to gather data from xend by setting
`(xend-unix-server yes)` in `/etc/xen/xend-config.sxp` and
restarting xend and libvirtd.
To test your setup, run `virsh -c qemu+ssh://vmhost/system list` or
`virsh -c xen+ssh://vmhost list` as your librenms polling user.
### BGP Support
# BGP Support
```php
$config['astext']['65332'] = "Cymru FullBogon Feed";
```
You can use this array to rewrite the description of ASes that you have discovered.
### Auto updates
# Auto updates
[Updating](../General/Updating.md)
### IPMI
Setup the types of IPMI protocols to test a host for and in what order. Don't forget to install ipmitool on the monitoring host.
# IPMI
Setup the types of IPMI protocols to test a host for and in what
order. Don't forget to install ipmitool on the monitoring host.
```php
$config['ipmi']['type'] = array();
@ -711,19 +843,19 @@ $config['ipmi']['type'][] = "imb";
$config['ipmi']['type'][] = "open";
```
### Distributed poller settings
# Distributed poller settings
[Distributed Poller](../Extensions/Distributed-Poller.md)
## API Settings
# API Settings
### CORS Support
# CORS Support
https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS>
CORS support for the API is disabled by default. Below you will find
the standard options, all of which you can configure.
CORS support for the API is disabled by default. Below you will find the standard options,
all of which you can configure.
```php
$config['api']['cors']['enabled'] = false;
$config['api']['cors']['origin'] = '*';

44
doc/Support/Device-Notes/Carel-pCOweb-Devices.md
View File

@ -2,27 +2,51 @@ source: Carel-pCOweb-Devices.md
path: blob/master/doc/
# Carel pCOweb Devices
The pCOWeb card is used to interface the pCO system to networks that use the HVAC protocols based on the Ethernet physical standard such the SNMP. The problem with this card is that the implementation is based on the final manufacturer of the HVAC (Heating, Ventilation and Air Conditioning) and not based on a standard given by Carel. So each pCOweb card has a different configuration that needs a different MIB depending on the manufacturer implementation.
The main problem is that LibreNMS will discover this card as pCOweb and not as your real manufacturer like it should. A solution was found to bypass this issue, but it's LibreNMS independent and you need to first configure your pCOWeb through the admin interface.
The pCOWeb card is used to interface the pCO system to networks that
use the HVAC protocols based on the Ethernet physical standard such
the SNMP. The problem with this card is that the implementation is
based on the final manufacturer of the HVAC (Heating, Ventilation and
Air Conditioning) and not based on a standard given by Carel. So each
pCOweb card has a different configuration that needs a different MIB
depending on the manufacturer implementation.
The main problem is that LibreNMS will discover this card as pCOweb
and not as your real manufacturer like it should. A solution was found
to bypass this issue, but it's LibreNMS independent and you need to
first configure your pCOWeb through the admin interface.
## Configuring the pCOweb card SNMP for LibreNMS
First you need to configure your SNMP card using the admin interface. An SNMP tab in the configuration menu leaves you the choice to choose a System OID. This is a little tricky but based on this information we defined a "standard" for all implementation of Carel products with LibreNMS.
First you need to configure your SNMP card using the admin
interface. An SNMP tab in the configuration menu leaves you the choice
to choose a System OID. This is a little tricky but based on this
information we defined a "standard" for all implementation of Carel
products with LibreNMS.
![pCOweb](/img/carelpcowebsystemoid.png)
The base Carel OID is 1.3.6.1.4.1.9839. To this OID we will add the final manufacturer Enterprise OID. You can find all enterprise OID [following this link](https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers). This will allow us to create a specific support for this device.
The base Carel OID is 1.3.6.1.4.1.9839. To this OID we will add the
final manufacturer Enterprise OID. You can find all enterprise OID
[following this
link](https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers). This
will allow us to create a specific support for this device.
Example for the Rittal IT Chiller that uses a pCOweb card:
1. Base Carel OID : **1.3.6.1.4.1.9839**
2. Rittal (the manufacturer) base enterprise OID : **2606**
3. Adding value to identify this device in LibreNMS : **1**
4. Complete System OID for a Rittal Chiller using a Carel pCOweb card: **1.3.6.1.4.1.9839.2606.1**
After constructing the correct System OID for your SNMP card, you can start the LibreNMS [new OS implementation](Developing/Support-New-OS/) and use this new OID as sysObjectID for the YAML definition file.
1. Base Carel OID : **1.3.6.1.4.1.9839**
1. Rittal (the manufacturer) base enterprise OID : **2606**
1. Adding value to identify this device in LibreNMS : **1**
1. Complete System OID for a Rittal Chiller using a Carel pCOweb card: **1.3.6.1.4.1.9839.2606.1**
After constructing the correct System OID for your SNMP card, you can
start the LibreNMS [new OS implementation](Developing/Support-New-OS/)
and use this new OID as sysObjectID for the YAML definition file.
## pCOweb card already supported
LibreNMS is ready for the devices listed in this table. You only need to configure your pCOweb card with the accorded System OID:
LibreNMS is ready for the devices listed in this table. You only need
to configure your pCOweb card with the accorded System OID:
| Manufacturer | Description | System OID |
| ------------ | ------------- | ------------ |

57
doc/Support/Device-Sensors.md
View File

@ -1,30 +1,40 @@
source: Support/Device-Sensors.md
path: blob/master/doc/
## Device Sensors
# Device Sensors
LibreNMS has a standard for device sensors they are split into categories.
This doc is to help users understand device sensors in general, if you need help with developing sensors for a device please see the Contributing + Developing section.
LibreNMS has a standard for device sensors they are split into
categories. This doc is to help users understand device sensors in
general, if you need help with developing sensors for a device please
see the Contributing + Developing section.
### Health Sensors
## Health Sensors
The High and Low values of these sensors can be edited in Web UI by going to the device settings -> Health. There you can set your own custom
High and Low values. List of these sensors can be found here [Link](../Developing/os/Health-Information.md)
The High and Low values of these sensors can be edited in Web UI by
going to the device settings -> Health. There you can set your own
custom High and Low values. List of these sensors can be found here
[Link](../Developing/os/Health-Information.md)
**Note** Some values are defined by the manufactures and others are auto calculated when you add the device into librenms. Keep in mind every environment is different and may require user input.
**Note** Some values are defined by the manufactures and others are
auto calculated when you add the device into librenms. Keep in mind
every environment is different and may require user input.
## Wireless Sensors
### Wireless Sensors
Some Wireless have High and Low values of these sensors can be edited
in Web UI by going to the device settings -> Wireless Sensors There
you can set your own custom High and Low values. List of these sensors
can be found here [Link](../Developing/os/Wireless-Sensors.md)
Some Wireless have High and Low values of these sensors can be edited in Web UI by going to the device settings -> Wireless Sensors There you can set your own custom High and Low values. List of these sensors can be found here [Link](../Developing/os/Wireless-Sensors.md)
**Note** Some values are defined by the manufactures and others are
auto calculated when you add the device into librenms. Keep in mind
every environment is different and may require user input.
**Note** Some values are defined by the manufactures and others are auto calculated when you add the device into librenms. Keep in mind every environment is different and may require user input.
## State Sensors
### State Sensors
Return states of device entries sensors states. For example.
Return states of device entries sensors states. For example.
Drive Status, Memory Status, Power Supply Status.
Drive Status, Memory Status, Power Supply Status.
```
0 = OK
@ -33,14 +43,17 @@ Drive Status, Memory Status, Power Supply Status.
3 = Unknown
```
### Alerting Sensors
## Alerting Sensors
These alert rules can be found inside the Alert Rules Collection. The alert rules below are
the default alert rules, there are more device-specific alert rules in the alerts collection.
These alert rules can be found inside the Alert Rules Collection. The
alert rules below are the default alert rules, there are more
device-specific alert rules in the alerts collection.
**Sensor Over Limit Alert Rule:** Will alert on any sensor value that is over the limit.
**Sensor Over Limit Alert Rule:** Will alert on any sensor value that
is over the limit.
**Sensor Under Limit Alert Rule:** Will alert on any sensor value that is under the limit.
**Sensor Under Limit Alert Rule:** Will alert on any sensor value that
is under the limit.
**Remember** you can set these limits inside device settings in the Web UI.
@ -48,6 +61,8 @@ the default alert rules, there are more device-specific alert rules in the alert
**State Sensor Warning:** Will alert on any state that returns warning = 1
**Wireless Sensor Over Limit Alert Rule:** Will Alert on sensors that listed in device settings under Wireless.
**Wireless Sensor Over Limit Alert Rule:** Will Alert on sensors that
listed in device settings under Wireless.
**Wireless Sensor Under Limit Alert Rule:** Will Alert on sensors that listed in device settings under Wireless.
**Wireless Sensor Under Limit Alert Rule:** Will Alert on sensors that
listed in device settings under Wireless.

29
doc/Support/Device-Troubleshooting.md
View File

@ -1,26 +1,33 @@
source: Support/Device-Troubleshooting.md
path: blob/master/doc/
# Capture Debug Information
You can use this feature to run Debug on Discovery, Poller, SNMP, Alerts.
This output information could be helpful for you in troubleshooting a device or when requesting help.
You can use this feature to run Debug on Discovery, Poller, SNMP,
Alerts. This output information could be helpful for you in
troubleshooting a device or when requesting help.
This feature can be found by going to the device that you are troubleshooting in the webui, clicking on the settings icon menu on far right and selecting
Capture.
This feature can be found by going to the device that you are
troubleshooting in the webui, clicking on the settings icon menu on
far right and selecting Capture.
![Capture-Debug-Icon](/img/capture-debug-icon.png)
### Discovery
## Discovery
Discovery will run and output debug infomation.
### Poller
## Poller
Poller will run and output debug information.
### SNMP
SNMP will run SNMP Bulk Walk on the device and output the information.
### Alerts
Alerts Capture is handy when you are creating alerts and need to see if your alert rule matches.
## SNMP
SNMP will run SNMP Bulk Walk on the device and output the information.
## Alerts
Alerts Capture is handy when you are creating alerts and need to see
if your alert rule matches.
![device-troubleshooting](/img/device-troubleshooting.png)

77
doc/Support/Discovery Support.md
View File

@ -1,10 +1,13 @@
source: Support/Discovery Support.md
path: blob/master/doc/
### discovery.php
This document will explain how to use discovery.php to debug issues or manually running to process data.
# discovery.php
This document will explain how to use discovery.php to debug issues or
manually running to process data.
## Command options
#### Command options
```bash
-h <device id> | <device hostname wildcard> Poll single device
-h odd Poll odd numbered devices (same as -i 2 -n 0)
@ -20,27 +23,33 @@ Debugging and testing options:
-d Enable debugging output
-v Enable verbose debugging output
-m Specify module(s) to be run. Comma separate modules, submodules may be added with /
```
`-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.
`-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 but with most sensitive data masked) so that you can see what is happening during a discovery run. This includes things like rrd updates, SQL queries and response from snmp.
`-d` Enables debugging output (verbose output but with most sensitive
data masked) so that you can see what is happening during a discovery
run. This includes things like rrd updates, SQL queries and response
from snmp.
`-v` Enables verbose debugging output with all data in tact.
`-m` This enables you to specify the module you want to run for discovery.
#### Discovery wrapper
# Discovery wrapper
We have a `discovery-wrapper.py` script which is based on `poller-wrapper.py` by [Job Snijders](https://github.com/job). This script is currently the default.
We have a `discovery-wrapper.py` script which is based on
`poller-wrapper.py` by [Job Snijders](https://github.com/job). This
script is currently the default.
If you need to debug the output of discovery-wrapper.py then you can add `-d` to the end of the command - it is NOT recommended to do this in cron.
If you need to debug the output of discovery-wrapper.py then you can
add `-d` to the end of the command - it is NOT recommended to do this
in cron.
If you want to switch back to discovery.php then you can replace:
@ -50,10 +59,12 @@ With:
`33 */6 * * * librenms /opt/librenms/discovery.php -h all >> /dev/null 2>&1`
#### Discovery config
# 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 -> Device -> Settings -> Modules.
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 -> Device -> Settings ->
Modules.
```php
$config['discovery_modules']['os'] = true;
@ -97,12 +108,14 @@ $config['discovery_modules']['wireless'] = true;
$config['discovery_modules']['fdb-table'] = true;
```
#### OS based Discovery config
## OS based Discovery config
You can enable or disable modules for a specific OS by add corresponding line in `config.php`
OS based settings have preference over global. Device based settings have preference over all others
You can enable or disable modules for a specific OS by add
corresponding line in `config.php` OS based settings have preference
over global. Device based settings have preference over all others
Discover performance improvement can be achieved by deactivating all modules that are not supported by specific OS.
Discover performance improvement can be achieved by deactivating all
modules that are not supported by specific OS.
E.g. to deactivate spanning tree but activate discovery-arp module for linux OS
@ -111,11 +124,12 @@ $config['os']['linux']['discovery_modules']['stp'] = false;
$config['os']['linux']['discovery_modules']['discovery-arp'] = true;
```
#### Discovery modules
## 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`: 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.
@ -143,7 +157,8 @@ $config['os']['linux']['discovery_modules']['discovery-arp'] = true;
`arp-table`: Detection of the ARP table for the device.
`fdb-table`: Detection of the Forwarding DataBase table for the device, with history data.
`fdb-table`: Detection of the Forwarding DataBase table for the
device, with history data.
`discovery-arp`: Auto discovery via ARP.
@ -175,36 +190,44 @@ $config['os']['linux']['discovery_modules']['discovery-arp'] = true;
`charge`: APC Charge detection and support.
#### Running
# 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
# 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:
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
```
Using `-d` shouldn't output much sensitive information, `-v` will so 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.
Using `-d` shouldn't output much sensitive information, `-v` will so
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:

10
doc/Support/Environment-Variables.md
View File

@ -1,7 +1,9 @@
# Environment Variables
path: blob/master/doc/
LibreNMS allows certain settings to be set via the environment or through the .env file.
# Environment Variables
LibreNMS allows certain settings to be set via the environment or
through the .env file.
## Database
@ -34,7 +36,8 @@ Set the base url for generated urls. Do not set this if it is not needed.
You may need to set this when using reverse proxies combined with a subdirectory.
Generally, LibreNMS will make correct URLs (especially if you have set up your proxy variables correctly)
Generally, LibreNMS will make correct URLs (especially if you have set
up your proxy variables correctly)
```dotenv
APP_URL=http://librenms/
@ -53,6 +56,7 @@ LIBRENMS_GROUP=librenms
## Debug
Increases the amount of information shown when an error occurs.
> WARNING: This may leak information, do not leave enabled.
```dotenv

38
doc/Support/Example-Hardware-Setup.md
View File

@ -1,6 +1,7 @@
source: Support/Example-Hardware-Setup.md
path: blob/master/doc/
### Example hardware setups
# Example hardware setups
The information in this document is direct from users, it's a place for people to share their
setups so you have an idea of what may be required for your install.
@ -13,7 +14,7 @@ select count(*) from ports where `deleted` = 0;
select count(*) from sensors where `sensor_deleted` = 0;
```
#### [laf](https://github.com/laf)
## [laf](https://github.com/laf)
> Home
@ -32,7 +33,7 @@ Running in Proxmox.
| Health sensors | 47 | - |
| Load | < 0.1 | < 0.1 |
#### [Vente-Privée](https://github.com/vp-noc)
## [Vente-Privée](https://github.com/vp-noc)
> NOC
@ -49,7 +50,7 @@ Running in Proxmox.
| Health sensors | 6238 | - |
| Load | < 0.5 | < 0.5 |
#### [KKrumm](https://github.com/kkrumm1)
## [KKrumm](https://github.com/kkrumm1)
> Home
@ -66,7 +67,7 @@ Running in Proxmox.
| Health sensors | 44 | |
| Load | < 2.5 | |
#### [KKrumm](https://github.com/kkrumm1)
## [KKrumm](https://github.com/kkrumm1)
> Work
@ -83,7 +84,7 @@ Running in Proxmox.
| Health sensors | 3223 | |
| Load | < 14.5 | |
#### [CppMonkey(KodApa85)](https://github.com/cppmonkey)
## [CppMonkey(KodApa85)](https://github.com/cppmonkey)
> Home
@ -100,7 +101,7 @@ Running in Proxmox.
| Health sensors | 70 | |
| Load | < 0.5 | |
#### [CppMonkey(KodApa85)](https://github.com/cppmonkey)
## [CppMonkey(KodApa85)](https://github.com/cppmonkey)
> Dev
@ -119,7 +120,7 @@ Running in Ganeti
| Health sensors | 884 | |
| Load | < 1.0 | |
#### [CppMonkey(KodApa85)](https://github.com/cppmonkey)
## [CppMonkey(KodApa85)](https://github.com/cppmonkey)
> Work NOC
@ -138,7 +139,7 @@ Running in Ganeti Cluster with 2x Dell PER730xd - 64GB, Dual E5-2660 v3
| Health sensors | 2329 | |
| Load | < 2.5 | < 1.5 |
#### [LaZyDK](https://github.com/lazydk)
## [LaZyDK](https://github.com/lazydk)
> Home
@ -155,7 +156,7 @@ Running in Ganeti Cluster with 2x Dell PER730xd - 64GB, Dual E5-2660 v3
| Health sensors | 117 | |
| Load | < 0.92 | |
#### [SirMaple](https://github.com/sirmaple)
## [SirMaple](https://github.com/sirmaple)
> Home
@ -171,3 +172,20 @@ Running in Ganeti Cluster with 2x Dell PER730xd - 64GB, Dual E5-2660 v3
| Ports | 196 | |
| Health sensors | 207 | |
| Load | < 3.65 | |
## [VVelox](https://github.com/VVelox)
> Home / Dev
| | LibreNMS | MariaDB |
| -------------- | ------------------- | ------------------- |
| Type | Supermicro X7SPA-HF | Same Server |
| OS | FreeBSD 12-STABLE | |
| CPU | Intel Atom D525 | |
| Memory | 4GB | |
| Disk Type | Raid 1, SATA | |
| Disk Space | 1TB | |
| Devices | 17 | |
| Ports | 174 | |
| Health sensors | 76 | |
| Load | < 3 | |

512
doc/Support/FAQ.md
View File

@ -1,177 +1,244 @@
source: Support/FAQ.md
path: blob/master/doc/
### Getting started
- [How do I install LibreNMS?](#faq1)
- [How do I add a device?](#faq2)
- [How do I get help?](#faq3)
- [What are the supported OSes for installing LibreNMS on?](#faq4)
- [Do you have a demo available?](#faq5)
### Support
- [How does LibreNMS use MIBs?](#how-does-librenms-use-mibs)
- [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)
- [Why do I get a lot apache or rrdtool zombies in my process list?](#faq14)
- [Why do I see traffic spikes in my graphs?](#faq15)
- [Why do I see gaps in my graphs?](#faq17)
- [How do I change the IP / hostname of a device?](#faq16)
- [My device doesn't finish polling within 300 seconds](#faq19)
- [Things aren't working correctly?](#faq18)
- [What do the values mean in my graphs?](#faq21)
- [Why does a device show as a warning?](#faq22)
- [Why do I not see all interfaces in the Overall traffic graph for a device?](#faq23)
- [How do I move my LibreNMS install to another server?](#faq24)
- [Why is my EdgeRouter device not detected?](#faq25)
- [Why are some of my disks not showing?](#faq26)
- [Why are my disks reporting an incorrect size?](#faq27)
- [What is the Difference between Disable Device and Ignore a Device?](#faq28)
- [Why can't Normal and Global View users see Oxidized?](#faq29)
- [What is the Demo User for?](#faq30)
- [Why does modifying 'Default Alert Template' fail?](#faq31)
- [Why would alert un-mute itself](#faq32)
- [How do I change the Device Type?](#faq33)
- [Where do I update my database credentials?](#faq-where-do-i-update-my-database-credentials)
- [My reverse proxy is not working](#my-reverse-proxy-is-not-working)
- [My alerts aren't being delivered on time](#my-alerts-aren't-being-delivered-on-time)
- [My alert templates stopped working](#my-alert-templates-stopped-working)
# Getting started
### Developing
- [How do I add support for a new OS?](#faq8)
- [What information do you need to add a new OS?](#faq20)
- [What can I do to help?](#faq9)
- [How can I test another users branch?](#faq13)
- [How do I install LibreNMS?](#faq1)
- [How do I add a device?](#faq2)
- [How do I get help?](#faq3)
- [What are the supported OSes for installing LibreNMS on?](#faq4)
- [Do you have a demo available?](#faq5)
#### <a name="faq1"> How do I install LibreNMS?</a>
# Support
- [How does LibreNMS use MIBs?](#how-does-librenms-use-mibs)
- [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)
- [Why do I get a lot apache or rrdtool zombies in my process list?](#faq14)
- [Why do I see traffic spikes in my graphs?](#faq15)
- [Why do I see gaps in my graphs?](#faq17)
- [How do I change the IP / hostname of a device?](#faq16)
- [My device doesn't finish polling within 300 seconds](#faq19)
- [Things aren't working correctly?](#faq18)
- [What do the values mean in my graphs?](#faq21)
- [Why does a device show as a warning?](#faq22)
- [Why do I not see all interfaces in the Overall traffic graph for a device?](#faq23)
- [How do I move my LibreNMS install to another server?](#faq24)
- [Why is my EdgeRouter device not detected?](#faq25)
- [Why are some of my disks not showing?](#faq26)
- [Why are my disks reporting an incorrect size?](#faq27)
- [What is the Difference between Disable Device and Ignore a Device?](#faq28)
- [Why can't Normal and Global View users see Oxidized?](#faq29)
- [What is the Demo User for?](#faq30)
- [Why does modifying 'Default Alert Template' fail?](#faq31)
- [Why would alert un-mute itself](#faq32)
- [How do I change the Device Type?](#faq33)
- [Where do I update my database credentials?](#faq-where-do-i-update-my-database-credentials)
- [My reverse proxy is not working](#my-reverse-proxy-is-not-working)
- [My alerts aren't being delivered on time](#my-alerts-aren't-being-delivered-on-time)
- [My alert templates stopped working](#my-alert-templates-stopped-working)
# Developing
- [How do I add support for a new OS?](#faq8)
- [What information do you need to add a new OS?](#faq20)
- [What can I do to help?](#faq9)
- [How can I test another users branch?](#faq13)
## <a name="faq1"> How do I install LibreNMS?</a>
This is currently well documented within the doc folder of the installation files.
Please see the following [doc](http://docs.librenms.org/Installation/Installing-LibreNMS/)
#### <a name="faq2"> How do I add a device?</a>
## <a name="faq2"> How do I add a device?</a>
You have two options for adding a new device into LibreNMS.
1. 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).
1: 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).
```ssh
./addhost.php [community] [v1|v2c] [port] [udp|udp6|tcp|tcp6]
```
> Please note that if the community contains special characters such as `$` then you will need to wrap it in `'`. I.e: `'Pa$$w0rd'`.
> Please note that if the community contains special characters such
> as `$` then you will need to wrap it in `'`. I.e: `'Pa$$w0rd'`.
2. Using the web interface, go to Devices and then Add Device. Enter the details required for the device that you want to add and then click 'Add Host'.
2: Using the web interface, go to Devices and then Add Device. Enter
the details required for the device that you want to add and then
click 'Add Host'.
#### <a name="faq3"> How do I get help?</a>
## <a name="faq3"> How do I get help?</a>
[Getting Help](index.md)
#### <a name="faq4"> What are the supported OSes for installing LibreNMS on?</a>
## <a name="faq4"> What are the supported OSes for installing LibreNMS on?</a>
Supported is quite a strong word :) The 'officially' supported distros are:
- Ubuntu / Debian
- Red Hat / CentOS
- Gentoo
- Ubuntu / Debian
- Red Hat / CentOS
- Gentoo
However we will always aim to help wherever possible so if you are running a distro that isn't one of the above then give it a try anyway and if you need help then jump on the [discord server](https://t.libren.ms/discord).
However we will always aim to help wherever possible so if you are
running a distro that isn't one of the above then give it a try anyway
and if you need help then jump on the [discord
server](https://t.libren.ms/discord).
#### <a name="faq5"> Do you have a demo available?</a>
## <a name="faq5"> Do you have a demo available?</a>
We do indeed, you can find access to the demo [here](https://demo.librenms.org)
### <a name='how-does-librenms-use-mibs'>How does LibreNMS use MIBs?</a>
LibreNMS does not parse MIBs to discover sensors for devices. LibreNMS uses static discovery definitions written in YAML or PHP. Therefore, updating a MIB alone will not improve OS support, the definitions must be updated. LibreNMS only uses MIBs to make OIDs easier to read.
## <a name='how-does-librenms-use-mibs'>How does LibreNMS use MIBs?</a>
#### <a name="faq6"> Why do I get blank pages sometimes in the WebUI?</a>
LibreNMS does not parse MIBs to discover sensors for devices.
LibreNMS uses static discovery definitions written in YAML or PHP.
Therefore, updating a MIB alone will not improve OS support, the
definitions must be updated. LibreNMS only uses MIBs to make OIDs
easier to read.
You can enable debug information by setting `APP_DEBUG=true` in your .env. (Do not leave this enabled, it could leak private data)
## <a name="faq6"> Why do I get blank pages sometimes in the WebUI?</a>
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 [config.php](Configuration.md#core).
You can enable debug information by setting `APP_DEBUG=true` in your
.env. (Do not leave this enabled, it could leak private data)
#### <a name="faq10"> Why do I not see any graphs?</a>
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
[config.php](Configuration.md#core).
The easiest way to check if all is well is to run `./validate.php` as root from within your install directory. This should give you info on why things aren't working.
## <a name="faq10"> Why do I not see any graphs?</a>
One other reason could be a restricted snmpd.conf file or snmp view which limits the data sent back. If you use net-snmp then we suggest using
the [included snmpd.conf](https://raw.githubusercontent.com/librenms/librenms/master/snmpd.conf.example) file.
The easiest way to check if all is well is to run `./validate.php` as
root from within your install directory. This should give you info on
why things aren't working.
#### <a name="faq7"> How do I debug pages not loading correctly?</a>
One other reason could be a restricted snmpd.conf file or snmp view
which limits the data sent back. If you use net-snmp then we suggest
using the [included
snmpd.conf](https://raw.githubusercontent.com/librenms/librenms/master/snmpd.conf.example)
file.
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.
## <a name="faq7"> How do I debug pages not loading correctly?</a>
You can enable debug information by setting `APP_DEBUG=true` in your .env. (Do not leave this enabled, it could leak private data)
To see additional information, run `./scripts/composer_wrapper.php install`, to install additional debug tools.
This will add a debug bar at the bottom of every page that will show you detailed debug information.
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.
#### <a name="faq11"> How do I debug the discovery process?</a>
You can enable debug information by setting `APP_DEBUG=true` in your
.env. (Do not leave this enabled, it could leak private data) To see
additional information, run `./scripts/composer_wrapper.php install`,
to install additional debug tools. This will add a debug bar at the
bottom of every page that will show you detailed debug information.
Please see the [Discovery Support](http://docs.librenms.org/Support/Discovery Support/) document for further details.
## <a name="faq11"> How do I debug the discovery process?</a>
#### <a name="faq12"> How do I debug the poller process?</a>
Please see the [Discovery
Support](http://docs.librenms.org/Support/Discovery Support/) document
for further details.
Please see the [Poller Support](http://docs.librenms.org/Support/Poller Support/) document for further details.
## <a name="faq12"> How do I debug the poller process?</a>
#### <a name="faq14"> Why do I get a lot apache or rrdtool zombies in my process list?</a>
Please see the [Poller
Support](http://docs.librenms.org/Support/Poller Support/) document
for further details.
If this is related to your web service for LibreNMS then this has been tracked down to an issue within php which the developers aren't fixing. We have implemented a work around which means you
shouldn't be seeing this. If you are, please report this in [issue 443](https://github.com/librenms/librenms/issues/443).
## <a name="faq14"> Why do I get a lot apache or rrdtool zombies in my process list?</a>
#### <a name="faq15"> Why do I see traffic spikes in my graphs?</a>
If this is related to your web service for LibreNMS then this has been
tracked down to an issue within php which the developers aren't
fixing. We have implemented a work around which means you shouldn't be
seeing this. If you are, please report this in [issue
443](https://github.com/librenms/librenms/issues/443).
This occurs either when a counter resets or the device sends back bogus data making it look like a counter reset. We have enabled support for setting a maximum value for rrd files for ports.
## <a name="faq15"> Why do I see traffic spikes in my graphs?</a>
This occurs either when a counter resets or the device sends back
bogus data making it look like a counter reset. We have enabled
support for setting a maximum value for rrd files for ports.
Before this all rrd files were set to 100G max values, now you can enable support to limit this to the actual port speed.
Before this all rrd files were set to 100G max values, now you can
enable support to limit this to the actual port speed.
rrdtool tune will change the max value when the interface speed is
detected as being changed (min value will be set for anything 10M or
over) or when you run the included script (./scripts/tune_port.php) -
see [RRDTune doc](../Extensions/RRDTune.md)
rrdtool tune will change the max value when the interface speed is detected as being changed (min value will be set for anything 10M or over) or when you run the included script (./scripts/tune_port.php) - see [RRDTune doc](../Extensions/RRDTune.md)
SNMP ifInOctets and ifOutOctets are counters, which means they start
at 0 (at device boot) and count up from there. LibreNMS records the
value every 5 minutes and uses the difference between the previous
value and the current value to calculate rate. (Also, this value
resets to 0 when it hits the max value)
SNMP ifInOctets and ifOutOctets are counters, which means they start at 0 (at device boot) and count up from there. LibreNMS records the value every 5 minutes and uses the difference between the previous value and the current value to calculate rate. (Also, this value resets to 0 when it hits the max value)
Now, when the value is not recorded for awhile RRD (our time series storage) does not record a 0, it records the last value, otherwise, there would be even worse problems. Then finally we get the current ifIn/OutOctets value and record that. Now, it appears as though all of the traffic since it stopped getting values have occurred in the last 5 minute interval.
Now, when the value is not recorded for awhile RRD (our time series
storage) does not record a 0, it records the last value, otherwise,
there would be even worse problems. Then finally we get the current
ifIn/OutOctets value and record that. Now, it appears as though all of
the traffic since it stopped getting values have occurred in the last
5 minute interval.
So whenever you see spikes like this, it means we have not received data from the device for several polling intervals. The cause can vary quite a bit: bad snmp implementations, intermittant network connectivity, broken poller, and more.
#### <a name="faq17"> Why do I see gaps in my graphs?</a>
## <a name="faq17"> Why do I see gaps in my graphs?</a>
This is most commonly due to the poller not being able to complete it's run within 300 seconds. Check which devices are causing this by going to /poll-log/ within the Web interface.
This is most commonly due to the poller not being able to complete
it's run within 300 seconds. Check which devices are causing this by
going to /poll-log/ within the Web interface.
When you find the device(s) which are taking the longest you can then look at the Polling module graph under Graphs -> Poller -> Poller Modules Performance. Take a look at what modules are taking the longest and disabled un used modules.
When you find the device(s) which are taking the longest you can then
look at the Polling module graph under Graphs -> Poller -> Poller
Modules Performance. Take a look at what modules are taking the
longest and disabled un used modules.
If you poll a large number of devices / ports then it's recommended to run a local recurisve dns server such as pdns-recursor.
If you poll a large number of devices / ports then it's recommended to
run a local recurisve dns server such as pdns-recursor.
Running RRDCached is also highly advised in larger installs but has benefits no matter the size.
Running RRDCached is also highly advised in larger installs but has
benefits no matter the size.
## <a name="faq16"> How do I change the IP / hostname of a device?</a>
There is a host rename tool called renamehost.php in your librenms
root directory. When renaming you are also changing the device's IP /
hostname address for monitoring.
#### <a name="faq16"> How do I change the IP / hostname of a device?</a>
There is a host rename tool called renamehost.php in your librenms root directory. When renaming you are also changing the device's IP / hostname address for monitoring.
Usage:
```bash
./renamehost.php <old hostname> <new hostname>
```
You can also rename a device in the Web UI by going to the device, then clicking settings Icon -> Edit.
#### <a name="faq19"> My device doesn't finish polling within 300 seconds</a>
You can also rename a device in the Web UI by going to the device,
then clicking settings Icon -> Edit.
## <a name="faq19"> My device doesn't finish polling within 300 seconds</a>
We have a few things you can try:
- Disable unnecessary polling modules under edit device.
- Set a max repeater value within the snmp settings for a device.
What to set this to is tricky, you really should run an snmpbulkwalk with -Cr10 through -Cr50 to see what works best. 50 is usually a good choice if the device can cope.
- Disable unnecessary polling modules under edit device.
- Set a max repeater value within the snmp settings for a device. What
to set this to is tricky, you really should run an snmpbulkwalk with
-Cr10 through -Cr50 to see what works best. 50 is usually a good
choice if the device can cope.
#### <a name="faq18"> Things aren't working correctly?</a>
## <a name="faq18"> Things aren't working correctly?</a>
Run `./validate.php` as root from within your install.
Re-run `./validate.php` once you've resolved any issues raised.
You have an odd issue - we'd suggest you join our [discord server](https://t.libren.ms/discord) to discuss.
You have an odd issue - we'd suggest you join our [discord
server](https://t.libren.ms/discord) to discuss.
#### <a name="faq21"> What do the values mean in my graphs?</a>
## <a name="faq21"> What do the values mean in my graphs?</a>
The values you see are reported as metric values. Thanks to a post on [Reddit](https://www.reddit.com/r/networking/comments/4xzpfj/rrd_graph_interface_error_label_what_is_the_m/)
The values you see are reported as metric values. Thanks to a post on
[Reddit](https://www.reddit.com/r/networking/comments/4xzpfj/rrd_graph_interface_error_label_what_is_the_m/)
here are those values:
```
@ -189,14 +256,17 @@ here are those values:
10^15 P - peta
```
#### <a name="faq22"> Why does a device show as a warning?</a>
## <a name="faq22"> Why does a device show as a warning?</a>
This is indicating that the device has rebooted within the last 24 hours (by default). If you want to adjust this
threshold then you can do so by setting `$config['uptime_warning'] = '84600';` in `config.php`. The value must be in seconds.
This is indicating that the device has rebooted within the last 24
hours (by default). If you want to adjust this threshold then you can
do so by setting `$config['uptime_warning'] = '84600';` in
`config.php`. The value must be in seconds.
#### <a name="faq23"> Why do I not see all interfaces in the Overall traffic graph for a device?</a>
## <a name="faq23"> Why do I not see all interfaces in the Overall traffic graph for a device?</a>
By default numerous interface types and interface descriptions are excluded from this graph. The excluded defailts are:
By default numerous interface types and interface descriptions are
excluded from this graph. The excluded defailts are:
```php
$config['device_traffic_iftype'][] = '/loopback/';
@ -215,7 +285,8 @@ $config['device_traffic_descr'][] = '/null/';
$config['device_traffic_descr'][] = '/dummy/';
```
If you would like to re-include l2vlan interfaces for instance, you first need to `unset` the config array and set your options:
If you would like to re-include l2vlan interfaces for instance, you
first need to `unset` the config array and set your options:
```php
unset($config['device_traffic_iftype']);
@ -226,33 +297,49 @@ $config['device_traffic_iftype'][] = '/mpls/';
$config['device_traffic_iftype'][] = '/ieee8023adLag/';
$config['device_traffic_iftype'][] = '/ppp/';
```
#### <a name="faq24"> How do I move my LibreNMS install to another server?</a>
If you are moving from one CPU architecture to another then you will need to dump the rrd files and re-create them. If you are in
this scenario then you can use [Dan Brown's migration scripts](https://vlan50.com/2015/04/17/migrating-from-observium-to-librenms/).
If you are just moving to another server with the same CPU architecture then the following steps should be all that's needed:
* Install LibreNMS as per our normal documentation; you don't need to run through the web installer or building the sql schema.
* Stop cron by commenting out all lines in `/etc/cron.d/librenms`
* Dump the MySQL database `librenms` from your old server (`mysqldump librenms -u root -p > librenms.sql`)...
* and import it into your new server (`mysql -u root -p < librenms.sql`).
* Copy the `rrd/` folder to the new server.
* Copy the `config.php` file to the new server.
* Ensure ownership of the copied files and folders (substitute your user if necessary) - `chown -R librenms:librenms rrd/; chown librenms:librenms config.php`
* Re-enable cron by uncommenting all lines in `/etc/cron.d/librenms`
## <a name="faq24"> How do I move my LibreNMS install to another server?</a>
#### <a name="faq25"> Why is my EdgeRouter device not detected?</a>
If you are moving from one CPU architecture to another then you will
need to dump the rrd files and re-create them. If you are in this
scenario then you can use [Dan Brown's migration
scripts](https://vlan50.com/2015/04/17/migrating-from-observium-to-librenms/).
If you have `service snmp description` set in your config then this will be why, please remove this. For some reason Ubnt have decided setting this
value should override the sysDescr value returned which breaks our detection.
If you don't have that set then this may be then due to an update of EdgeOS or a new device type, please [create an issue](https://github.com/librenms/librenms/issues/new).
If you are just moving to another server with the same CPU
architecture then the following steps should be all that's needed:
#### <a name="faq26"> Why are some of my disks not showing?</a>
- Install LibreNMS as per our normal documentation; you don't need to
run through the web installer or building the sql schema.
- Stop cron by commenting out all lines in `/etc/cron.d/librenms`
- Dump the MySQL database `librenms` from your old server (`mysqldump
librenms -u root -p > librenms.sql`)...
- and import it into your new server (`mysql -u root -p < librenms.sql`).
- Copy the `rrd/` folder to the new server.
- Copy the `config.php` file to the new server.
- Ensure ownership of the copied files and folders (substitute your
user if necessary) - `chown -R librenms:librenms rrd/; chown
librenms:librenms config.php`
- Re-enable cron by uncommenting all lines in `/etc/cron.d/librenms`
If you are monitoring a linux server then net-snmp doesn't always expose all disks via hrStorage (HOST-RESOURCES-MIB). We have additional support which will retrieve disks via dskTable (UCD-SNMP-MIB).
To expose these disks you need to add additional config to your snmpd.conf file. For example, to expose `/dev/sda1` which may be mounted as `/storage` you can specify:
## <a name="faq25"> Why is my EdgeRouter device not detected?</a>
If you have `service snmp description` set in your config then this
will be why, please remove this. For some reason Ubnt have decided
setting this value should override the sysDescr value returned which
breaks our detection.
If you don't have that set then this may be then due to an update of
EdgeOS or a new device type, please [create an
issue](https://github.com/librenms/librenms/issues/new).
## <a name="faq26"> Why are some of my disks not showing?</a>
If you are monitoring a linux server then net-snmp doesn't always
expose all disks via hrStorage (HOST-RESOURCES-MIB). We have
additional support which will retrieve disks via dskTable
(UCD-SNMP-MIB). To expose these disks you need to add additional
config to your snmpd.conf file. For example, to expose `/dev/sda1`
which may be mounted as `/storage` you can specify:
`disk /dev/sda1`
@ -263,26 +350,39 @@ Or
Restart snmpd and LibreNMS should populate the additional disk after a fresh discovery.
#### <a name="faq27"> Why are my disks reporting an incorrect size?</a>
There is a known issue for net-snmp, which causes it to report incorrect disk size and disk usage when the size of the disk (or raid) are larger then 16TB, a workaround has been implemented but is not active on Centos 6.8 by default due to the fact that this workaround breaks official SNMP specs, and as such could cause unexpected behaviour in other SNMP tools. You can activate the workaround by adding to /etc/snmp/snmpd.conf :
There is a known issue for net-snmp, which causes it to report
incorrect disk size and disk usage when the size of the disk (or raid)
are larger then 16TB, a workaround has been implemented but is not
active on Centos 6.8 by default due to the fact that this workaround
breaks official SNMP specs, and as such could cause unexpected
behaviour in other SNMP tools. You can activate the workaround by
adding to /etc/snmp/snmpd.conf :
`realStorageUnits 0`
#### <a name="faq28"> What is the Difference between Disable Device and Ignore a Device?</a>
## <a name="faq28"> What is the Difference between Disable Device and Ignore a Device?</a>
- Disable stops polling.
- Ignore disables alerting.
- Disable stops polling.
- Ignore disables alerting.
#### <a name="faq8"> How do I add support for a new OS?</a>
## <a name="faq8"> How do I add support for a new OS?</a>
Please see [Supporting a new OS](../Developing/Support-New-OS.md)
#### <a name="faq20"> What information do you need to add a new OS?</a>
## <a name="faq20"> What information do you need to add a new OS?</a>
Under the device, click the gear and select Capture.
Please [open an issue on GitHub](https://github.com/librenms/librenms/issues/new) and provide the output of Discovery, Poller, and Snmpwalk as separate non-expiring https://p.libren.ms/ links.
Under the device, click the gear and select Capture.
You can also use the command line to obtain the information. Especially, if snmpwalk results in a large amount of data.
Replace the relevant information in these commands such as HOSTNAME and COMMUNITY. Use `snmpwalk` instead of `snmpbulkwalk` for v1 devices.
Please [open an issue on
GitHub](https://github.com/librenms/librenms/issues/new) and provide
the output of Discovery, Poller, and Snmpwalk as separate non-expiring
<https://p.libren.ms/> links.
You can also use the command line to obtain the information.
Especially, if snmpwalk results in a large amount of data. Replace the
relevant information in these commands such as HOSTNAME and
COMMUNITY. Use `snmpwalk` instead of `snmpbulkwalk` for v1 devices.
> These commands will automatically upload the data to LibreNMS servers.
@ -296,40 +396,75 @@ You can use the links provided by these commands within the issue.
If possible please also provide what the OS name should be if it doesn't exist already.
#### <a name="faq9"> What can I do to help?</a>
## <a name="faq9"> What can I do to help?</a>
Thanks for asking, sometimes it's not quite so obvious and everyone can contribute something different. So here are some ways you can help LibreNMS improve.
Thanks for asking, sometimes it's not quite so obvious and everyone
can contribute something different. So here are some ways you can help
LibreNMS improve.
- Code. This is a big thing. We want this community to grow by the software developing and evolving to cater for users needs. The biggest area that people can help make this happen is by providing code support. This doesn't necessarily mean contributing code for discovering a new device:
- Web UI, a new look and feel has been adopted but we are not finished by any stretch of the imagination. Make suggestions, find and fix bugs, update the design / layout.
- Poller / Discovery code. Improving it (we think a lot can be done to speed things up), adding new device support and updating old ones.
- The LibreNMS main website, this is hosted on GitHub like the main repo and we accept use contributions here as well :)
- Hardware. We don't physically need it but if we are to add device support, it's made a whole lot easier with access to the kit via SNMP.
- If you've got MIBs, they are handy as well :)
- If you know the vendor and can get permission to use logos that's also great.
- Bugs. Found one? We want to know about it. Most bugs are fixed after being spotted and reported by someone, I'd love to say we are amazing developers and will fix all bugs before you spot them but that's just not true.
- Feature requests. Can't code / won't code. No worries, chuck a feature request into our [community forum](https://community.librenms.org) 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.
- Documentation. Documentation can always be improved and every little bit helps. Not all features are currently documented or documented well, there's speeling mistakes etc. It's very easy to submit updates [through the GitHub website](https://help.github.com/articles/editing-files-in-another-user-s-repository/), no git experience needed.
- 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.
- Code. This is a big thing. We want this community to grow by the
software developing and evolving to cater for users needs. The
biggest area that people can help make this happen is by providing
code support. This doesn't necessarily mean contributing code for
discovering a new device:
- Web UI, a new look and feel has been adopted but we are not
finished by any stretch of the imagination. Make suggestions,
find and fix bugs, update the design / layout.
- Poller / Discovery code. Improving it (we think a lot can be done
to speed things up), adding new device support and updating old
ones.
- The LibreNMS main website, this is hosted on GitHub like the main
repo and we accept use contributions here as well :)
- Hardware. We don't physically need it but if we are to add device
support, it's made a whole lot easier with access to the kit via
SNMP.
- If you've got MIBs, they are handy as well :)
- If you know the vendor and can get permission to use logos that's also great.
- Bugs. Found one? We want to know about it. Most bugs are fixed after
being spotted and reported by someone, I'd love to say we are
amazing developers and will fix all bugs before you spot them but
that's just not true.
- Feature requests. Can't code / won't code. No worries, chuck a
feature request into our [community
forum](https://community.librenms.org) 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.
- Documentation. Documentation can always be improved and every little
bit helps. Not all features are currently documented or documented
well, there's speeling mistakes etc. It's very easy to submit
updates [through the GitHub
website](https://help.github.com/articles/editing-files-in-another-user-s-repository/),
no git experience needed.
- 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>
## <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.
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:
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/f0o/librenms.git
@ -343,36 +478,54 @@ Once you are done testing, you can easily switch back to the master branch:
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:
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
```
### <a name="faq29"> Why can't Normal and Global View users see Oxidized?</a>
Configs can often contain sensitive data. Because of that only global admins can see configs.
### <a name="faq30"> What is the Demo User for?</a>
Demo users allow full access except adding/editing users and deleting devices and can't change passwords.
## <a name="faq29"> Why can't Normal and Global View users see Oxidized?</a>
### <a name="faq31"> Why does modifying 'Default Alert Template' fail?</a>
This template's entry could be missing in the database. Please run this from the LibreNMS directory:
Configs can often contain sensitive data. Because of that only global
admins can see configs.
## <a name="faq30"> What is the Demo User for?</a>
Demo users allow full access except adding/editing users and deleting
devices and can't change passwords.
## <a name="faq31"> Why does modifying 'Default Alert Template' fail?</a>
This template's entry could be missing in the database. Please run
this from the LibreNMS directory:
```bash
php artisan db:seed --class=DefaultAlertTemplateSeeder
```
### <a name="faq32"> Why would alert un-mute itself?</a>
If alert un-mutes itself then it most likely means that the alert cleared and is then triggered again.
Please review eventlog as it will tell you in there.
### <a name="faq33"> How do I change the Device Type?</a>
You can change the Device Type by going to the device you would like to change, then click on the Gear Icon -> Edit.
If you would like to define custom types, we suggest using [Device Groups](/Extensions/Device-Groups/). They will be listed in the menu similarly to device types.
## <a name="faq32"> Why would alert un-mute itself?</a>
### <a name="faq-where-do-i-update-my-database-credentials">Where do I update my database credentials?</a>
If you've changed your database credentials then you will need to update LibreNMS with those new details.
If alert un-mutes itself then it most likely means that the alert
cleared and is then triggered again. Please review eventlog as it will
tell you in there.
## <a name="faq33"> How do I change the Device Type?</a>
You can change the Device Type by going to the device you would like
to change, then click on the Gear Icon -> Edit. If you would like to
define custom types, we suggest using [Device
Groups](/Extensions/Device-Groups/). They will be listed in the
menu similarly to device types.
## <a name="faq-where-do-i-update-my-database-credentials">Where do I update my database credentials?</a>
If you've changed your database credentials then you will need to
update LibreNMS with those new details.
Please edit both `config.php` and `.env`
config.php:
```php
$config['db_host'] = '';
$config['db_user'] = '';
@ -381,6 +534,7 @@ $config['db_name'] = '';
```
[.env](../Support/Environment-Variables.md#database):
```bash
DB_HOST=
DB_DATABASE=
@ -389,7 +543,7 @@ DB_PASSWORD=
DB_PORT=
```
### <a name='my-reverse-proxy-is-not-working'>My reverse proxy is not working</a>
## <a name='my-reverse-proxy-is-not-working'>My reverse proxy is not working</a>
Make sure your proxy is passing the proper variables.
At a minimum: X-Forwarded-For and X-Forwarded-Proto (X-Forwarded-Port if needed)
@ -399,11 +553,21 @@ You also need to [Set the proxy or proxies as trusted](../Support/Environment-Va
If you are using a subdirectory on the reverse proxy and not on the actual web server,
you may need to set [APP_URL](../Support/Environment-Variables.md#base-url) and `$config['base_url']`.
### <a name='my-alerts-aren't-being-delivered-on-time'>My alerts aren't being delivered on time</a>
If you're running MySQL/MariaDB on a separate machine or container make sure the timezone is set properly on both the LibreNMS **and** MySQL/MariaDB instance. Alerts will be delivered according to MySQL/MariaDB's time, so a mismatch between the two can cause alerts to be delivered late if LibreNMS is on a timezone later than MySQL/MariaDB.
## <a name='my-alerts-aren't-being-delivered-on-time'>My alerts aren't being delivered on time</a>
### <a name='my-alert-templates-stopped-working'>My alert templates stopped working</a>
You should probably have a look in the documentation concerning the new template syntax: https://docs.librenms.org/Alerting/Templates/.
Since version 1.42, syntax changed, and you basically need to convert your templates to this new syntax (including the titles).
If you're running MySQL/MariaDB on a separate machine or container
make sure the timezone is set properly on both the LibreNMS **and**
MySQL/MariaDB instance. Alerts will be delivered according to
MySQL/MariaDB's time, so a mismatch between the two can cause alerts
to be delivered late if LibreNMS is on a timezone later than
MySQL/MariaDB.
## <a name='my-alert-templates-stopped-working'>My alert templates stopped working</a>
You should probably have a look in the documentation concerning the
new template syntax:
<https://docs.librenms.org/Alerting/Templates/>. Since version 1.42,
syntax changed, and you basically need to convert your templates to
this new syntax (including the titles).

6
doc/Support/Features.md
View File

@ -1,6 +1,7 @@
source: Support/Features.md
path: blob/master/doc/
### Features
# Features
Here's a brief list of supported features, some might be missing.
If you think something is missing, feel free to ask us.
@ -22,7 +23,8 @@ If you think something is missing, feel free to ask us.
* API
* Auto Updating
### Vendors
# Vendors
Here's a brief list of supported vendors, some might be missing.
If you are unsure of whether your device is supported or not, feel free to ask us.

53
doc/Support/Install Validation.md
View File

@ -3,29 +3,37 @@ path: blob/master/doc/
# Install validation
With a lot of configuration possibilities, manually editing config.php means it's not
uncommon that mistakes get made. It's also impossible to validate user input in config.php when you're just using a text editor :)
With a lot of configuration possibilities, manually editing config.php
means it's not uncommon that mistakes get made. It's also impossible
to validate user input in config.php when you're just using a text
editor :)
So, to try and help with some of the general issues people come across we've put together a simple validation tool which at present will:
So, to try and help with some of the general issues people come across
we've put together a simple validation tool which at present will:
- Validate config.php from a php perspective including whitespace where it shouldn't be.
- Connection to your MySQL server to verify credentials.
- Checks if you are running the older alerting system.
- Checks your rrd directory setup if not running rrdcached.
- Checks disk space for where /opt/librenms is installed.
- Checks location to fping
- Tests MySQL strict mode being enabled
- Tests for files not owned by librenms user (if configured)
- Validate config.php from a php perspective including whitespace
where it shouldn't be.
- Connection to your MySQL server to verify credentials.
- Checks if you are running the older alerting system.
- Checks your rrd directory setup if not running rrdcached.
- Checks disk space for where /opt/librenms is installed.
- Checks location to fping
- Tests MySQL strict mode being enabled
- Tests for files not owned by librenms user (if configured)
Optionally you can also pass -m and a module name for that to be tested. Current modules are:
Optionally you can also pass -m and a module name for that to be
tested. Current modules are:
- mail - This will validate your mail transport configuration.
- dist-poller - This will test your distributed poller configuration.
- rrdcheck - This will test your rrd files to see if they are unreadable or corrupted (source of broken graphs).
- mail - This will validate your mail transport configuration.
- dist-poller - This will test your distributed poller configuration.
- rrdcheck - This will test your rrd files to see if they are
unreadable or corrupted (source of broken graphs).
You can run validate.php as `root` by executing `./validate.php` within your install directory.
You can run validate.php as `root` by executing `./validate.php`
within your install directory.
The output will provide you either a clean bill of health or a list of things you need to fix:
The output will provide you either a clean bill of health or a list of
things you need to fix:
**OK** - This is a good thing, you can skip over these :)
@ -33,10 +41,13 @@ The output will provide you either a clean bill of health or a list of things yo
**FAIL** - This is going to need your attention!
### Validate from the WebUI
You can validate your LibreNMS install from the WebUI, using the nav bar and clicking on the little Gear Icon -> Validate Config.
![Validate Config Icon](/img/validate-config-icon.png)
Then You should see the results of validate.
# Validate from the WebUI
You can validate your LibreNMS install from the WebUI, using the nav
bar and clicking on the little Gear Icon -> Validate
Config. ![Validate Config Icon](/img/validate-config-icon.png) Then
You should see the results of validate.
Below is just example of the results.
![Validate results](/img/validate-results.png)

144
doc/Support/Performance.md
View File

@ -1,72 +1,90 @@
source: Support/Performance.md
path: blob/master/doc/
# Performance optimisations
This document will give you some guidance on optimising your setup.
The suggestions are in a rough order of how much impact they will have.
### RRDCached
## RRDCached
**We absolutely recommend running this, it will save on IO load**. [RRDCached](http://docs.librenms.org/Extensions/RRDCached/)
## MySQL Optimisation
### MySQL Optimisation
It's advisable after 24 hours of running MySQL that you run [MySQL Tuner](https://raw.githubusercontent.com/major/MySQLTuner-perl/master/mysqltuner.pl)
It's advisable after 24 hours of running MySQL that you run [MySQL
Tuner](https://raw.githubusercontent.com/major/MySQLTuner-perl/master/mysqltuner.pl)
which will make suggestions on things you can change specific to your setup.
One recommendation we can make is that you set the following in my.cnf under a [mysqld] group:
One recommendation we can make is that you set the following in my.cnf
under a [mysqld] group:
```bash
innodb_flush_log_at_trx_commit = 0
```
You can also set this to 2. This will have the possibility that you could lose up to 1 second on mysql data in the event
MySQL crashes or your server does but it provides an amazing difference in IO use.
You can also set this to 2. This will have the possibility that you
could lose up to 1 second on mysql data in the event MySQL crashes or
your server does but it provides an amazing difference in IO use.
## Polling modules
### Polling modules
Review the graph of poller module time take under gear > pollers >
performance to see what modules are consuming poller time. This data
is shown per device under device > graphs > poller.
Review the graph of poller module time take under gear > pollers > performance to see what modules are consuming poller time.
This data is shown per device under device > graphs > poller.
Disable polling (and discovery) modules that you do not need. You can do this globally in `config.php` like:
Disable polling (and discovery) modules that you do not need. You can
do this globally in `config.php` like:
Disable OSPF polling
```php
$config['poller_modules']['ospf'] = false;
```
You can disable modules globally then re-enable the module per device or the opposite way. For a list of modules please see
[Poller modules](http://docs.librenms.org/Support/Poller%20Support/)
You can disable modules globally then re-enable the module per device
or the opposite way. For a list of modules please see [Poller
modules](http://docs.librenms.org/Support/Poller%20Support/)
### SNMP Max Repeaters
## SNMP Max Repeaters
We have support for SNMP Max repeaters which can be handy on devices where we poll a lot of ports or bgp sessions for instance and
where snmpwalk or snmpbulkwalk is used. This needs to be enabled on a per device basis under edit device -> snmp -> Max repeaters.
We have support for SNMP Max repeaters which can be handy on devices
where we poll a lot of ports or bgp sessions for instance and
where snmpwalk or snmpbulkwalk is used. This needs to be enabled on a
per device basis under edit device -> snmp -> Max repeaters.
You can also set this globally with the config option `$config['snmp']['max_repeaters'] = X;`.
You can also set this globally with the config option
`$config['snmp']['max_repeaters'] = X;`.
It's advisable to test the time taken to snmpwalk IF-MIB or something similar to work out what the best value is. To do this run the following
but replace <REPEATERS> with varying numbers from 10 upto around 50. You will also need to set the correct snmp version, hostname and community string:
It's advisable to test the time taken to snmpwalk IF-MIB or something
similar to work out what the best value is. To do this run the
following but replace -REPEATERS- with varying numbers from 10 upto
around 50. You will also need to set the correct snmp version,
hostname and community string:
`time snmpbulkwalk -v2c -cpublic HOSTNAME -Cr<REPEATERS> -M /opt/librenms/mibs -m IF-MIB IfEntry`
`time snmpbulkwalk -v2c -cpublic HOSTNAME -Cr-REPEATERS- -M
/opt/librenms/mibs -m IF-MIB IfEntry`
> NOTE: Do not go blindly setting this value as you can impact polling negatively.
> NOTE: Do not go blindly setting this value as you can impact polling
> negatively.
### SNMP Max OIDs
## SNMP Max OIDs
For sensors polling we now do bulk snmp gets to speed things up. By default this is ten but you can overwrite this per device under
edit device -> snmp -> Max OIDs.
For sensors polling we now do bulk snmp gets to speed things up. By
default this is ten but you can overwrite this per device under edit
device -> snmp -> Max OIDs.
You can also set this globally with the config option `$config['snmp']['max_oid'] = X;`.
You can also set this globally with the config option
`$config['snmp']['max_oid'] = X;`.
> NOTE: It is advisable to monitor sensor polling when you change this to ensure you don't set the value too high.
> NOTE: It is advisable to monitor sensor polling when you change this
> to ensure you don't set the value too high.
### fping tuning
## fping tuning
You can change some of the default fping options used globally or per device. The defaults are:
You can change some of the default fping options used globally or per
device. The defaults are:
```php
$config['fping_options']['timeout'] = 500;
@ -74,8 +92,10 @@ $config['fping_options']['count'] = 3;
$config['fping_options']['interval'] = 500;
```
If your devices are slow to respond then you will need to increase the timeout value and potentially the interval value.
However if your network is stable, you can increase poller performance by dropping the count value to 1 and/or the timeout+millsec value to 200 or 300:
If your devices are slow to respond then you will need to increase the
timeout value and potentially the interval value. However if your
network is stable, you can increase poller performance by dropping the
count value to 1 and/or the timeout+millsec value to 200 or 300:
```php
$config['fping_options']['timeout'] = 300;
@ -83,47 +103,67 @@ $config['fping_options']['count'] = 1;
$config['fping_options']['interval'] = 300;
```
This will mean that we no longer delay each icmp packet sent (we send 3 in total by default) by 0.5 seconds. With only 1 icmp packet
being sent then we will receive a response quicker. The defaults mean it will take at least 1 second for a response no matter how
This will mean that we no longer delay each icmp packet sent (we send
3 in total by default) by 0.5 seconds. With only 1 icmp packet
being sent then we will receive a response quicker. The defaults mean
it will take at least 1 second for a response no matter how
quick the icmp packet is returned.
### Optimise poller-wrapper
## Optimise poller-wrapper
The default 16 threads that `poller-wrapper.py` runs as isn't necessarily the optimal number. A general rule of thumb is
2 threads per core but we suggest that you play around with lowering / increasing the number until you get the optimal value.
**Note** KEEP in MIND that this doesn't always help, it depends on your system and CPU. So be careful.
This can be changed by going to the cron job for librenms. Usually in `/etc/cron.d/librenms` and changing the "16"
The default 16 threads that `poller-wrapper.py` runs as isn't
necessarily the optimal number. A general rule of thumb is 2 threads
per core but we suggest that you play around with lowering /
increasing the number until you get the optimal value. **Note** KEEP
in MIND that this doesn't always help, it depends on your system and
CPU. So be careful. This can be changed by going to the cron job for
librenms. Usually in `/etc/cron.d/librenms` and changing the "16"
```
*/5 * * * * librenms /opt/librenms/cronic /opt/librenms/poller-wrapper.py 16
```
### Recursive DNS
## Recursive DNS
If your install uses hostnames for devices and you have quite a lot then it's advisable to setup a local recursive dns instance on the
LibreNMS server. Something like pdns-recursor can be used and then configure `/etc/resolv.conf` to use 127.0.0.1 for queries.
If your install uses hostnames for devices and you have quite a lot
then it's advisable to setup a local recursive dns instance on the
LibreNMS server. Something like pdns-recursor can be used and then
configure `/etc/resolv.conf` to use 127.0.0.1 for queries.
### Per port polling - experimental
## Per port polling - experimental
By default the polling ports module will walk ifXEntry + some items from ifEntry regardless of the port. So if a port is marked as deleted because you don't want to see them
or it's disabled then we still collect data. For the most part this is fine as the walks are quite quick. However for devices with a lot of ports and good % of those are
either deleted or disabled then this approach isn't optimal. So to counter this you can enable 'selected port polling' per device within the edit device -> misc section or by
globally enabling it (**not recommended**): `$config['polling']['selected_ports'] = true;`. You can also set it for a specific OS: `$config['os']['ios']['polling']['selected_ports'] = true;`.
By default the polling ports module will walk ifXEntry + some items
from ifEntry regardless of the port. So if a port is marked as deleted
because you don't want to see them or it's disabled then we still
collect data. For the most part this is fine as the walks are quite
quick. However for devices with a lot of ports and good % of those are
either deleted or disabled then this approach isn't optimal. So to
counter this you can enable 'selected port polling' per device within
the edit device -> misc section or by globally enabling it (**not
recommended**): `$config['polling']['selected_ports'] = true;`. You
can also set it for a specific OS:
`$config['os']['ios']['polling']['selected_ports'] = true;`.
Running `./scripts/collect-port-polling.php` will poll your devices with both full and selective polling, display a table with the difference and optionally enable or disable selected ports polling for devices which would benefit from a change.
Note that it doesn't continously re-evaluate this, it will only be updated when the script is run. There are a number of options:
Running `./scripts/collect-port-polling.php` will poll your devices
with both full and selective polling, display a table with the
difference and optionally enable or disable selected ports polling for
devices which would benefit from a change. Note that it doesn't
continously re-evaluate this, it will only be updated when the script
is run. There are a number of options:
```
-h <device id> | <device hostname wildcard> Poll single device or wildcard hostname
-e <percentage> Enable/disable selected ports polling for devices which would benefit <percentage> from a change
```
### Web interface
## Web interface
#### HTTP/2
### HTTP/2
If you are running https then you should enable http/2 support in whatever web server you use:
If you are running https then you should enable http/2 support in
whatever web server you use:
For Nginx (1.9.5 and above) change `listen 443 ssl;` to `listen 443 ssl http2;` in the Virtualhost config.
For Nginx (1.9.5 and above) change `listen 443 ssl;` to `listen 443
ssl http2;` in the Virtualhost config.
For Apache (2.4.17 an above) set `Protocols h2 http/1.1` in the Virtualhost config.

68
doc/Support/Poller Support.md
View File

@ -1,10 +1,13 @@
source: Support/Poller Support.md
path: blob/master/doc/
### poller.php
This document will explain how to use poller.php to debug issues or manually running to process data.
# poller.php
This document will explain how to use poller.php to debug issues or
manually running to process data.
## Command options
#### Command options
```bash
LibreNMS 2014.master Poller
@ -24,29 +27,39 @@ Debugging and testing options:
-m Specify module(s) to be run. Comma separate modules, submodules may be added with /
```
`-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.
`-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 but with most sensitive data masked) so that you can see what is happening during a poller run. This includes things like rrd updates, SQL queries and response from snmp.
`-d` Enables debugging output (verbose output but with most sensitive
data masked) so that you can see what is happening during a poller
run. This includes things like rrd updates, SQL queries and response
from snmp.
`-v` Enables verbose debugging output with all data in tact.
`-m` This enables you to specify the module you want to run for poller.
#### Poller Wrapper
# Poller Wrapper
We have a `poller-wrapper.py` script by [Job Snijders](https://github.com/job). This script is currently the default.
We have a `poller-wrapper.py` script by [Job
Snijders](https://github.com/job). This script is currently the
default.
If you need to debug the output of poller-wrapper.py then you can add `-d` to the end of the command - it is NOT recommended to do this in cron.
If you need to debug the output of poller-wrapper.py then you can add
`-d` to the end of the command - it is NOT recommended to do this in
cron.
#### Poller config
# 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 Device -> Edit -> Modules.
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 Device
-> Edit -> Modules.
```php
$config['poller_modules']['unix-agent'] = false;
@ -94,12 +107,14 @@ $config['poller_modules']['loadbalancers'] = false;
$config['poller_modules']['mef'] = false;
```
#### OS based Poller config
## OS based Poller config
You can enable or disable modules for a specific OS by add corresponding line in `config.php`
OS based settings have preference over global. Device based settings have preference over all others
You can enable or disable modules for a specific OS by add
corresponding line in `config.php` OS based settings have preference
over global. Device based settings have preference over all others
Poller performance improvement can be achieved by deactivating all modules that are not supported by specific OS.
Poller performance improvement can be achieved by deactivating all
modules that are not supported by specific OS.
E.g. to deactivate spanning tree but activate unix-agent module for linux OS
@ -108,7 +123,7 @@ $config['os']['linux']['poller_modules']['stp'] = false;
$config['os']['linux']['poller_modules']['unix-agent'] = true;
```
#### Poller modules
## Poller modules
`unix-agent`: Enable the check_mk agent for external support for applications.
@ -134,7 +149,8 @@ $config['os']['linux']['poller_modules']['unix-agent'] = true;
`ipSystemStats`: IP statistics for device.
`ports`: This module will detect all ports on a device excluding ones configured to be ignored by config options.
`ports`: This module will detect all ports on a device excluding ones
configured to be ignored by config options.
`nac`: Network Access Control (NAC) or 802.1X support.
@ -178,36 +194,44 @@ $config['os']['linux']['poller_modules']['unix-agent'] = true;
`mib`: Support for generic MIB parsing.
#### Running
# 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
# Debugging
To provide debugging output you will need to run the poller process with the `-d` flag. You can do this either against
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
```
Using `-d` shouldn't output much sensitive information, `-v` will so 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.
Using `-d` shouldn't output much sensitive information, `-v` will so
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:

127
doc/Support/Remote-Monitoring-VPN.md
View File

@ -1,25 +1,40 @@
source: Support/Remote-Monitoring-VPN.md
path: blob/master/doc/
# Remote monitoring using tinc VPN
This article describes how to use tinc to connect several remote sites and their subnets to your central monitoring server. This will let you connect to devices on remote private IP ranges through one gateway on each site, routing them securely back to your LibreNMS installation.
This article describes how to use tinc to connect several remote sites
and their subnets to your central monitoring server. This will let you
connect to devices on remote private IP ranges through one gateway on
each site, routing them securely back to your LibreNMS installation.
## Configuring the monitoring server
tinc should be available on nearly all Linux distributions via package management. If you are running something different, just take a look at tinc's homepage to find an appropriate version for your operating system: https://www.tinc-vpn.org/download/
I am going to describe the setup for Debian-based systems, but there are virtually no differences for e.g. CentOS or similar.
tinc should be available on nearly all Linux distributions via package
management. If you are running something different, just take a look
at tinc's homepage to find an appropriate version for your operating
system: <https://www.tinc-vpn.org/download/>
I am going to describe the setup for Debian-based systems, but there
are virtually no differences for e.g. CentOS or similar.
- First make sure your firewall accepts connections on port 655 UDP
and TCP.
- Then install tinc via `apt-get install tinc`.
- Create the following directory structure to hold all your
configuration files: `mkdir -p /etc/tinc/myvpn/hosts` "myvpn" is
your VPN network's name and can be chosen freely.
- Create your main configuration file: `vim /etc/tinc/myvpn/tinc.conf`
* First make sure your firewall accepts connections on port 655 UDP and TCP.
* Then install tinc via `apt-get install tinc`.
* Create the following directory structure to hold all your configuration files: `mkdir -p /etc/tinc/myvpn/hosts` "myvpn" is your VPN network's name and can be chosen freely.
* Create your main configuration file: `vim /etc/tinc/myvpn/tinc.conf`
```bash
Name = monitoring
AddressFamily = ipv4
Device = /dev/net/tun
```
* Next we need network up- and down scripts to define a few network settings for inside our VPN: `vim /etc/tinc/myvpn/tinc-up`
- Next we need network up- and down scripts to define a few network
settings for inside our VPN: `vim /etc/tinc/myvpn/tinc-up`
```bash
#!/bin/sh
ifconfig $INTERFACE 10.6.1.1 netmask 255.255.255.0
@ -29,34 +44,59 @@ ip route add 10.100.0.0/22 dev $INTERFACE
ip route add 10.200.0.0/22 dev $INTERFACE
```
In this example we have 10.6.1.1 as the VPN IP address for the monitoring server on a /24 subnet. $INTERFACE will be automatically substituted with the name of the VPN, "myvpn" in this case. Then we have a route for the VPN subnet, so we can reach other sites via their VPN address. The last 3 lines designate the remote subnets. In the example I want to reach devices on three different remote private /22 subnets and be able to monitor devices on them from this server, so I set up routes for each of those remote sites in my tinc-up script.
- In this example we have 10.6.1.1 as the VPN IP address for the
monitoring server on a /24 subnet. $INTERFACE will be automatically
substituted with the name of the VPN, "myvpn" in this case. Then we
have a route for the VPN subnet, so we can reach other sites via
their VPN address. The last 3 lines designate the remote subnets. In
the example I want to reach devices on three different remote
private /22 subnets and be able to monitor devices on them from this
server, so I set up routes for each of those remote sites in my
tinc-up script.
- The tinc-down script is relatively simple as it just removes the
custom interface, which should get rid of the routes as well: `vim
/etc/tinc/myvpn/tinc-down`
* The tinc-down script is relatively simple as it just removes the custom interface, which should get rid of the routes as well: `vim /etc/tinc/myvpn/tinc-down`
```bash
#!/bin/sh
ifconfig $INTERFACE down
```
* Make sure your scripts scan be executed: `chmod +x /etc/tinc/myvpn/tinc-*`
* As a last step we need a host configuration file. This should be named the same as the "Name" you defined in tinc.conf: `vim /etc/tinc/myvpn/hosts/monitoring`
- Make sure your scripts scan be executed: `chmod +x
/etc/tinc/myvpn/tinc-*`
- As a last step we need a host configuration file. This should be
named the same as the "Name" you defined in tinc.conf: `vim
/etc/tinc/myvpn/hosts/monitoring`
```bash
Subnet = 10.6.1.1/32
```
On the monitoring server we will just fill in the subnet and not define its external IP address to make sure it listens on all available external interfaces.
On the monitoring server we will just fill in the subnet and not
define its external IP address to make sure it listens on all
available external interfaces.
* It's time to use tinc to create our key-pair: `tincd -n myvpn -K`
* Now the file `/etc/tinc/myvpn/hosts/monitoring` should have an RSA public key appended to it and your private key should reside in `/etc/tinc/myvpn/rsa_key.priv`.
* To make sure that the connection will be restored after each reboot, you can add your VPN name to `/etc/tinc/nets.boot`.
* Now you can start tinc with `tincd -n myvpn` and it will listen for your remote sites to connect to it.
- It's time to use tinc to create our key-pair: `tincd -n myvpn -K`
- Now the file `/etc/tinc/myvpn/hosts/monitoring` should have an RSA
public key appended to it and your private key should reside in
`/etc/tinc/myvpn/rsa_key.priv`.
- To make sure that the connection will be restored after each reboot,
you can add your VPN name to `/etc/tinc/nets.boot`.
- Now you can start tinc with `tincd -n myvpn` and it will listen for
your remote sites to connect to it.
## Remote site configuration
Essentially the same steps as for your central monitoring server apply for all remote gateway devices. These can be routers, or just any computer or VM running on the remote subnet, able to reach the internet with the ability to forward IP packets externally.
Essentially the same steps as for your central monitoring server apply
for all remote gateway devices. These can be routers, or just any
computer or VM running on the remote subnet, able to reach the
internet with the ability to forward IP packets externally.
- Install tinc
- Create directory structure: `mkdir -p /etc/tinc/myvpn/hosts`
- Create main configuration: `vim /etc/tinc/myvpn/tinc.conf`
* Install tinc
* Create directory structure: `mkdir -p /etc/tinc/myvpn/hosts`
* Create main configuration: `vim /etc/tinc/myvpn/tinc.conf`
```bash
Name = remote1
AddressFamily = ipv4
@ -64,21 +104,24 @@ Device = /dev/net/tun
ConnectTo = monitoring
```
* Create up script: `vim /etc/tinc/myvpn/tinc-up`
- Create up script: `vim /etc/tinc/myvpn/tinc-up`
```bash
#!/bin/sh
ifconfig $INTERFACE 10.6.1.2 netmask 255.255.255.0
ip route add 10.6.1.2/32 dev $INTERFACE
```
* Create down script: `vim /etc/tinc/myvpn/tinc-down`
- Create down script: `vim /etc/tinc/myvpn/tinc-down`
```bash
#!/bin/sh
ifconfig $INTERFACE down
```
* Make executable: `chmod +x /etc/tinc/myvpn/tinc*`
* Create device configuration: `vim /etc/tinc/myvpn/hosts/remote1`
- Make executable: `chmod +x /etc/tinc/myvpn/tinc*`
- Create device configuration: `vim /etc/tinc/myvpn/hosts/remote1`
```bash
Address = 198.51.100.2
Subnet = 10.0.0.0/22
@ -86,7 +129,10 @@ Subnet = 10.0.0.0/22
This defines the device IP address outside of the VPN and the subnet it will expose.
* Copy over the monitoring server's host configuration (including the embedded public key) and add it's external IP address: `vim /etc/tinc/myvpn/hosts/monitoring`
- Copy over the monitoring server's host configuration (including the
embedded public key) and add it's external IP address: `vim
/etc/tinc/myvpn/hosts/monitoring`
```bash
Address = 203.0.113.6
Subnet = 10.6.1.1/32
@ -95,14 +141,27 @@ Subnet = 10.6.1.1/32
VeDyaqhKd4o2Fz...
```
* Generate this device's keys: `tincd -n myvpn -K`
* Copy over this devices host file including the embedded public key to your monitoring server.
* Add the name for the VPN to`/etc/tinc/nets.boot` if you want to autostart the connection upon reboot.
* Start tinc: `tincd -n myvpn`
- Generate this device's keys: `tincd -n myvpn -K`
- Copy over this devices host file including the embedded public key
to your monitoring server.
- Add the name for the VPN to`/etc/tinc/nets.boot` if you want to
autostart the connection upon reboot.
- Start tinc: `tincd -n myvpn`
These steps can basically be repeated for every remote site just
choosing different names and other internal IP addresses. In my case
I connected 3 remote sites running behind Ubiquiti EdgeRouters. Since
those devices let me install software through Debian's package
management it was very easy to set up. Just create the necessary
configuration files and network scripts on each device and distribute
the host configurations including the public keys to each device that
will actively connect back.
These steps can basically be repeated for every remote site just choosing different names and other internal IP addresses. In my case I connected 3 remote sites running behind Ubiquiti EdgeRouters. Since those devices let me install software through Debian's package management it was very easy to set up. Just create the necessary configuration files and network scripts on each device and distribute the host configurations including the public keys to each device that will actively connect back.
Now you can add all devices you want to monitor in LibreNMS using
their internal IP address on the remote subnets or using some form of
name resolution. I opted to declare the most important devices in my
`/etc/hosts` file on the monitoring server.
Now you can add all devices you want to monitor in LibreNMS using their internal IP address on the remote subnets or using some form of name resolution. I opted to declare the most important devices in my `/etc/hosts` file on the monitoring server.
As an added bonus tinc is a mesh VPN, so in theory you could specify several "ConnectTo" on each device and they should hold connections even if one network path goes down.
As an added bonus tinc is a mesh VPN, so in theory you could specify
several "ConnectTo" on each device and they should hold connections
even if one network path goes down.

228
doc/Support/SNMP-Configuration-Examples.md
View File

@ -4,46 +4,48 @@ path: blob/master/doc/
# SNMP configuration examples
Table of Content:
- [Devices](#devices)
- [Cisco](#cisco)
- [Adaptive Security Appliance (ASA)](#adaptive-security-appliance-asa)
- [IOS / IOS XE](#ios--ios-xe)
- [NX-OS](#nx-os)
- [Wireless LAN Controller (WLC)](#wireless-lan-controller-wlc)
- [HPE 3PAR](#hpe3par)
- [Inform OS 3.2.x](#inform-os-32x)
- [Infoblox](#infoblox)
- [NIOS 7.x+](#nios-7x)
- [Juniper](#juniper)
- [Junos OS](#junos-os)
- [Mikrotik](#mikrotik)
- [RouterOS 6.x](#routeros-6x)
- [Palo Alto](#palo-alto)
- [PANOS 6.x/7.x](#panos-6x7x)
- [VMware](#vmware)
- [ESX/ESXi 5.x/6.x](#esxesxi-5x6x)
- [VCenter 6.x](#vcenter-6x)
- [Cisco](#cisco)
- [Adaptive Security Appliance (ASA)](#adaptive-security-appliance-asa)
- [IOS / IOS XE](#ios--ios-xe)
- [NX-OS](#nx-os)
- [Wireless LAN Controller (WLC)](#wireless-lan-controller-wlc)
- [HPE 3PAR](#hpe3par)
- [Inform OS 3.2.x](#inform-os-32x)
- [Infoblox](#infoblox)
- [NIOS 7.x+](#nios-7x)
- [Juniper](#juniper)
- [Junos OS](#junos-os)
- [Mikrotik](#mikrotik)
- [RouterOS 6.x](#routeros-6x)
- [Palo Alto](#palo-alto)
- [PANOS 6.x/7.x](#panos-6x7x)
- [VMware](#vmware)
- [ESX/ESXi 5.x/6.x](#esxesxi-5x6x)
- [VCenter 6.x](#vcenter-6x)
- [Operating systems](#operating-systems)
- [Linux (snmpd v2)](#linux-snmpd)
- [Linux (snmpd v3)](#linux-snmpd-v3)
- [Windows Server 2008 R2](#windows-server-2008-r2)
- [Windows Server 2012 R2 and 2016](#windows-server-2012-r2-and-2016)
- [Mac OSX](#Mac-OSX)
- [Linux (snmpd v2)](#linux-snmpd)
- [Linux (snmpd v3)](#linux-snmpd-v3)
- [Windows Server 2008 R2](#windows-server-2008-r2)
- [Windows Server 2012 R2 and 2016](#windows-server-2012-r2-and-2016)
- [Mac OSX](#Mac-OSX)
## Devices
### Cisco
#### Adaptive Security Appliance (ASA)
ASDM
1. Launch ASDM and connect to your device
2. Go to Configuration > Management Access > SNMP
3. Add your community string
4. Add in the "SNMP Host Access List" section your LibreNMS server IP address
5. Click Apply and Save
1. Go to Configuration > Management Access > SNMP
1. Add your community string
1. Add in the "SNMP Host Access List" section your LibreNMS server IP address
1. Click Apply and Save
CLI
CLI
```
# SNMPv2c
@ -100,46 +102,59 @@ snmp-server location <YOUR-LOCATION>
```
#### Wireless LAN Controller (WLC)
1. Access the web admin page and log in
2. If you are running version 8.1 and later, on the new dashboard click "Advanced"
3. Go to management Tab
4. On SNMP sub-menu, select "Communities"
5. Click "New..."
6. Add your community name and leave IP addresses empty
7. Click Apply and Save
1. If you are running version 8.1 and later, on the new dashboard click "Advanced"
1. Go to management Tab
1. On SNMP sub-menu, select "Communities"
1. Click "New..."
1. Add your community name and leave IP addresses empty
1. Click Apply and Save
### HPE 3PAR
#### Inform OS 3.2.x
- Access the CLI
- Add an SNMP Manager with your LibreNMS IP address:
```
addsnmpmgr <librenms ip>
```
- Add your SNMP community:
```
setsnmppw <community>
```
### Infoblox
#### NIOS 7.x+
1. Access the web admin page and log in
2. Go to Grid tab > Grid Manager
3. In the right menu select "Grid properties"
4. Select "SNMP" menu
5. Click "Enable SNMPv1/SNMPv2 Queries"
6. Add your community
7. Click Save & Close
1. Go to Grid tab > Grid Manager
1. In the right menu select "Grid properties"
1. Select "SNMP" menu
1. Click "Enable SNMPv1/SNMPv2 Queries"
1. Add your community
1. Click Save & Close
### Juniper
#### Junos OS
for SNMPv1/v2c
```
set snmp description description
set snmp location location
set snmp contact contact
set snmp community YOUR-COMMUNITY authorization read-only
```
for SNMPv3 (authPriv):
```
set snmp v3 usm local-engine user authpriv authentication-sha authentication-password YOUR_AUTH_SECRET
set snmp v3 usm local-engine user authpriv privacy-aes128 privacy-password YOUR_PRIV_SECRET
@ -149,9 +164,10 @@ set snmp v3 vacm access group mysnmpv3 default-context-prefix security-model any
set snmp view mysnmpv3view oid iso include
```
### Mikrotik
#### RouterOS 6.x
```
#Terminal SNMP v2 Configuration
/snmp community
@ -162,17 +178,26 @@ set contact="<NAME>" enabled=yes engine-id=<ENGINE ID> location="<LOCALTION>"
```
### Palo Alto
#### PANOS 6.x/7.x
1. Access the web admin page and log in
2. Go to Device tab > Setup
3. Go to the sub-tab "Operations"
4. Click "SNMP Setup"
5. Enter your SNMP community and then click "OK"
6. Click Apply
1. Go to Device tab > Setup
1. Go to the sub-tab "Operations"
1. Click "SNMP Setup"
1. Enter your SNMP community and then click "OK"
1. Click Apply
Note that you need to allow SNMP on the needed interfaces. To do that you need to create a network "Interface Mgmt" profile for standard interface and allow SNMP under "Device > Management > Management Interface Settings" for out of band management interface.
Note that you need to allow SNMP on the needed interfaces. To do that
you need to create a network "Interface Mgmt" profile for standard
interface and allow SNMP under "Device > Management > Management
Interface Settings" for out of band management interface.
One may also configure SNMP from the command line, which is useful
when you need to configure more than one firewall for SNMP
monitoring. Log into the firewall(s) via ssh, and perform these
commands for basic SNMPv3 configuration:
One may also configure SNMP from the command line, which is useful when you need to configure more than one firewall for SNMP monitoring. Log into the firewall(s) via ssh, and perform these commands for basic SNMPv3 configuration:
```
username@devicename> configure
username@devicename# set deviceconfig system service disable-snmp no
@ -188,24 +213,29 @@ username@devicename# commit
username@devicename# exit
```
### VMware
#### ESX/ESXi 5.x/6.x
Log on to your ESX server by means of ssh. You may have to enable the ssh service in the GUI first.
Log on to your ESX server by means of ssh. You may have to enable the
ssh service in the GUI first.
From the CLI, execute the following commands:
```
esxcli system snmp set --authentication SHA1
esxcli system snmp set --privacy AES128
esxcli system snmp hash --auth-hash YOUR_AUTH_SECRET --priv-hash YOUR_PRIV_SECRET --raw-secret
```
This command produces output like this
```
Authhash: f3d8982fc28e8d1346c26eee49eb2c4a5950c934
Privhash: 0596ab30b315576a4e9f7d7bde65bf49b749e335
```
Now define a SNMPv3 user:
```
esxcli system snmp set --users authpriv/f3d8982fc28e8d1346c26eee49eb2c4a5950c934/0596ab30b315576a4e9f7d7bde65bf49b749e335/priv
esxcli system snmp set -L "Yourcity, Yourcountry [60.4,5.3]"
@ -213,34 +243,42 @@ esxcli system snmp set -C noc@your.org
esxcli system snmp set --enable true
```
>Note: In case of snmp timouts, disable the firewall with `esxcli network firewall set --enabled false`
>If snmp timeouts still occur with firewall disabled, migrate VMs if needed and reboot ESXi host.
>Note: In case of snmp timouts, disable the firewall with `esxcli
>network firewall set --enabled false` If snmp timeouts still occur
>with firewall disabled, migrate VMs if needed and reboot ESXi host.
#### VCenter 6.x
Log on to your ESX server by means of ssh. You may have to enable the ssh service in the GUI first.
From the CLI, execute the following commands:
Log on to your ESX server by means of ssh. You may have to enable the
ssh service in the GUI first. From the CLI, execute the following
commands:
```
snmp.set --authentication SHA1
snmp.set --privacy AES128
snmp.hash --auth_hash YOUR_AUTH_SECRET --priv_hash YOUR_PRIV_SECRET --raw_secret true
```
This command produces output like this
```
Privhash: 0596ab30b315576a4e9f7d7bde65bf49b749e335
Authhash: f3d8982fc28e8d1346c26eee49eb2c4a5950c934
```
Now define a SNMPv3 user:
```
snmp.set --users authpriv/f3d8982fc28e8d1346c26eee49eb2c4a5950c934/0596ab30b315576a4e9f7d7bde65bf49b749e335/priv
snmp.enable
```
## Operating systems
### Linux (snmpd v2)
Replace your snmpd.conf file by the example below and edit it with appropriate community in "RANDOMSTRINGGOESHERE".
Replace your snmpd.conf file by the example below and edit it with
appropriate community in "RANDOMSTRINGGOESHERE".
```
vi /etc/snmp/snmpd.conf
@ -266,7 +304,11 @@ extend .1.3.6.1.4.1.2021.7890.1 distro /usr/bin/distro
#extend .1.3.6.1.4.1.2021.7890.4 serial '/bin/cat /sys/devices/virtual/dmi/id/product_serial'
```
**NOTE**: On some systems the snmpd is running as its own user, which means it can't read `/sys/devices/virtual/dmi/id/product_serial` which is mode 0400. One solution is to include `@reboot chmod 444 /sys/devices/virtual/dmi/id/product_serial` in the crontab for root or equivalent.
**NOTE**: On some systems the snmpd is running as its own user, which
means it can't read `/sys/devices/virtual/dmi/id/product_serial` which
is mode 0400. One solution is to include `@reboot chmod 444
/sys/devices/virtual/dmi/id/product_serial` in the crontab for root or
equivalent.
The LibreNMS server include a copy of this example here:
@ -285,21 +327,26 @@ chmod +x /usr/bin/distro
Go to /etc/snmp/snmpd.conf
Open the file in vi or nano /etc/snmp/snmpd.conf and add the following line to create SNMPV3 User (replace username and passwords with your own):
Open the file in vi or nano /etc/snmp/snmpd.conf and add the following
line to create SNMPV3 User (replace username and passwords with your
own):
```
createUser authPrivUser MD5 "authPassword" DES "privPassword"
```
Make sure the agent listens to all interfaces by adding the following line inside snmpd.conf:
Make sure the agent listens to all interfaces by adding the following
line inside snmpd.conf:
```
agentAddress udp:161,udp6:[::1]:161
```
This line simply means listen to connections across all interfaces IPv4 and IPv6 respectively
This line simply means listen to connections across all interfaces
IPv4 and IPv6 respectively
Uncomment and change the following line to give read access to the username created above (rouser is what LibreNMS uses) :
Uncomment and change the following line to give read access to the
username created above (rouser is what LibreNMS uses) :
```
#rouser authPrivUser priv
@ -314,48 +361,59 @@ syscontact Your Name <your@email.address>
Save and exit the file
#### Restart the snmpd service:
#### Restart the snmpd service
##### CentOS 6 / Red hat 6
```
service snmpd restart
```
##### CentOS 7 / Red hat 7
```
systemctl restart snmpd
```
##### Ubuntu
```
service snmpd restart
```
### Windows Server 2008 R2
1. Log in to your Windows Server 2008 R2
2. Start "Server Manager" under "Administrative Tools"
3. Click "Features" and then click "Add Feature"
5. Check (if not checked) "SNMP Service", click "Next" until "Install"
6. Start "Services" under "Administrative Tools"
7. Edit "SNMP Service" properties
8. Go to the security tab
9. In "Accepted community name" click "Add" to add your community string and permission
10. In "Accept SNMP packets from these hosts" click "Add" and add your LibreNMS server IP address
11. Validate change by clicking "Apply"
1. Start "Server Manager" under "Administrative Tools"
1. Click "Features" and then click "Add Feature"
1. Check (if not checked) "SNMP Service", click "Next" until "Install"
1. Start "Services" under "Administrative Tools"
1. Edit "SNMP Service" properties
1. Go to the security tab
1. In "Accepted community name" click "Add" to add your community string and permission
1. In "Accept SNMP packets from these hosts" click "Add" and add your
LibreNMS server IP address
1. Validate change by clicking "Apply"
### Windows Server 2012 R2 and 2016
1. Log in to your Windows Server 2012 R2
2. Start "Server Manager" under "Administrative Tools"
3. Click "Manage" and then "Add Roles and Features"
4. Continue by pressing "Next" to the "Features" menu
5. Install (if not installed) "SNMP Service"
6. Start "Services" under "Administrative Tools"
7. Edit "SNMP Service" properties
8. Go to the security tab
9. In "Accepted community name" click "Add" to add your community string and permission
10. In "Accept SNMP packets from these hosts" click "Add" and add your LibreNMS server IP address
11. Validate change by clicking "Apply"
1. Start "Server Manager" under "Administrative Tools"
1. Click "Manage" and then "Add Roles and Features"
1. Continue by pressing "Next" to the "Features" menu
1. Install (if not installed) "SNMP Service"
1. Start "Services" under "Administrative Tools"
1. Edit "SNMP Service" properties
1. Go to the security tab
1. In "Accepted community name" click "Add" to add your community string and permission
1. In "Accept SNMP packets from these hosts" click "Add" and add your
LibreNMS server IP address
1. Validate change by clicking "Apply"
### Mac OSX
Step 1: ```sudo nano /etc/snmp/snmpd.conf```
```bash
#Allow read-access with the following SNMP Community String:
rocommunity public
@ -375,7 +433,9 @@ sysName SystemName
# to identify this as a MAC OS system.
sysobjectid 1.3.6.1.4.1.8072.3.2.16
```
Step 2:
``` bash
Step 2:
``` bash
sudo launchctl load -w /System/Library/LaunchDaemons/org.net-snmp.snmpd.plist
```

66
doc/Support/SSL-Configuration.md
View File

@ -3,22 +3,35 @@ path: blob/master/doc/
# Ubuntu 16.04
### Enabling HTTPS - Nginx
This example is specifically for Ubuntu 16.04 with Nginx and uses an SSL certificate from Let's Encrypt.
Please follow [this](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-16-04) excellent tutorial on setting up nginx with an SSL cert from LetsEncrypt.
## Enabling HTTPS - Nginx
#### Step 1
Follow the LetsEncrypt tutorial until you get to *Step 2: Obtain and SSL Certificate.*
In this section you need to change some config in the Nginx configuration. The tutorial directs you to edit `/etc/nginx/sites-available/default` however in the standard LibreNMS install, the file you need to edit is actually `/etc/nginx/conf.d/librenms.conf`.
This example is specifically for Ubuntu 16.04 with Nginx and uses an
SSL certificate from Let's Encrypt. Please follow
[this](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-16-04)
excellent tutorial on setting up nginx with an SSL cert from LetsEncrypt.
#### Step 2
When you get to *Step 3: Configure TLS/SSL on Web Server (Nginx)* there are some differences again.
Follow the instructions regarding the "snippet" configuration, the main differences come when you get to *Adjust the Nginx Configuration to Use SSL*.
Here you are again directed to edit `/etc/nginx/sites-available/default`, so we need to go to `/etc/nginx/conf.d/librenms.conf`.
### Step 1
Follow the LetsEncrypt tutorial until you get to *Step 2: Obtain and
SSL Certificate.* In this section you need to change some config in
the Nginx configuration. The tutorial directs you to edit
`/etc/nginx/sites-available/default` however in the standard LibreNMS
install, the file you need to edit is actually
`/etc/nginx/conf.d/librenms.conf`.
### Step 2
When you get to *Step 3: Configure TLS/SSL on Web Server (Nginx)*
there are some differences again. Follow the instructions regarding
the "snippet" configuration, the main differences come when you get to
*Adjust the Nginx Configuration to Use SSL*. Here you are again
directed to edit `/etc/nginx/sites-available/default`, so we need to
go to `/etc/nginx/conf.d/librenms.conf`.
`sudo vi /etc/nginx/sites-available/default`
The top section of this file will look like this:
```
server {
listen 80;
@ -29,7 +42,9 @@ server {
access_log /opt/librenms/logs/access_log;
error_log /opt/librenms/logs/error_log;
```
Edit it to look like this (obviously changing example.com to your actual domain name):
```
server {
listen 80;
@ -50,7 +65,9 @@ server {
access_log /opt/librenms/logs/access_log;
error_log /opt/librenms/logs/error_log;
```
This config will redirect HTTP traffic to HTTPS and use the SSL config that you have just set up.
This config will redirect HTTP traffic to HTTPS and use the SSL config
that you have just set up.
Check for syntax errors
`sudo nginx -t`
@ -58,20 +75,28 @@ Check for syntax errors
Then restart Nginx
`sudo systemctl restart nginx`
#### Step 3
### Step 3
Follow the rest of the tutorial, especially if you have the server's firewall enabled.
# CentOS
#### Enabling HTTPS - Apache
This example is specifically for CentOS 7 with Apache
Please follow [this](https://wiki.centos.org/HowTos/Https) How To from CentOS wiki on setting up Apache with a SSL cert.
#### Step 1
Follow the How to until you get to step 3. This is going to be little different with LibreNMS.
You will need to make changes in here `sudo vi /etc/httpd/conf.d/librenms.conf`
## Enabling HTTPS - Apache
This example is specifically for CentOS 7 with Apache
Please follow [this](https://wiki.centos.org/HowTos/Https) How To from
CentOS wiki on setting up Apache with a SSL cert.
### Step 1
Follow the How to until you get to step 3. This is going to be little
different with LibreNMS. You will need to make changes in here `sudo
vi /etc/httpd/conf.d/librenms.conf`
Your VirtualHost for 443 will need to look something like this for LibreNMS
(obviously changing librenms.example.com to your actual domain name)
```
<VirtualHost *:443>
SSLEngine on
@ -90,8 +115,9 @@ Your VirtualHost for 443 will need to look something like this for LibreNMS
</VirtualHost>
```
#### Step 2
### Step 2
Then restart Apache `sudo systemctl restart httpd`
#### Step 3
### Step 3
Follow the rest of the How To, especially if you have the server's firewall enabled.

17
doc/Support/index.md
View File

@ -1,20 +1,19 @@
# How to get Help
path: blob/master/doc/
* Browse through the navigation on the left
* Search in the upper right
* Check the [frequently asked questions](FAQ.md)
# How to get Help
- Browse through the navigation on the left
- Search in the upper right
- Check the [frequently asked questions](FAQ.md)
# Additional Support
We have a few methods for you to get in touch to ask for help.
[Community Forum](https://community.librenms.org)
- [Community Forum](https://community.librenms.org)
- [Ask for Help](https://community.librenms.org/c/help)
- [Feature Requests](https://community.librenms.org/c/feature-requests?order=op_likes&status=open)
[Discord](https://t.libren.ms/discord) Active chat and discussion
[Bug Reports](https://community.librenms.org/c/help)
- [Discord](https://t.libren.ms/discord) Active chat and discussion
- [Bug Reports](https://community.librenms.org/c/help)