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

Documentation cleanup of Basic Setup, Advanced Setup, 3rd Party Integration sections (#13018)

Browse Source 
* TOC cleanup of Basic Setup, Advanced Setup, 3rd Party Integration sections
This commit is contained in:
rhinoau
2021-07-10 03:34:01 +08:00
committed by GitHub
parent fbf653f02e
commit 02c2cd47b3
31 changed files with 403 additions and 389 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,15 +1,17 @@
source: Extensions/Agent-Setup.md
path: blob/master/doc/
# Check_MK Setup
The agent can be used to gather data from remote systems you can use
LibreNMS in combination with check_mk (found
[here](https://github.com/librenms/librenms-agent)). The agent can be
extended to include data about [applications](Applications.md) on the
remote system.
# Installation
## Installation
## Linux / BSD
### Linux / BSD
Make sure that systemd or xinetd is installed on the host you want to
run the agent on.
@@ -71,7 +73,7 @@ monitor. Under the modules section, ensure that unix-agent is enabled.
10: Wait for around 10 minutes and you should start seeing data in
your graphs under Apps for the device.
### Restrict the devices on which the agent listens: Linux systemd
#### Restrict the devices on which the agent listens: Linux systemd
If you want to restrict which network adapter the agent listens on, do the following:
1: Edit `/etc/systemd/system/check_mk.socket`
@@ -81,7 +83,7 @@ If you want to restrict which network adapter the agent listens on, do the follo
3: If the script has already been enabled in systemd, you may need to issue a `systemctl daemon-reload` and then `systemctl restart check_mk.socket`
## Windows
### Windows
1. Grab version 1.2.6b5 of the check_mk agent from the check_mk github repo (exe/msi or compile it yourself depending on your usage): <https://github.com/tribe29/checkmk/tree/v1.2.6b5/agents/windows>
2. Run the msi / exe
3. Make sure your LibreNMS instance can reach TCP port 6556 on your target.

252
doc/Extensions/Applications.md
View File

@@ -1,7 +1,7 @@
source: Extensions/Applications.md
path: blob/master/doc/
# Introduction
# Applications
You can use Application support to graph performance statistics of
many applications.
@@ -142,7 +142,7 @@ by following the steps under the `SNMP Extend` heading.
1. [Voip-monitor](#voip-monitor) - SNMP extend
1. [ZFS](#zfs) - SNMP extend
# Apache
## Apache
Either use SNMP extend or use the agent.
@@ -150,7 +150,7 @@ Note that you need to install and configure the Apache
[mod_status](https://httpd.apache.org/docs/2.4/en/mod/mod_status.html)
module before trying the script.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host (the host must be added
to LibreNMS devices)
@@ -189,7 +189,7 @@ extend apache /etc/snmp/apache-stats.py
snmpwalk <various options depending on your setup> localhost NET-SNMP-EXTEND-MIB::nsExtendOutput2Table
```
## Agent
### Agent
[Install the agent](Agent-Setup.md) on this device if it isn't already
and copy the `apache` script to `/usr/lib/check_mk_agent/local/`
@@ -208,11 +208,11 @@ mkdir -p /var/cache/librenms/
3: On the device page in Librenms, edit your host and check the
`Apache` under the Applications tab.
# Asterisk
## Asterisk
A small shell script that reports various Asterisk call status.
## SNMP Extend
### SNMP Extend
1: Download the [asterisk
script](https://github.com/librenms/librenms-agent/blob/master/snmp/asterisk)
@@ -239,11 +239,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# backupninja
## backupninja
A small shell script that reports status of last backupninja backup.
## SNMP Extend
### SNMP Extend
1: Download the [backupninja
script](https://github.com/librenms/librenms-agent/blob/master/snmp/backupninja.py)
@@ -261,7 +261,7 @@ extend backupninja /etc/snmp/backupninja.py
4: Restart snmpd on your host
# BIND9 aka named
## BIND9 aka named
1: Create stats file with appropriate permissions:
@@ -333,7 +333,7 @@ zero_stats = A 0/1 boolean for if the stats file should be zeroed
If you want to guess at the configuration, call the script with `-g`
and it will print out what it thinks it should be.
## SNMP Extend
### SNMP Extend
1: Copy the bind shell script, to the desired host.
@@ -359,7 +359,7 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
## Agent
### Agent
1: [Install the agent](Agent-Setup.md) on this device if it isn't
already and copy the script to `/usr/lib/check_mk_agent/local/bind`
@@ -369,7 +369,7 @@ via `wget https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/
3: Set the variable 'agent' to '1' in the config.
# Certificate
## Certificate
A small python3 script that checks age and remaining validity of certificates
@@ -391,7 +391,7 @@ Content of an example /etc/snmp/certificate.json . Please edit with your own set
Key 'domains' contains a list of domains to check.
Optional you can define a port. By default it checks on port 443.
## SNMP Extend
### SNMP Extend
1. Copy the shell script to the desired host.
```
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/certificate.py -O /etc/snmp/certificate.py
@@ -407,7 +407,7 @@ extend certificate /etc/snmp/certificate.py
The application should be auto-discovered as described at the top of the page. If it is not, please follow the steps set out under `SNMP Extend` heading top of page.
# C.H.I.P
## C.H.I.P
C.H.I.P. is a $9 R8 based tiny computer ideal for small projects.
Further details: <https://getchip.com/pages/chip>
@@ -432,14 +432,14 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# DHCP Stats
## DHCP Stats
A small python3 script that reports current DHCP leases stats and pool usage.
Also you have to install the dhcpd-pools Package.
Under Ubuntu/Debian just run `apt install dhcpd-pools`
## SNMP Extend
### SNMP Extend
1: Copy the shell script to the desired host.
@@ -471,13 +471,13 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Docker Stats
## Docker Stats
It allows you to know which container docker run and their stats.
This script require: jq
## SNMP Extend
### SNMP Extend
1: Install jq
```
@@ -504,11 +504,11 @@ extend docker /etc/snmp/docker-stats.sh
systemctl restart snmpd
```
# Entropy
## Entropy
A small shell script that checks your system's available random entropy.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -530,11 +530,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# EXIM Stats
## EXIM Stats
SNMP extend script to get your exim stats data into your host.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -563,9 +563,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Fail2ban
## Fail2ban
## SNMP Extend
### SNMP Extend
1: Copy the shell script, fail2ban, to the desired host.
@@ -622,9 +622,9 @@ other SNMP information being polled.
For additional details of the switches, please see the POD in the
script it self at the top.
# FreeBSD NFS Client
## FreeBSD NFS Client
## SNMP Extend
### SNMP Extend
1: Copy the shell script, fbsdnfsserver, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/fbsdnfsclient
@@ -644,9 +644,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# FreeBSD NFS Server
## FreeBSD NFS Server
## SNMP Extend
### SNMP Extend
1: Copy the shell script, fbsdnfsserver, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/fbsdnfsserver
@@ -666,7 +666,7 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# FreeRADIUS
## FreeRADIUS
The FreeRADIUS application extension requires that status_server be
enabled in your FreeRADIUS config. For more information see:
@@ -695,7 +695,7 @@ radclient -x localhost:18121 status adminsecret
Note that adminsecret is the default secret key in status_server.
Change if you've modified this.
## SNMP Extend
### SNMP Extend
1: Copy the freeradius shell script, to the desired host.
@@ -721,7 +721,7 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
## Agent
### Agent
1: [Install the agent](Agent-Setup.md) on this device if it isn't
already and copy the script to
@@ -738,11 +738,11 @@ variable accordingly.
4: Edit the freeradius.sh script and set the variable 'AGENT' to '1'
in the config.
# Freeswitch
## Freeswitch
A small shell script that reports various Freeswitch call status.
## Agent
### Agent
1: [Install the agent](Agent-Setup.md) on your Freeswitch server if it
isn't already
@@ -757,7 +757,7 @@ authentication.
4: Verify it is working by running `/usr/lib/check_mk_agent/local/freeswitch`
## SNMP Extend
### SNMP Extend
1: Copy the [freeswitch
script](https://github.com/librenms/librenms-agent/blob/master/agent-local/freeswitch)
@@ -783,9 +783,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# GPSD
## GPSD
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -807,7 +807,7 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading at the top of the page.
## Agent
### Agent
[Install the agent](Agent-Setup.md) on this device if it isn't already
and copy the `gpsd` script to `/usr/lib/check_mk_agent/local/`
@@ -816,10 +816,10 @@ You may need to configure `$server` or `$port`.
Verify it is working by running `/usr/lib/check_mk_agent/local/gpsd`
# Icecast
## Icecast
Shell script that reports load average/memory/open-files stats of Icecast
## SNMP Extend
### SNMP Extend
1. Copy the shell script, icecast-stats.sh, to the desired host (the host must be added to LibreNMS devices)
```
@@ -835,9 +835,9 @@ wget https://github.com/librenms/librenms-agent/raw/master/snmp/icecast-stats.sh
```
extend icecast /etc/snmp/icecast-stats.sh
```
# mailcow-dockerized postfix
## mailcow-dockerized postfix
## SNMP Extend
### SNMP Extend
1: Download the script into the desired host.
@@ -861,9 +861,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Mailscanner
## Mailscanner
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -885,11 +885,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Mdadm
## Mdadm
This shell script checks mdadm health and array data
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -911,9 +911,9 @@ The application should be auto-discovered as described at the
top of the page. If it is not, please follow the steps set out
under `SNMP Extend` heading top of page.
# Memcached
## Memcached
## SNMP Extend
### SNMP Extend
1: Copy the [memcached
script](https://github.com/librenms/librenms-agent/blob/master/agent-local/memcached)
@@ -937,9 +937,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Munin
## Munin
## Agent
### Agent
1. Install the script to your agent: `wget
https://raw.githubusercontent.com/librenms/librenms-agent/master/agent-local/munin
@@ -968,7 +968,7 @@ fi
echo -n "foobar.value " $(date +%s) #Populate a value, here unix-timestamp
```
# MySQL
## MySQL
Create the cache directory, '/var/cache/librenms/' and make sure
that it is owned by the user running the SNMP daemon.
@@ -1013,7 +1013,7 @@ Note also if you get a mysql error `Uncaught TypeError: mysqli_num_rows(): Argum
this is because you are using a newer mysql version which doesnt support `UNBLOCKING` for slave statuses,
so you need to also include the line `$chk_options['slave'] = false;` into `mysql.cnf` to skip checking slave statuses
## Agent
### Agent
[Install the agent](Agent-Setup.md) on this device if it isn't already
@@ -1021,7 +1021,7 @@ and copy the `mysql` script to `/usr/lib/check_mk_agent/local/`
Verify it is working by running `/usr/lib/check_mk_agent/local/mysql`
## SNMP extend
### SNMP extend
1: Copy the mysql script to the desired host.
```
@@ -1044,7 +1044,7 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# NGINX
## NGINX
NGINX is a free, open-source, high-performance HTTP server: <https://www.nginx.org/>
@@ -1061,7 +1061,7 @@ location /nginx-status {
}
```
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -1083,16 +1083,16 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
## Agent
### Agent
[Install the agent](Agent-Setup.md) on this device if it isn't already
and copy the `nginx` script to `/usr/lib/check_mk_agent/local/`
# NFS Server
## NFS Server
Export the NFS stats from as server.
## SNMP Extend
### SNMP Extend
1: Edit your snmpd.conf file (usually /etc/snmp/snmpd.conf) and add :
@@ -1104,11 +1104,11 @@ note : find out where cat is located using : `which cat`
2: reload snmpd service to activate the configuration
# NTP Client
## NTP Client
A shell script that gets stats from ntp client.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -1130,11 +1130,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# NTP Server aka NTPD
## NTP Server aka NTPD
A shell script that gets stats from ntp server (ntpd).
## SNMP Extend
### SNMP Extend
1. Download the script onto the desired host.
@@ -1156,9 +1156,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Nvidia GPU
## Nvidia GPU
## SNMP Extend
### SNMP Extend
1: Copy the shell script, nvidia, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/nvidia -O
@@ -1183,11 +1183,11 @@ sees them as being.
For questions about what the various values are/mean, please see the
nvidia-smi man file under the section covering dmon.
# Open Grid Scheduler
## Open Grid Scheduler
Shell script to track the OGS/GE jobs running on clusters.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -1209,11 +1209,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Opensips
## Opensips
Script that reports load-average/memory/open-files stats of Opensips
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host. `wget
https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/opensips-stats.sh
@@ -1229,7 +1229,7 @@ Script that reports load-average/memory/open-files stats of Opensips
extend opensips /etc/snmp/opensips-stats.sh
```
# OS Updates
## OS Updates
A small shell script that checks your system package manager for any
available updates. Supports apt-get/pacman/yum/zypper package
@@ -1239,7 +1239,7 @@ For pacman users automatically refreshing the database, it is
recommended you use an alternative database location
`--dbpath=/var/lib/pacman/checkupdate`
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host.
@@ -1268,9 +1268,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# PHP-FPM
## PHP-FPM
## SNMP Extend
### SNMP Extend
1: Copy the shell script, phpfpmsp, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/phpfpmsp
@@ -1296,9 +1296,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Pi-hole
## Pi-hole
## SNMP Extend
### SNMP Extend
1: Copy the shell script, pi-hole, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/pi-hole -O
@@ -1321,9 +1321,9 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Portactivity
## Portactivity
## SNMP Extend
### SNMP Extend
Ubuntu is shown below.
@@ -1360,9 +1360,9 @@ use the -P flag.
Please note that for only TCP[46] services are supported.
# Postfix
## Postfix
## SNMP Extend
### SNMP Extend
1: Copy the shell script, postfix-queues, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/postfix-queues
@@ -1405,9 +1405,9 @@ Extend` heading top of page.
> installed manually as it is not officially supported. CentOs 6 rpms
> seem to work without issues.
# Postgres
## Postgres
## SNMP Extend
### SNMP Extend
1: Copy the shell script, postgres, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/postgres -O
@@ -1438,11 +1438,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# PowerDNS
## PowerDNS
An authoritative DNS server: <https://www.powerdns.com/auth.html>
## SNMP Extend
### SNMP Extend
1: Copy the shell script, powerdns.py, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/powerdns.py
@@ -1462,22 +1462,22 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
## Agent
### Agent
[Install the agent](Agent-Setup.md) on this device if it isn't already
and copy the `powerdns` script to `/usr/lib/check_mk_agent/local/`
# PowerDNS Recursor
## PowerDNS Recursor
A recursive DNS server: <https://www.powerdns.com/recursor.html>
## Direct
### Direct
The LibreNMS polling host must be able to connect to port 8082 on the
monitored device. The web-server must be enabled, see the Recursor
docs: <https://doc.powerdns.com/md/recursor/settings/#webserver>
## Variables
### Variables
`$config['apps']['powerdns-recursor']['api-key']` required, this is
defined in the Recursor config
@@ -1488,7 +1488,7 @@ port to connect to PowerDNS Recursor on. The default is 8082
`$config['apps']['powerdns-recursor']['https']` true or false,
defaults to use http.
## SNMP Extend
### SNMP Extend
1: Copy the shell script, powerdns-recursor, to the desired
host. `wget
@@ -1509,7 +1509,7 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
## Agent
### Agent
[Install the agent](Agent-Setup.md) on this device if it isn't already
and copy the `powerdns-recursor` script to
@@ -1517,9 +1517,9 @@ and copy the `powerdns-recursor` script to
This script uses `rec_control get-all` to collect stats.
# PowerDNS-dnsdist
## PowerDNS-dnsdist
## SNMP Extend
### SNMP Extend
1: Copy the BASH script to the desired host.
@@ -1541,7 +1541,7 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# PowerMon
## PowerMon
PowerMon tracks the power usage on your host and can report on both consumption
and cost, using a python script installed on the host.
@@ -1565,9 +1565,9 @@ Because the methods are unreliable for all hardware, you need to declare to the
script which method to use. The are several options to assist with testing, see
`--help`.
## SNMP Extend
### SNMP Extend
### Initial setup
#### Initial setup
1. Download the python script onto the host:
```
@@ -1668,7 +1668,7 @@ vi /usr/local/bin/powermon-snmp.py
If you see a reading of `0.0` it is likely this method is not supported for
your system. If not, continue.
### Finishing Up
#### Finishing Up
5. Edit your snmpd.conf file (usually `/etc/snmp/snmpd.conf`) and add the following:
```
@@ -1686,7 +1686,7 @@ systemctl reload snmpd
7. You're now ready to enable the application in LibreNMS.
# Proxmox
## Proxmox
1: For Proxmox 4.4+ install the libpve-apiclient-perl package `apt
install libpve-apiclient-perl`
@@ -1716,7 +1716,7 @@ Debian-snmp ALL=(ALL) NOPASSWD: /usr/local/bin/proxmox
6: Restart snmpd on your host
# Puppet Agent
## Puppet Agent
SNMP extend script to get your Puppet Agent data into your host.
@@ -1753,11 +1753,11 @@ custom summary file has highest priority
4: Restart snmpd on the host
# PureFTPd
## PureFTPd
SNMP extend script to monitor PureFTPd.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host. `wget
https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/pureftpd.py
@@ -1793,11 +1793,11 @@ pureftpd.json. The file has to be located in /etc/snmp/.
5: Restart snmpd on your host
# Raspberry PI
## Raspberry PI
SNMP extend script to get your PI data into your host.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host. `wget
https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/raspberry.sh
@@ -1823,11 +1823,11 @@ the user snmpd is using with `ps aux | grep snmpd`
5: Restart snmpd on PI host
# Redis
## Redis
SNMP extend script to monitor your Redis Server
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host. `wget
https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/redis.py
@@ -1841,7 +1841,7 @@ SNMP extend script to monitor your Redis Server
extend redis /etc/snmp/redis.py
```
# RRDCached
## RRDCached
Install/Setup:
For Install/Setup Local Librenms RRDCached: Please see [RRDCached](RRDCached.md)
@@ -1853,7 +1853,7 @@ Will collect stats by:
SNMP extend script to monitor your (remote) RRDCached via snmp
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host. `wget
https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/rrdcached
@@ -1867,11 +1867,11 @@ SNMP extend script to monitor your (remote) RRDCached via snmp
extend rrdcached /etc/snmp/rrdcached
```
# SDFS info
## SDFS info
A small shell script that exportfs SDFS volume info.
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host (the host must be added
to LibreNMS devices)
@@ -1894,11 +1894,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Seafile
## Seafile
SNMP extend script to monitor your Seafile Server
## SNMP Extend
### SNMP Extend
1: Copy the Python script, seafile.py, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/seafile.py -O
@@ -1944,9 +1944,9 @@ hide_monitoring_account = With this Boolean you can hide the Account which you
**Note:**It is recommended to use a dedicated Administrator account for monitoring.
# SMART
## SMART
## SNMP Extend
### SNMP Extend
1. Copy the Perl script, smart, to the desired host.
@@ -2036,9 +2036,9 @@ Also if the system you are using uses non-static device naming based
on bus information, it may be worthwhile just using the SN as the
device ID is going to be irrelevant in that case.
# Squid
## Squid
## SNMP Proxy
### SNMP Proxy
1: Enable SNMP for Squid like below, if you have not already, and
restart it.
@@ -2065,9 +2065,9 @@ for net-snmp, please see the links below.
<http://wiki.squid-cache.org/Features/Snmp>
<http://www.net-snmp.org/wiki/index.php/Snmpd_proxy>
# TinyDNS aka djbdns
## TinyDNS aka djbdns
## Agent
### Agent
[Install the agent](Agent-Setup.md) on this device if it isn't already
and copy the `tinydns` script to `/usr/lib/check_mk_agent/local/`
@@ -2097,7 +2097,7 @@ chown dnslog:nofiles /service/dns/log/main/tinystats
(Gentoo) it doesn't rehook the logging and I'm forced to restart it
entirely.
# Unbound
## Unbound
Unbound configuration:
@@ -2116,7 +2116,7 @@ remote-control:
Restart your unbound after changing the configuration, verify it is
working by running `unbound-control stats`.
## Option 1: SNMP Extend (Preferred and easiest method)
### Option 1: SNMP Extend (Preferred and easiest method)
1: Copy the shell script, unbound, to the desired host. `wget
https://github.com/librenms/librenms-agent/raw/master/snmp/unbound -O
@@ -2136,16 +2136,16 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
## Option 2: Agent
### Option 2: Agent
[Install the agent](#agent-setup) on this device if it isn't already
and copy the `unbound.sh` script to `/usr/lib/check_mk_agent/local/`
# UPS-nut
## UPS-nut
A small shell script that exports nut ups status.
## SNMP Extend
### SNMP Extend
1: Copy the [ups
nut](https://github.com/librenms/librenms-agent/blob/master/snmp/ups-nut.sh)
@@ -2165,11 +2165,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# UPS-apcups
## UPS-apcups
A small shell script that exports apcacess ups status.
## SNMP Extend
### SNMP Extend
1: Copy the [ups
apcups](https://github.com/librenms/librenms-agent/blob/master/snmp/ups-apcups)
@@ -2196,11 +2196,11 @@ The application should be auto-discovered as described at the top of
the page. If it is not, please follow the steps set out under `SNMP
Extend` heading top of page.
# Voip-monitor
## Voip-monitor
Shell script that reports cpu-load/memory/open-files files stats of Voip Monitor
## SNMP Extend
### SNMP Extend
1: Download the script onto the desired host. `wget
https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/voipmon-stats.sh
@@ -2214,9 +2214,9 @@ Shell script that reports cpu-load/memory/open-files files stats of Voip Monitor
extend voipmon /etc/snmp/voipmon-stats.sh
```
# ZFS
## ZFS
## SNMP Extend
### SNMP Extend
`zfs-linux` requires python3 >=python3.5.
@@ -2227,7 +2227,7 @@ The installation steps are:
1. Make the script executable
1. Edit snmpd.conf to include ZFS stats
### FreeBSD
#### FreeBSD
```
wget https://github.com/librenms/librenms-agent/raw/master/snmp/zfs-freebsd -O /etc/snmp/zfs-freebsd
@@ -2235,7 +2235,7 @@ chmod +x /etc/snmp/zfs-freebsd
echo "extend zfs /etc/snmp/zfs-freebsd" >> /etc/snmp/snmpd.conf
```
### Linux
#### Linux
```
wget https://github.com/librenms/librenms-agent/raw/master/snmp/zfs-linux -O /etc/snmp/zfs-linux

72
doc/Extensions/Authentication.md
View File

@@ -1,12 +1,12 @@
source: Extensions/Authentication.md
path: blob/master/doc/
# Authentication modules
# Authentication Options
LibreNMS supports multiple authentication modules along with [Two Factor Auth](Two-Factor-Auth.md).
Here we will provide configuration details for these modules.
# Available authentication modules
## Available authentication modules
- MySQL: [mysql](#mysql-authentication)
@@ -25,7 +25,7 @@ Here we will provide configuration details for these modules.
⚠️ **When enabling a new authentication module, the local users will no
longer be available to log in.**
# Enable authentication module
## Enable authentication module
To enable a particular authentication module you need to set this up
in config.php. Please note that only ONE module can be
@@ -36,7 +36,7 @@ the same time.
$config['auth_mechanism'] = "mysql";
```
# User levels and User account type
## User levels and User account type
- 1: **Normal User**: You will need to assign device / port
permissions for users at this level.
@@ -51,7 +51,7 @@ $config['auth_mechanism'] = "mysql";
**Note** Oxidized configs can often contain sensitive data. Because of
that only Administrator account type can see configs.
# Note for SELinux users
## Note for SELinux users
When using SELinux on the LibreNMS server, you need to allow Apache
(httpd) to connect LDAP/Active Directory server, this is disabled by
@@ -62,7 +62,7 @@ resources with this command:
setsebool -P httpd_can_connect_ldap=1
```
# Testing authentication
## Testing authentication
You can test authentication with this script:
@@ -72,7 +72,7 @@ You can test authentication with this script:
Enable debug output to troubleshoot issues
# MySQL Authentication
## MySQL Authentication
Config option: `mysql`
@@ -86,7 +86,7 @@ DB_USERNAME=DBUSER
DB_PASSWORD="DBPASS"
```
# Active Directory Authentication
## Active Directory Authentication
Config option: `active_directory`
@@ -97,7 +97,7 @@ If you have issues with secure LDAP try setting
`$config['auth_ad_check_certificates']` to `0`, this will ignore
certificate errors.
## Require actual membership of the configured groups
### Require actual membership of the configured groups
If you set `$config['auth_ad_require_groupmembership']` to 1, the
authenticated user has to be a member of the specific group.
@@ -105,7 +105,7 @@ Otherwise all users can authenticate, and will be either level 0 or
you may set `$config['auth_ad_global_read']` to 1 and all users will
have read only access unless otherwise specified.
## Old account cleanup
### Old account cleanup
Cleanup of old accounts is done by checking the authlog. You will need
to set the number of days when old accounts will be purged
@@ -115,7 +115,7 @@ Please ensure that you set the `$config['authlog_purge']` value to be
greater than `$config['active_directory']['users_purge']` otherwise old
users won't be removed.
## Sample configuration
### Sample configuration
```php
$config['auth_mechanism'] = 'active_directory';
@@ -139,7 +139,7 @@ and `ad-usergroup` with your standard user group. It is __highly
suggested__ to create a bind user, otherwise "remember me", alerting
users, and the API will not work.
## Active Directory redundancy
### Active Directory redundancy
You can set two Active Directory servers by editing the
`$config['auth_ad_url']` like this example:
@@ -148,7 +148,7 @@ You can set two Active Directory servers by editing the
$config['auth_ad_url'] = "ldaps://dc1.example.com ldaps://dc2.example.com";
```
## Active Directory LDAP filters
### Active Directory LDAP filters
You can add an LDAP filter to be ANDed with the builtin user filter (`(sAMAccountName=$username)`).
@@ -163,14 +163,14 @@ This yields `(&(objectclass=user)(sAMAccountName=$username))` for the
user filter and `(&(objectclass=group)(sAMAccountName=$group))` for
the group filter.
# LDAP Authentication
## LDAP Authentication
Config option: `ldap`
Install __php_ldap__ or __php7.0-ldap__, making sure to install the
same version as PHP.
## Standard config
### Standard config
```php
$config['auth_mechanism'] = 'ldap';
@@ -182,7 +182,7 @@ $config['auth_ldap_groups']['pfy']['level'] = 5; // set pfy group
$config['auth_ldap_groups']['support']['level'] = 1; // set support group as a normal user
```
## Additional options (usually not needed)
### Additional options (usually not needed)
```php
$config['auth_ldap_version'] = 3; # v2 or v3
@@ -198,7 +198,7 @@ $config['auth_ldap_userlist_filter'] = 'service=informatique'; // Replace 'servi
$config['auth_ldap_wildcard_ou'] = false; // Search for user matching user name independently of OU set in auth_ldap_suffix. Useful if your users are in different OU. Bind username, if set, still user auth_ldap_suffix
```
## LDAP bind user (optional)
### LDAP bind user (optional)
If your ldap server does not allow anonymous bind, it is highly
suggested to create a bind user, otherwise "remember me", alerting
@@ -210,7 +210,7 @@ $config['auth_ldap_binduser'] = 'ldapbind'; // will use auth_ldap_prefix and aut
$config['auth_ldap_bindpassword'] = 'password';
```
## LDAP server redundancy
### LDAP server redundancy
You can set two LDAP servers by editing the
`$config['auth_ldap_server']` like this example:
@@ -249,7 +249,7 @@ $config['auth_ldap_groups'] = [
];
```
# Radius Authentication
## Radius Authentication
Please note that a mysql user is created for each user the logs in
successfully. User level 1 is assigned to those accounts so you will
@@ -265,7 +265,7 @@ $config['radius']['users_purge'] = 14; // Purge users who haven't logged in f
$config['radius']['default_level'] = 1; // Set the default user level when automatically creating a user.
```
## Old account cleanup
### Old account cleanup
Cleanup of old accounts is done by checking the authlog. You will need
to set the number of days when old accounts will be purged
@@ -275,7 +275,7 @@ Please ensure that you set the `$config['authlog_purge']` value to be
greater than `$config['radius']['users_purge']` otherwise old users
won't be removed.
# HTTP Authentication
## HTTP Authentication
Config option: `http-auth`
@@ -293,7 +293,7 @@ $config['http_auth_guest'] = "guest";
This will then assign the userlevel for guest to all authenticated users.
## HTTP Authentication / AD Authorization
### HTTP Authentication / AD Authorization
Config option: `ad-authorization`
@@ -326,7 +326,7 @@ $config['auth_ad_bindpassword'] = "ad_bindpassword";
$config['auth_ldap_cache_ttl'] = 300;
```
## HTTP Authentication / LDAP Authorization
### HTTP Authentication / LDAP Authorization
Config option: `ldap-authorization`
@@ -347,14 +347,14 @@ To disabled this caching (highly discourage) set this option to 0.
$config['auth_ldap_cache_ttl'] = 300;
```
# View/embedded graphs without being logged into LibreNMS
## View/embedded graphs without being logged into LibreNMS
```php
$config['allow_unauth_graphs_cidr'] = array('127.0.0.1/32');
$config['allow_unauth_graphs'] = true;
```
# Single Sign-on
## Single Sign-on
The single sign-on mechanism is used to integrate with third party
authentication providers that are managed outside of LibreNMS - such
@@ -376,7 +376,7 @@ about validating the configuration - if it finds that certain values
in the configuration are not set, it will reject access rather than
try and guess.
## Basic Configuration
### Basic Configuration
To get up and running, all you need to do is configure the following values:
@@ -398,7 +398,7 @@ This happens to mimic the behaviour of [http-auth](#http-auth), so if
this is the kind of setup you want, you're probably better of just
going and using that mechanism.
## Security
### Security
If there is a proxy involved (e.g. EZProxy, Azure AD Application
Proxy, NGINX, mod_proxy) it's ___essential___ that you have some means
@@ -423,9 +423,9 @@ This configuration item should contain an array with a list of IP
addresses or CIDR prefixes that are allowed to connect to LibreNMS and
supply environment variables or headers.
## Advanced Configuration Options
### Advanced Configuration Options
### User Attribute
#### User Attribute
If for some reason your relying party doesn't store the username in
___REMOTE\_USER___, you can override this choice.
@@ -440,7 +440,7 @@ user - it's a special case. If you're using something different you
need to figure out of the ___HTTP\____ prefix is required or not
yourself.
### Automatic User Create/Update
#### Automatic User Create/Update
These are enabled by default:
@@ -466,15 +466,15 @@ $config['sso']['realname_attr'] = "displayName";
$config['sso']['descr_attr'] = "unscoped-affiliation
```
### Group Strategies
#### Group Strategies
#### Static
##### Static
As used above, ___static___ gives every single user the same privilege
level. If you're working with a small team, or don't need access
control, this is probably suitable.
#### Attribute
##### Attribute
```php
$config['sso']['group_strategy'] = "attribute";
@@ -488,7 +488,7 @@ the name of the attribute that the Relying Party exposes to LibreNMS -
as long as ___sso\_mode___ is correctly set, the mechanism should find
the value.
#### Group Map
##### Group Map
This is the most flexible (and complex) way of assigning privileges.
@@ -518,7 +518,7 @@ $config['sso']['group_filter'] = "/librenms-(.*)/i";
This filter causes the mechanism to only consider groups matching a regular expression.
### Logout Behaviour
#### Logout Behaviour
LibreNMS has no capability to log out a user authenticated via Single
Sign-On - that responsibility falls to the Relying Party.
@@ -532,7 +532,7 @@ $config['post_logout_action'] = '/Shibboleth.sso/Logout';
This option functions independently of the Single Sign-on mechanism.
## Complete Configuration
### Complete Configuration
This configuration works on my deployment with a Shibboleth relying
party, injecting environment variables, with the IDP supplying a list

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

@@ -51,7 +51,7 @@ $config['nets'][] = '192.168.0.0/24';
$config['nets'][] = '172.2.4.0/22';
```
## Exclusions
### Exclusions
If you have added a network as above but a single device exists within
it that you can't auto add, then you can exclude this with the following:
@@ -60,9 +60,9 @@ it that you can't auto add, then you can exclude this with the following:
$config['autodiscovery']['nets-exclude'][] = '192.168.0.1/32';
```
# Additional Options
## Additional Options
## Discovering devices by IP
### Discovering devices by IP
By default we don't add devices by IP address, we look for a reverse
dns name to be found and add with that. If this fails
@@ -82,12 +82,12 @@ returned over snmp by your devices). If you would like to allow
devices to be added with duplicate sysNames then please set
`$config['allow_duplicate_sysName'] = true;`.
# Discovery Methods
## Discovery Methods
Below are the methods for auto discovering devices. Each one can be
enabled or disabled and may have additional configuration options.
## ARP
### ARP
Disabled by default.
@@ -99,7 +99,7 @@ To enable, switch on globally the
`$config['discovery_modules']['discovery-arp'] = true;` or per device
within the Modules section.
## XDP
### XDP
Enabled by default.
@@ -136,13 +136,13 @@ $config['autodiscovery']['xdp_exclude']['sysdesc_regexp'][] = '/-K9W8-/'; // Cis
$config['autodiscovery']['cdp_exclude']['platform_regexp'][] = '/^Cisco IP Phone/'; //Cisco IP Phone
```
## OSPF
### OSPF
Enabled by default.
`$config['autodiscovery']['ospf'] = false;` to disable.
## BGP
### BGP
Enabled by default.
@@ -150,7 +150,7 @@ Enabled by default.
This module is invoked from bgp-peers discovery module.
## SNMP Scan
### SNMP Scan
Apart from the aforementioned Auto-Discovery options, LibreNMS is also
able to proactively scan a network for SNMP-enabled devices using the
@@ -184,7 +184,7 @@ optional arguments:
```
# Discovered devices
### Discovered devices
Newly discovered devices will be added to the `default_poller_group`, this value defaults to 0 if unset.

2
doc/Extensions/Dell-OpenManage.md
View File

@@ -30,7 +30,7 @@ Ensure that srvadmin is started, this is usually done by executing:
Once this has been done, add the device to LibreNMS as normal and you
will start to receive Temperatures and Fan speed data.
# Windows
## Windows
Download OpenManage from Dell's support page
[Link](http://www.dell.com/support/contents/us/en/04/article/product-support/self-support-knowledgebase/enterprise-resource-center/systemsmanagement/OMSA)

42
doc/Extensions/Dispatcher-Service.md
View File

@@ -9,14 +9,14 @@ The LibreNMS dispatcher service (`librenms-service.py`) is a new method
of running the poller service at set times. It does not replace the php scripts,
just the cron entries running them.
# External Requirements
## External Requirements
## A recent version of Python
### A recent version of Python
The LibreNMS service requires Python 3 and some features require
behaviour only found in Python3.4+.
## Python modules
### Python modules
- PyMySQL is recommended as it requires no C compiler to
install. MySQLclient can also be used, but does require compilation.
@@ -30,7 +30,7 @@ These can be obtained from your OS package manager, or from PyPI with the below
pip3 install -r requirements.txt
```
## Redis (distributed polling)
### Redis (distributed polling)
If you want to use distributed polling, you'll need a Redis instance
to coordinate the nodes. It's recommended that you do not share the
@@ -43,7 +43,7 @@ systems, and use redis-sentinel.
You should not rely on the password for the security of your
system. See <https://redis.io/topics/security>
## Memcached (distributed polling)
### Memcached (distributed polling)
LibreNMS can still use memcached as a locking mechanism when using
distributed polling. So you can configure memcached for this purpose
@@ -52,14 +52,14 @@ unless you have updates disabled.
See `Locking Mechanisms` at
<https://docs.librenms.org/Extensions/Distributed-Poller/>
## MySQL
### MySQL
You should already have this, but the pollers do need access to the
SQL database. The LibreNMS service runs faster and more aggressively
than the standard poller, so keep an eye on the number of open
connections and other important health metrics.
# Configuration
## Configuration
Connection settings are required in `.env`. The `.env` file is
generated after composer install and `APP_KEY` and `NODE_ID` are set.
@@ -75,7 +75,7 @@ DB_USERNAME=librenms
DB_PASSWORD=
```
## Distributed Polling Configuration
### Distributed Polling Configuration
Once you have your Redis database set up, configure it in the .env file on each node. Configure the redis cache driver for distributed locking.
@@ -93,7 +93,7 @@ REDIS_DB=0
CACHE_DRIVER=redis
```
## Basic Configuration
### Basic Configuration
Additional configuration settings can be set in `config.php` or
directly into the database.
@@ -141,7 +141,7 @@ If Consumed WS is below Maximum WS and Devices Pending is > 0, your hardware is
Maximum WS equals the number of workers multiplied with the number of seconds in the polling period. (default 300)
# Fast Ping
## Fast Ping
The [fast ping](Fast-Ping-Check.md) scheduler is disabled by default.
You can enable it by setting the following:
@@ -150,7 +150,7 @@ You can enable it by setting the following:
$config['service_ping_enabled'] = true;
```
# Watchdog
## Watchdog
The watchdog scheduler is disabled by default. You can enable it by setting the following:
@@ -160,24 +160,24 @@ $config['service_watchdog_enabled'] = true;
The watchdog scheduler will check that the poller log file has been written to within the last poll period. If there is no change to the log file since, the watchdog will restart the polling service. The poller log file is set by `$config['log_file']` and defaults to `./logs/librenms.log`
# Cron Scripts
## Cron Scripts
Once the LibreNMS service is installed, the cron scripts used by
LibreNMS are no longer required and must be removed.
# Service Installation
## Service Installation
A systemd unit file is provided - the sysv and upstart init scripts
could also be used with a little modification.
## systemd
### systemd
A systemd unit file can be found in `misc/librenms.service`. To
install run `cp /opt/librenms/misc/librenms.service
/etc/systemd/system/librenms.service && systemctl enable --now
librenms.service`
## systemd-watchdog
### systemd-watchdog
A systemd unit file can be found in `misc/librenms-watchdog.service`. To
install run `cp /opt/librenms/misc/librenms-watchdog.service
@@ -187,9 +187,9 @@ librenms.service`
This requires: python3-systemd (or python-systemd on older systems)
or https://pypi.org/project/systemd-python/
## OS-Specific Instructions
### OS-Specific Instructions
### RHEL/CentOS
#### RHEL/CentOS
To get the LibreNMS service running under python3.4+ on
RHEL-derivatives with minimal fuss, you can use the software
@@ -197,13 +197,13 @@ collections build:
First, enable SCL's on your system:
#### CentOS 7
##### CentOS 7
```
# yum install centos-release-scl
```
#### RHEL 7
##### RHEL 7
```
# subscription-manager repos --enable rhel-server-rhscl-7-rpms
@@ -228,9 +228,9 @@ If you want to use another version of python 3, change `rh-python36`
in the unit file and the commands above to match the name of the
replacement scl.
### Debian/Ubuntu
#### Debian/Ubuntu
#### Debian 9 (stretch)
##### Debian 9 (stretch)
install python3 and python-mysqldb. python-dotenv is not yet
available, but the testing package is working fine, you can grab it on

22
doc/Extensions/Distributed-Poller.md
View File

@@ -33,7 +33,7 @@ mechanisms available
All of the above locking mechanisms are natively supported in LibreNMS.
If none are specified, it will default to using SQL.
# Requirements for distributed polling
## Requirements for distributed polling
These requirements are above the normal requirements for a full LibreNMS install.
@@ -61,11 +61,11 @@ $config['distributed_poller'] = true;
$config['distributed_poller_group'] = 0;
```
# Locking mechanisms
## Locking mechanisms
Pick one of the following setups, do not use all of them at the same
time.
## Using REDIS
### Using REDIS
In your `.env` file you will need to specify a redis server, port and
the driver.
@@ -75,7 +75,7 @@ REDIS_HOST=HOSTNAME or IP
REDIS_PORT=6379
CACHE_DRIVER=redis
```
## Using Memcached
### Using Memcached
Preferably you should set the memcached server settings via the web UI.
Under Settings > Global Settings > Distributed poller, you fill out the
@@ -106,7 +106,7 @@ being monitored, all the way through to having a dedicated server for
each of the individual roles. Below are notes on what you need to
consider both from the software layer, but also connectivity.
### Web / API Layer
## Web / API Layer
This is typically Apache but we have setup guides for both Nginx and
Lighttpd which should work perfectly fine. There is nothing unique
@@ -120,7 +120,7 @@ web service can then generate rrd graphs via RRDCached. If RRDCached
isn't an option then you can mount the rrd directory to read the RRD
files directly.
### Database Server
## Database Server
MySQL / MariaDB - At the moment these are the only database servers
that are supported.
@@ -128,7 +128,7 @@ that are supported.
The pollers, web and API layers should all be able to access the
database server directly.
### RRD Storage
## RRD Storage
Central storage should be provided so all RRD files can be read from
and written to in one location. As suggested above, it's recommended
@@ -138,7 +138,7 @@ For this example, we are running RRDCached to allow all pollers and
web/api servers to read/write to the rrd files with the rrd directory
also exported by NFS for simple access and maintenance.
### Pollers
## Pollers
Pollers can be installed and run from anywhere, the only requirements are:
@@ -174,7 +174,7 @@ cause issues with a large number of devices.
A last note to make sure of, is that all pollers writing to the same DB
need to have the same `APP_KEY` value set in the `.env` file.
### Discovery
## Discovery
Depending on your setup will depend on how you configure your discovery processes.
@@ -187,13 +187,13 @@ Designate a single poller to run discovery (or a separate server if required).
**Dispatcher service**
When using the dispatcher service, discovery can run on all nodes.
### Configuration
## Configuration
Settings in config.php should be copied to all servers as they only apply locally.
One way around this is to set settings in the database via the web ui or `./lnms config:set`
### Config sample
## Config sample
The following config is taken from a live setup which consists of a
Web server, DB server, RRDCached server and 3 pollers.

4
doc/Extensions/Fast-Ping-Check.md
View File

@@ -80,14 +80,14 @@ $config['ping_rrd_step'] = 30;
* * * * * librenms sleep 45 && /opt/librenms/alerts.php >> /dev/null 2>&1
```
# Device dependencies
## Device dependencies
The ping.php script respects device dependencies, but the main poller
does not (for technical reasons). However, using this script does not
disable the icmp check in the poller and a child may be reported as
down before the parent.
# Settings
## Settings
`ping.php` uses much the same settings as the poller fping with one
exception: retries is used instead of count.

10
doc/Extensions/Graylog.md
View File

@@ -120,13 +120,15 @@ $config['graylog']['loglevel']
```
(applies to /graylog and /device/device=/tab=logs/section=graylog/ (min: 0, max: 7)
# Suppressing/enabling the domain part of a hostname for specific platforms
## Domain and hostname handling
Suppressing/enabling the domain part of a hostname for specific platforms
You should see if what you get in syslog/Graylog matches up with your
configured hosts first. If you need to modify the syslog messages from
specific platforms, this may be of assistance:
## IOS (Cisco)
### IOS (Cisco)
```
router(config)# logging origin-id hostname
@@ -138,13 +140,13 @@ or
router(config)# logging origin-id string
```
## JunOS (Juniper Networks)
### JunOS (Juniper Networks)
```
set system syslog host yourlogserver.corp log-prefix YOUR_PREFERRED_STRING
```
## PanOS (Palo Alto Networks)
### PanOS (Palo Alto Networks)
```
set deviceconfig setting management hostname-type-in-syslog hostname

10
doc/Extensions/IRC-Bot-Extensions.md
View File

@@ -1,7 +1,7 @@
source: Extensions/IRC-Bot-Extensions.md
path: blob/master/doc/
# Quick Guide
# IRC Bot Extensions
Okay this is a very quick walk-through in writing your own `commands` for the IRC-Bot.
@@ -28,11 +28,11 @@ To enable your command, edit your `config.php` and add something like this:
See: [Example](#example)
# Functions and Attributes
## Functions and Attributes
... that are accessible from within an extension
## Functions
### Functions
Function( (Type) $Variable [= Default] [,...] ) | Returns | Description
--- | --- | ---
@@ -47,7 +47,7 @@ Function( (Type) $Variable [= Default] [,...] ) | Returns | Description
`$this->read( (string) $Buffer )` | `String/Boolean` | Returns a `line` from given `$Buffer` or `false` if there's nothing suitable inside the Buffer. Please use `$this->getData()` for handler-safe data retrieval.
`$this->respond( (string) $Message )` | `Boolean` | Responds to the `request` auto-detecting channel or private message.
## Attributes
### Attributes
Attribute | Type | Description
--- | --- | ---
@@ -66,7 +66,7 @@ Attribute | Type | Description
`$this->tick` | `Int` | Interval to check buffers in microseconds.
`$this->user` | `Array` | Array containing details about the `user` that sent the `request`.
# Example
## Example
`includes/ircbot/join-ng.inc.php`

17
doc/Extensions/IRC-Bot.md
View File

@@ -1,8 +1,7 @@
source: Extensions/IRC-Bot.md
path: blob/master/doc/
[TOC]
# About
# IRC Bot
LibreNMS has an easy to use IRC-Interface for basic tasks like viewing
last log-entry, current device/port status and such.
@@ -40,7 +39,7 @@ Option | Default-Value | Notes
`$config['irc_ctcp_version']` | `LibreNMS IRCbot. https://www.librenms.org/` | Optional; Reply-string to CTCP VERSION requests
`$config['irc_auth']` | | Optional; Array of hostmasks that are automatically authenticated.
### IRC-Commands
## IRC-Commands
Command | Description
--- | ---
@@ -59,9 +58,9 @@ Command | Description
( __/!\\__ All commands are case-_insensitive_ but their arguments are case-_sensitive_)
# Examples
## Examples
## Server examples
### Server examples
Unencrypted Connection to `irc.freenode.org`:
@@ -91,7 +90,7 @@ SSL-Encrypted Connection to `irc.localdomain` with Server-Password and odd port:
...
```
## Channel notations
### Channel notations
Channels can be defined using Array-Notation like:
@@ -111,7 +110,7 @@ Or using a single string using `,` as delimiter between various channels:
...
```
## Hostmask authentication
### Hostmask authentication
```php
...
@@ -126,7 +125,7 @@ be authenticated as the "admin" user in LibreNMS, and clients matching
the last line will be authenticated as the user "john" in LibreNMS,
without using .auth and a waiting for a valid token.
# Extensions?!
## Extensions?!
The bot is coded in a unified way.
This makes writing extensions by far less painful.
@@ -161,7 +160,7 @@ File: includes/ircbot/echo.inc.php
}
```
# Systemd start up script
## Systemd start up script
Basic systemd start up script to be placed in /etc/systemd/system/ to
start irc service at boot.

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

@@ -1,13 +1,13 @@
source: Extensions/Interface-Description-Parsing.md
path: blob/master/doc/
# About
# Interface Description Parsing
Librenms can interpret, display and group certain additional information on ports.
This is done based on the format that the port description is written
although it's possible to customise the parser to be specific for your setup.
# Keywords
## Keywords
See [examples](#examples) for formats.
@@ -21,7 +21,7 @@ See [examples](#examples) for formats.
- `{}` contains *your* circuit id
- `[]` contains the service type or speed
# Examples
## Examples
Cisco IOS / NXOS / IOSXR:
@@ -47,7 +47,7 @@ This requires an additional script to be [setup](#setup)
# eth2: Peering: Peering Exchange
```
# Customisation
## Customisation
The following config options can be set to enable more custom types:
@@ -59,7 +59,7 @@ $config['core_descr'][] = "core";
$config['custom_descr'][] = "something_made_up";
```
# Custom interface parser
## Custom interface parser
It's also possible to write your own parser, the existing one is: includes/port-descr-parser.inc.php
@@ -69,7 +69,7 @@ Once you've created your own then you can enable it with:
$config['port_descr_parser'] = "includes/custom/my-port-descr-parser.inc.php";
```
## Setup
### Setup
For Unix / Linux based systems, you need to run an additional script
to support the parsing of interface infor.

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

@@ -24,7 +24,7 @@ for individual devices are available showing the relationship with
other devices. Also you can Build Device Groups and those Device
Groups can be drawn with Network Map.
# Network Map Configurator
## Network Map Configurator
[This link](https://visjs.github.io/vis-network/docs/network/) will
show you all the options and explain what they do.
@@ -39,14 +39,14 @@ $config['network_map_vis_options'] = '{
}';
```
## Note
### Note
You may want to disable the automatic page refresh while you're
tweaking your configuration, as the refresh will reset the dynamic
configuration UI to the values currently saved in config.php This can
be done by clicking on the Settings Icon then Refresh Pause.
## Configurator Output
### Configurator Output
Once you've achieved your desired map appearance, click the generate
options button at the bottom to be given the necessary parameters to

20
doc/Extensions/Oxidized.md
View File

@@ -1,7 +1,7 @@
source: Extensions/Oxidized.md
path: blob/master/doc/
# Oxidized intro
# Oxidized
Integrating LibreNMS with
[Oxidized](https://github.com/ytti/oxidized-web) brings the following
@@ -26,7 +26,7 @@ LibreNMS will automatically map the OS to the Oxidized model name if
they don't match. this means you shouldn't need to use the model_map
config option within Oxidized.
# Detailed integration information
## Detailed integration information
This is a straight forward use of Oxidized, it relies on you having a
working Oxidized setup which is already taking config snapshots for
@@ -62,7 +62,7 @@ You can set a default group that devices will fall back to with:
lnms config:set oxidized.default_group default
```
# SELinux
## SELinux
If you're running SELinux, you'll need to allow httpd to connect
outbound to the network, otherwise Oxidized integration in the web UI
@@ -72,7 +72,7 @@ will silently fail:
setsebool -P httpd_can_network_connect 1
```
# Feeding Oxidized
## Feeding Oxidized
----
@@ -107,7 +107,7 @@ to your config.
lnms config:set oxidized.reload_nodes true
```
# Creating overrides
## Creating overrides
To return an override to Oxidized you can do this by providing the
override key, followed by matching a lookup for a host (or hosts), and
@@ -205,7 +205,7 @@ groups:
password: <password>
```
# Miscellaneous
## Miscellaneous
If you have devices which you do not wish to appear in Oxidized then
you can edit those devices in Device -> Edit -> Misc and enable
@@ -225,7 +225,7 @@ You can also ignore whole groups of devices
lnms config:set oxidized.ignore_groups '["london-switches", "default"]'
```
# Trigger configuration backups
## Trigger configuration backups
Using the Oxidized REST API and [Syslog
Hooks](/Extensions/Syslog/#external-hooks), Oxidized can trigger
@@ -239,7 +239,7 @@ configuration
next_adds_job: true
```
# Validate Oxidized config
## Validate Oxidized config
You can perform basic validation of the Oxidized configuration by
going to the Overview -> Tools -> Oxidized link and in the Oxidized
@@ -249,7 +249,7 @@ click 'Validate YAML'.
We check for yaml syntax errors and also actual config values to
ensure they are used in the correct location.
# Accessing configuration of a disabled/removed device
## Accessing configuration of a disabled/removed device
When you're disabling or removing a device from LibreNMS, the
configuration will no longer be available via the LibreNMS web interface.
@@ -276,7 +276,7 @@ file content:
git cat-file -p <object id>
```
# Remove disabled/removed device
## Remove disabled/removed device
If you want to purge saved config of a device that is not in LibreNMS anymore, you can run the following command:
```

4
doc/Extensions/Proxmox.md
View File

@@ -11,7 +11,7 @@ be added later on.
The ultimate goal is to be able to create traffic bills for VMs, no
matter on which physical machine that VM runs.
# Enabling Proxmox graphs
## Enabling Proxmox graphs
To enable Proxmox graphs, do the following:
@@ -43,7 +43,7 @@ flag for the device you are monitoring. You should now see an
application in LibreNMS, as well as a new menu-item in the topmenu,
allowing you to choose which cluster you want to look at.
# Note, if you want to use use xinetd instead of systemd
## Note, if you want to use use xinetd instead of systemd
Its possible to use the librenms-agent started by xinetd instead of
systemd. One use case is if you are forced to use a old Proxmox

18
doc/Extensions/RRDCached.md
View File

@@ -17,7 +17,7 @@ This setting has to be the exact version of rrdtool you are running.
NOTE: This feature requires your client version of rrdtool to be 1.5.5
or newer, in addition to your rrdcached version.
# Distributed Poller Support Matrix
## Distributed Poller Support Matrix
Shared FS: Is a shared filesystem required?
@@ -41,7 +41,7 @@ It is recommended that you monitor your LibreNMS server with LibreNMS
so you can view the disk I/O usage delta.
# Installation Manual for
## Installation Manual for
1. [RRDCached installation Ubuntu 16](#rrdcached-installation-ubuntu-16)
1. [RRDCached installation Debian Buster](#rrdcached-installation-debian-buster)
@@ -51,7 +51,7 @@ so you can view the disk I/O usage delta.
1. [Securing RRCached](#securing-rrcached)
## RRDCached installation Ubuntu 16
### RRDCached installation Ubuntu 16
1: Install rrdcached
@@ -94,7 +94,7 @@ systemctl restart rrdcached.service
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
## RRDCached installation Debian Buster
### RRDCached installation Debian Buster
(rrdcached 1.7.1)
1: Install rrdcached
@@ -152,7 +152,7 @@ $config['rrdcached'] = "IPADDRESS:42217";
NOTE: change IPADDRESS to the ip the rrdcached server is listening on.
## RRDCached installation Debian Stretch
### RRDCached installation Debian Stretch
(rrdcached 1.6.0)
1: Install rrdcached
@@ -210,7 +210,7 @@ $config['rrdcached'] = "IPADDRESS:42217";
NOTE: change IPADDRESS to the ip the rrdcached server is listening on.
## RRDCached installation CentOS 7 or 8
### RRDCached installation CentOS 7 or 8
1: Create `/etc/systemd/system/rrdcached.service` with this content:
@@ -240,7 +240,7 @@ systemctl enable --now rrdcached.service
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
## RRDCached installation CentOS 6
### RRDCached installation CentOS 6
This example is based on a fresh LibreNMS install, on a minimal CentOS 6 installation.
In this example, we'll use the Repoforge repository.
@@ -280,7 +280,7 @@ service rrdcached start
$config['rrdcached'] = "unix:/run/rrdcached.sock";
```
# Verify
## Verify
Check to see if the graphs are being drawn in LibreNMS. This might take a few minutes.
After at least one poll cycle (5 mins), check the LibreNMS disk I/O performance delta.
@@ -289,7 +289,7 @@ hostname](../Installation/Installation-CentOS-7-Apache.md)>Health>Disk I/O.
Depending on many factors, you should see the Ops/sec drop by ~30-40%.
# Securing RRCached
## Securing RRCached
Please see [RRDCached Security](RRDCached-Security.md)

6
doc/Extensions/Rancid.md
View File

@@ -1,13 +1,13 @@
source: Extensions/Rancid.md
path: blob/master/doc/
# Rancid integration
# Rancid
Librenms can generate a list of hosts that can be monitored by
RANCID. We assume you have currently a running Rancid, and you just
need to create and update the file 'router.db'
# Included Rancid script
## Included Rancid script
To generate the config file (maybe even add a cron to schedule
this). We've assumed a few locations for Rancid, the config file you
@@ -33,7 +33,7 @@ $config['rancid_ignorecomments'] = 0;
After that, you should see some "config" tab on routers that have a rancid update.
# Ubuntu Rancid Install
## Ubuntu Rancid Install
The options shown below also contains the default values.

28
doc/Extensions/Services.md
View File

@@ -1,18 +1,20 @@
source: Extensions/Services.md
path: blob/master/doc/
[TOC]
# Setting up services
# Nagios Plugins - Services
Services within LibreNMS provides the ability to leverage Nagios plugins to
perform additional monitoring outside of SNMP. Services can also be used
in conjunction with your SNMP monitoring for larger monitoring functionality.
## Setting up Services
**Services must be tied to a device to function properly. A good generic
option is to use `localhost`, but it is suggested to attach the check to
the device you are monitoring.**
## Nagios plugins source
### Nagios plugins source
Plugins come from two main sources:
@@ -23,7 +25,7 @@ Note: Plugins will only load if they are prefixed with `check_`.
The `check_` prefix is stripped out when displaying in the "Add Service"
GUI "Type" dropdown list.
## Service Templates
### Service Templates
Service Templates within LibreNMS provides the same ability as Nagios
does with Host Groups. Known as Device Groups in LibreNMS.
@@ -50,7 +52,7 @@ appropriate.
one Device Group to be able to add Service Templates - You can define a
dummy one. The Device Group does not need members to add Service Templates.**
## Service Auto Discovery
### Service Auto Discovery
To automatically create services for devices with available checks.
@@ -60,7 +62,7 @@ You need to enable the discover services within config.php with the following:
$config['discover_services'] = true;
```
## Service Templates Auto Discovery
### Service Templates Auto Discovery
To automatically create services for devices with configured
Service Templates.
@@ -71,7 +73,7 @@ You need to enable the discover services within config.php with the following:
$config['discover_services_templates'] = true;
```
## Setup
### Setup
Service checks are now distributable if you run a distributed
setup. To leverage this, use the `dispatch` service. Alternatively,
@@ -134,7 +136,7 @@ Note that some services (procs, inodes, load and similar) will always
poll the local LibreNMS server it's running on, regardless of which
device you add it to.
## Performance data
### Performance data
By default, the check-services script will collect all performance
data that the Nagios script returns and display each datasource on a
@@ -174,7 +176,7 @@ go together. Example below:
-- snip --
```
## Alerting
### Alerting
Services uses the Nagios Alerting scheme where exit code:
@@ -191,7 +193,7 @@ rule would look like:
%services.service_status = "2"
```
## Debug
### Debug
Change user to librenms for example
@@ -205,7 +207,7 @@ then you can run the following command to help troubleshoot services.
./check-services.php -d
```
## Related Polling / Discovery Options
### Related Polling / Discovery Options
These settings are related and should be investigated and set accordingly.
The below values are not defaults or recommended.
@@ -241,7 +243,7 @@ $config['service_services_workers'] = 16;
$config['service_services_frequency'] = 60;
```
## Service checks polling logic
### Service checks polling logic
Service check is skipped when the associated device is not pingable,
and an appropriate entry is populated in the event log. Service check
@@ -254,7 +256,7 @@ setting (Edit -> Misc) to ON.
Service checks will never be polled on disabled devices.
## CHECK_MRPE
### CHECK_MRPE
In most cases, only Nagios plugins that run against a remote host with the -H option are available as services. However, if you're remote host is running the [Check_MK agent](Agent-Setup.md) you may be able to use MRPE to monitor Nagios plugins that only execute locally as services.

7
doc/Extensions/Supermicro.md
View File

@@ -1,10 +1,11 @@
source: Extensions/Supermicro.md
path: blob/master/doc/
# Introduction
# Supermicro
For some Supermicro information to show up in LibreNMS, you will need to install an agent.
# Supermicro SuperDoctor
## Supermicro SuperDoctor
Install Supermicro SuperDoctor onto the device you want to monitor.
Then add the following to /etc/snmp/snmpd.conf:
@@ -17,4 +18,4 @@ Restart net-snmp:
```bash
service snmpd restart
```
```

48
doc/Extensions/Syslog.md
View File

@@ -1,7 +1,7 @@
source: Extensions/Syslog.md
path: blob/master/doc/
# Setting up syslog support
# 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
@@ -251,7 +251,7 @@ 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`
@@ -263,7 +263,7 @@ 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](../Support/Cleanup-options.md)
# Client configuration
## 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
@@ -273,19 +273,19 @@ 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
@@ -296,7 +296,7 @@ logging trap notifications
logging host <outside interface name> librenms.ip
```
## Cisco IOS
### Cisco IOS
```config
logging trap debugging
@@ -304,13 +304,13 @@ 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
@@ -323,7 +323,7 @@ set system syslog host librenms.ip exclude-hostname
set system syslog time-format
```
## Huawei VRP
### Huawei VRP
```config
info-center loghost librenms.ip
@@ -339,14 +339,14 @@ 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.
@@ -361,14 +361,14 @@ 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).
### Note
#### 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.
@@ -378,7 +378,7 @@ just using this Datagram-Syslog Agent for this example.
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
@@ -392,43 +392,43 @@ 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
### 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
@@ -439,9 +439,9 @@ to the syslog server.
$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

14
doc/Extensions/Varnish.md
View File

@@ -12,17 +12,19 @@ cache it directs the request to the HTTP Server. This type of HTTP
caching is called a reverse proxy server. Caching your HTTP server can
decrease page load times significantly.
# Simplified block diagram of an Apache HTTP server with Varnish 4.0 Reverse Proxy
## Architecture
Simplified block diagram of an Apache HTTP server with Varnish 4.0 Reverse Proxy
![Block Diagram 1](/img/varnish_block.png)
# CentOS 7 Varnish Installation
## CentOS 7 Varnish Installation
In this example we will assume your Apache 2.4.X HTTP server is working and
configured to process HTTP requests on port 80. If not, please see
[Installing LibreNMS](../Installation/Installation-CentOS-7-Apache.md)
# Install Varnish 4.0 RPM
## Install Varnish 4.0 RPM
- Enable the Varnish CentOS 7 repo and install
@@ -39,7 +41,7 @@ By default Varnish listens for HTTP requests on port 6081.
firewall-cmd --zone=public --add-port=6081/tcp
```
# Test Varnish
## Test Varnish
- Start Varnish
@@ -64,7 +66,7 @@ Varnish cache server
```
# Edit Varnish Parameters
## Edit Varnish Parameters
Now we need to configure Varnish to listen to HTTP requests on port 80 and
relay those requests to the Apache HTTP server on port 8080 (see block diagram).
@@ -135,7 +137,7 @@ VARNISH_GROUP=varnish
DAEMON_OPTS="-p thread_pool_min=5 -p thread_pool_max=500 -p thread_pool_timeout=300"
```
# Configure Apache for Varnish
## Configure Apache for Varnish
Edit librenms.conf and modify the Apache Virtual Host listening port.

18
doc/Extensions/Weathermap.md
View File

@@ -12,7 +12,7 @@ Network-WeatherMap requires php pear to work.
## Installing Network-WeatherMap
## Step 1
### Step 1
Extract to your LibreNMS plugins directory `/opt/librenms/html/plugins`
so you should see something like `/opt/librenms/html/plugins/Weathermap/`
@@ -22,7 +22,7 @@ then `/opt/librenms/html/plugins` enter:
git clone https://github.com/librenms-plugins/Weathermap.git
```
## Step 2
### Step 2
Inside the html/plugins directory, change the ownership of the
Weathermap directory by typing `chown -R librenms:librenms Weathermap/`
@@ -39,7 +39,7 @@ Note if you are using SELinux you need to input the following command
chcon -R -t httpd_cache_t Weathermap/
```
## Step 3
### Step 3
Enable the cron process by editing your current LibreNMS cron file
(typically /etc/cron.d/librenms) and add the following:
@@ -48,11 +48,11 @@ Enable the cron process by editing your current LibreNMS cron file
*/5 * * * * librenms /opt/librenms/html/plugins/Weathermap/map-poller.php >> /dev/null 2>&1
```
## Step 4
### Step 4
Enable the plugin from LibreNMS Web UI in OverView -> Plugins -> Plugin Admin menu.
## Step 5
### Step 5
Now you should see Weathermap Overview -> Plugins -> Weathermap
Create your maps, please note when you create a MAP, please click Map
@@ -64,18 +64,18 @@ updates (i.e. use `output/mymap.png` and `output/mymap.html`).
Optional: If your install is in another directory than standard, set
`$basehref` within `map-poller.php`.
# WeatherMapper
## WeatherMapper
Automatically generate weathermaps from a LibreNMS database using [WeatherMapper](https://github.com/pblasquez/weathermapper).
![Example Network Weather Map](/img/network-weather-map.png)
# Adding your Network Weathermaps to the Dashboards
## Adding your Network Weathermaps to the Dashboards
Once you have created your Network Weather Map you can add it to a
dashboard page by doing the following.
## Step 1
### Step 1
When you create the Weathermap make sure to export as HTML and PNG you
will need this for the out to the dashboard.
@@ -85,7 +85,7 @@ click` on one of the maps and click on `copy image address`.
Example URL: `http://yourlibrenms.org/plugins/Weathermap/output/yourmap.html`
## Step 2
### Step 2
Then go back to your Dashboard, create a new dashboard and give it a
name. select the widget as *External Images*.

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

@@ -6,7 +6,7 @@ path: blob/master/doc/
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
@@ -39,7 +39,7 @@ 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.
@@ -53,7 +53,7 @@ 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
@@ -63,7 +63,7 @@ different url you can set:
$config['leaflet']['tile_url'] = 'localhost.com';
```
# Additional Leaflet config
## Additional Leaflet config
```php
$config['map']['engine'] = "leaflet";
@@ -74,7 +74,7 @@ $config['leaflet']['default_zoom'] = 8;
$config['leaflet']['group_radius'] = 1;
```
# Geocode engine config
## Geocode engine config
```php
$config['geoloc']['engine'] = "google"; // Valid options are google, mapquest or bing
@@ -93,7 +93,7 @@ Bing:
Pros: free, no credit card required, accurate
Cons: Microsoft (debatable)
# Jquery-Mapael config
## 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

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

@@ -6,7 +6,7 @@ path: blob/master/doc/
This module sends all metrics to a remote graphite service. You need
something like Grafana for graphing.
# What you don't get
## What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
@@ -14,7 +14,7 @@ something like Grafana for graphing.
RRD will continue to function as normal so LibreNMS itself should
continue to function as normal.
# Configuration
## Configuration
```php
$config['graphite']['enable'] = true;
@@ -32,7 +32,7 @@ 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
## Graphite Configuration
As LibreNMS updates its metrics every 5 minutes, the following
addition to your storage-schemas.conf is suggested.

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

@@ -10,7 +10,7 @@ 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!
# Requirements
## Requirements
- InfluxDB >= 0.94
- Grafana
@@ -19,7 +19,7 @@ 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.
# What you don't get
## What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
@@ -29,7 +29,7 @@ really able to provide any help with this side of things.
RRD will continue to function as normal so LibreNMS itself should
continue to function as normal.
# Configuration
## Configuration
```php
$config['influxdb']['enable'] = true;

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

@@ -6,12 +6,12 @@ path: blob/master/doc/
This module sends all metrics to OpenTSDB server. You need something
like Grafana for graphing.
# Requirements
## Requirements
- OpenTSDB
- Grafana
# What you don't get
## What you don't get
Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
@@ -21,7 +21,7 @@ continue to function normally.
You can add the following to `config.php`.
# Configuration
## Configuration
```php
// OpenTSDB default configuration

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

@@ -8,7 +8,7 @@ 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!
# Requirements (Older versions may work but haven't been tested
## Requirements (Older versions may work but haven't been tested
- Prometheus >= 2.0
- PushGateway >= 0.4.0
@@ -18,7 +18,7 @@ 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.
# What you don't get
## What you don't get
- Pretty graphs, this is why at present you need Grafana. You need to
build your own graphs within Grafana.
@@ -28,7 +28,7 @@ really able to provide any help with this side of things.
RRD will continue to function as normal so LibreNMS itself should
continue to function as normal.
# Configuration
## Configuration
```php
$config['prometheus']['enable'] = true;
@@ -36,7 +36,7 @@ $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

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

@@ -1,7 +1,7 @@
source: Support/1-Minute-Polling.md
path: blob/master/doc/
# Information
# 1-Minute Polling
We now have support for polling data at intervals to fit your needs.
@@ -35,7 +35,7 @@ for step and heartbeat intervals:
- 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

8
doc/Support/Bare-Dashboard.md
View File

@@ -1,12 +1,16 @@
source: Support/Bare-Dashboard.md
path: blob/master/doc/
# Hide Menubar
# Bare Dashboard
Settings to assist with wall/monitor displays.
## Hide Menubar
To hide Menubar e.g. for Monitoring TV Screens
attach `?bare=yes` on URL
# No Search Fields in Dashboard Widgets
## No Search Fields in Dashboard Widgets
To hide Search Field in Dashboard Widgets take a look into
Widget Settings.

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

@@ -32,7 +32,7 @@ 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.

98
doc/Support/Configuration.md
View File

@@ -1,6 +1,8 @@
source: Support/Configuration.md
path: blob/master/doc/
# Configuration Docs
LibreNMS configuration is a set of key values.
The config is stored in two places:
@@ -21,13 +23,13 @@ The LibreNMS uses dot notation for config items:
> option. Without that option input is checked for correctness, that does not
> mean it is not possible to set bad values. Please report missing settings.
# CLI
## CLI
`lnms config:get` will fetch the current config settings (composite of database, config.php, and defaults).
`lnms config:set` will set the config setting in the database. Calling `lnms config:set` on a setting with no value will reset it to the default value.
If you set up bash completion, you can use tab completion to find config settings.
## Examples
### Examples
```bash
lnms config:get snmp.community
@@ -73,7 +75,7 @@ lnms config:get snmp.community --json
```
# Directories
## Directories
```php
$config['temp_dir'] = "/tmp";
@@ -88,7 +90,7 @@ $config['log_dir'] = "/opt/librenms/logs";
Log files created by LibreNMS will be stored within this directory.
# Database config
## Database config
Set these variables either in .env or in the environment.
@@ -111,22 +113,22 @@ Use a unix socket:
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:
`$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.
### RRDTool
#### RRDTool
> You can configure these options within the WebUI now, please avoid
> setting these options within config.php
@@ -140,7 +142,7 @@ $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.
### fping
#### fping
```php
$config['fping'] = "/usr/bin/fping";
@@ -190,7 +192,7 @@ $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
### traceroute
#### traceroute
LibreNMS uses traceroute / traceroute6 to record debug information
when a device is down due to icmp AND you have
@@ -201,7 +203,7 @@ $config['traceroute'] = '/usr/bin/traceroute';
$config['traceroute6'] = '/usr/bin/traceroute6';
```
### SNMP
#### SNMP
```php
$config['snmpwalk'] = "/usr/bin/snmpwalk";
@@ -225,7 +227,7 @@ $config['neato'] = "/usr/bin/neato";
$config['sfdp'] = "/usr/bin/sfdp";
```
# Authentication
## Authentication
Generic Authentication settings.
@@ -233,7 +235,7 @@ 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:
@@ -250,11 +252,11 @@ http_proxy=proxy.domain.com
https_proxy=proxy.domain.com
```
# RRDCached
## RRDCached
Please refer to [RRDCached](../Extensions/RRDCached.md)
# WebUI Settings
## WebUI Settings
```php
$config['base_url'] = "http://demo.librenms.org";
@@ -500,7 +502,7 @@ can disable this with the following config:
$config['allow_duplicate_sysName'] = false;
```
# Global poller and discovery modules
## Global poller and discovery modules
Generally, it is a better to set these [per
OS](../Developing/os/Settings.md#poller-and-discovery-modules) or
@@ -511,7 +513,7 @@ $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.
@@ -548,11 +550,11 @@ $config['snmp']['v3'][0]['cryptopass'] = ""; # Privacy (Encryption)
$config['snmp']['v3'][0]['cryptoalgo'] = "AES"; # AES | DES
```
# Auto discovery settings
## Auto discovery settings
Please refer to [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
@@ -575,15 +577,15 @@ 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
Please refer to [Alerting](../Alerting/index.md)
# Billing
## Billing
Please refer to [Billing](../Extensions/Billing-Module.md)
# Global module support
## Global module support
```php
$config['enable_bgp'] = 1; # Enable BGP session collection and display
@@ -594,7 +596,7 @@ $config['enable_vrfs'] = 1; # Enable VRFs
$config['enable_sla'] = 0; # Enable Cisco SLA collection and display
```
# Port extensions
## Port extensions
Please refer to [Port-Description-Parser](../Extensions/Port-Description-Parser.md)
@@ -607,9 +609,9 @@ $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/';
@@ -621,11 +623,11 @@ 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
Please refer to [Oxidized](../Extensions/Oxidized.md)
## CollectD
### CollectD
```php
$config['collectd_dir'] = '/var/lib/collectd/rrd';
@@ -666,15 +668,15 @@ 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
Please refer to [Smokeping](../Extensions/Smokeping.md)
## NFSen
### NFSen
Please refer to [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
@@ -706,7 +708,7 @@ 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.
# Interfaces to be ignored
## Interfaces to be ignored
Interfaces can be automatically ignored during discovery by modifying
bad_if\* entries in a default array, unsetting a default array and
@@ -753,7 +755,7 @@ $config['os']['iosxe']['bad_iftype'][] = "macSecUncontrolledIF";
`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:
@@ -767,7 +769,7 @@ 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';
@@ -778,7 +780,7 @@ 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
@@ -790,7 +792,7 @@ $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
@@ -803,7 +805,7 @@ these are not provided by the vendor, the guess method can be disabled:
$config['sensors']['guess_limits'] = false;
```
# Ignoring Health Sensors
## Ignoring Health Sensors
It is possible to filter some sensors from the configuration:
@@ -831,7 +833,7 @@ $config['os']['vrp']['disabled_sensors']['current'] = true;
$config['os']['iosxe']['disabled_sensors_regex'][] = '/PEM Iout/';
```
# Storage configuration
## Storage configuration
Mounted storage / mount points to ignore in discovery and polling.
@@ -870,15 +872,15 @@ $config['storage_perc_warn'] = 60;
$config['os']['linux']['storage_perc_warn'] = 60;
```
# IRC Bot
## IRC Bot
Please refer to [IRC Bot](../Extensions/IRC-Bot.md)
# Authentication
## Authentication
Please refer to [Authentication](../Extensions/Authentication.md)
# Cleanup options
## Cleanup options
These options rely on daily.sh running from cron as per the installation instructions.
@@ -900,11 +902,11 @@ automatically purged. You can alter these individually. values are in days.
> directory automatically - only enable this if you are comfortable
> with that happening.
# Syslog options
## Syslog options
Please refer to [Syslog](../Extensions/Syslog.md)
# Virtualization
## Virtualization
```php
$config['enable_libvirt'] = 1;
@@ -927,7 +929,7 @@ to indicate how you connect to libvirt. You also need to:
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";
@@ -935,11 +937,11 @@ $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
Please refer to [Updating](../General/Updating.md)
# IPMI
## 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.
@@ -952,13 +954,13 @@ $config['ipmi']['type'][] = "imb";
$config['ipmi']['type'][] = "open";
```
# Distributed poller settings
## Distributed poller settings
Please refer to [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>