LibreNMS

https://github.com/librenms/librenms
Admin
LibreNMS is an auto-discovering PHP/MySQL/SNMP based network monitoring system that provides...
Tokens:1,258,687
Snippets:8,493
Trust Score:9
License:GPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example SMART configuration file

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/SMART.md

Example configuration file for the SMART script. Lines starting with # are comments, variables are set as $variable=$value, and lines without a variable or comment are treated as disks.

```bash
#This is a comment
cache=/var/cache/smart
smartctl=/usr/bin/env smartctl
useSN=1
ada0
ada1
da5 /dev/da5 -d sat
twl0,0 /dev/twl0 -d 3ware,0
twl0,1 /dev/twl0 -d 3ware,1
twl0,2 /dev/twl0 -d 3ware,2
```

--------------------------------

### Example bind.config configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/BIND9 aka named.md

Example configuration file for the bind script. Lines starting with # are comments, variables are set as $variable=$value, and empty lines are ignored. The config file path defaults to the script path with .config appended, or can be specified with -c $file.

```text
rndc = The path to rndc. Default: /usr/bin/env rndc
call_rndc = A 0/1 boolean on whether or not to call rndc stats.
    Suggest to set to 0 if using netdata. Default: 1
stats_file = The path to the named stats file. Default: /var/cache/bind/stats
agent = A 0/1 boolean for if this is being used as a LibreNMS
    agent or not. Default: 0
zero_stats = A 0/1 boolean for if the stats file should be zeroed
    first. Default: 0 (1 if guessed)
```

--------------------------------

### Copy snmpd configuration example

Source: https://github.com/librenms/librenms/blob/master/doc/Installation/Install-LibreNMS.md

Copy the provided snmpd.conf.example to /etc/snmp/snmpd.conf as the starting point for SNMP v2c configuration.

```bash
cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
```

--------------------------------

### Multi repo configuration example

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/BorgBackup.md

Example multi-repo configuration with separate sections for each repo.

```bash
mode=multi

[borg1]
repo=/backup/borg1
passphrase=foobar

[derp]
repo=/backup/derp
passcommand=pass show backup
```

--------------------------------

### Setup cron for suricata_stat_check

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Suricata.md

Example cron entry to run suricata_stat_check every 5 minutes. Adjust the path if needed.

```cron
*/5 * * * * /usr/local/bin/suricata_stat_check > /dev/null
```

--------------------------------

### Download example rpigpiomonitor.ini

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Raspberry Pi GPIO Monitor.md

Optionally downloads the example configuration file rpigpiomonitor.ini to /etc/snmp/.

```bash
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/rpigpiomonitor.ini
-O /etc/snmp/rpigpiomonitor.ini
```

--------------------------------

### Start MariaDB client

Source: https://github.com/librenms/librenms/blob/master/doc/Installation/Install-LibreNMS.md

Start the MariaDB client as root to create the database and user.

```bash
mysql -u root
```

--------------------------------

### Start Varnish service

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Varnish.md

Start the Varnish service using systemctl.

```bash
systemctl start varnish
```

--------------------------------

### Install prerequisites on FreeBSD

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/ISC DHCP Stats.md

Install prerequisites on FreeBSD using pkg and then install the Net::ISC::DHCPd::Leases module via cpanm.

```bash
pkg install p5-JSON p5-MIME-Base64 p5-App-cpanminus p5-File-Slurp
cpanm Net::ISC::DHCPd::Leases
```

--------------------------------

### Example logsize.conf configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Logsize.md

Example configuration for /usr/local/etc/logsize.conf defining sets of directories to monitor.

```conf
# monitor log sizes of logs directly under /var/log
[sets.var_log]
dir="/var/log/"

# monitor remote logs from network devices
[sets.remote_network]
dir="/var/log/remote/network/"

# monitor remote logs from windows sources
[sets.remote_windows]
dir="/var/log/remote/windows/"

# monitor suricata flows logs sizes
[sets.suricata_flows]
dir="/var/log/suricata/flows/current"
```

--------------------------------

### Unix / Linux interface description examples

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Interface-Description-Parsing.md

Shows the format for interface descriptions on Unix/Linux systems, using comments in the format '# interface: description'. Requires an additional script to be set up as described in the Device Setup section.

```text
# eth3: Cust: Example Customer [10Mbit] (T1 Telco Y CCID129031) {EXAMP0001}
# eth0: Transit: Example Provider (AS65000)
# eth1: Core: core.router01 FastEthernet0/0 (Telco X CCID023141)
# eth2: Peering: Peering Exchange
```

--------------------------------

### Single repo configuration example

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/BorgBackup.md

Example single-repo configuration with repo path and passphrase.

```bash
repo=/backup/borg
repo=1234abc
```

--------------------------------

### Install prerequisites on FreeBSD

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/SMART.md

Install smartmontools and required Perl modules on FreeBSD systems.

```bash
pkg install p5-JSON p5-MIME-Base64 smartmontools
```

--------------------------------

### Start Galera Cluster for the First Time

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Galera-Cluster.md

Steps to start the Galera cluster for the first time: stop MariaDB on all nodes, run galera_new_cluster on the node with existing data (or any node if starting fresh), then start the remaining nodes normally.

```bash
sudo systemctl stop mariadb-server
```

```bash
sudo galera_new_cluster
```

```bash
sudo systemctl start mariadb-server
```

--------------------------------

### Install prerequisites generically

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/ISC DHCP Stats.md

Generic installation of required Perl modules using cpanm.

```bash
cpanm Net::ISC::DHCPd::Leases MIME::Base64 File::Slurp
```

--------------------------------

### Install librenms_return_optimizer on FreeBSD

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications.md

Install the required Perl modules and download the optimizer script on FreeBSD.

```bash
pkg install p5-MIME-Base64 p5-Gzip-Faster wget
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/utils/librenms_return_optimizer -O /usr/local/bin/librenms_return_optimizer
chmod +x /usr/local/bin/librenms_return_optimizer
```

--------------------------------

### Install LibreNMS Dispatcher Service

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Dispatcher-Service.md

Installs the provided systemd unit file and enables/starts the LibreNMS dispatcher service. Update ExecStart and WorkingDirectory in the unit file if LibreNMS is not installed in /opt/librenms.

```bash
cp /opt/librenms/misc/librenms.service /etc/systemd/system/librenms.service && systemctl enable --now librenms.service
```

--------------------------------

### Install librenms_return_optimizer on CentOS/RedHat

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications.md

Install the required Perl modules and download the optimizer script on CentOS/RedHat.

```bash
yum install zlib-devel perl-CPAN wget
cpan Gzip::Faster
cpan MIME::Base64
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/utils/librenms_return_optimizer -O /usr/local/bin/librenms_return_optimizer
chmod +x /usr/local/bin/librenms_return_optimizer
```

--------------------------------

### Install Composer and Run Code Validation

Source: https://github.com/librenms/librenms/blob/master/doc/Developing/Validating-Code.md

Install Composer, install dependencies, and run the code validation script. The output 'Tests ok, submit away :)' indicates the code is correct.

```bash
curl -sS https://getcomposer.org/installer | php
```

```bash
./composer.phar install
```

```bash
./lnms dev:check
```

--------------------------------

### Install prerequisites on Debian/Ubuntu

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/SMART.md

Install smartmontools and required Perl modules on Debian or Ubuntu systems.

```bash
apt-get install smartmontools libjson-perl libmime-base64-perl
```

--------------------------------

### Start Kafka with Docker

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/metrics/Kafka.md

Start a Kafka instance using Docker Compose with the specified environment variables.

```bash
# Start Kafka with Docker Compose
docker run -d \
  --name kafka \
  -p 9092:9092 \
  -e KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181 \
  -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 \
  -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 \
  confluentinc/cp-kafka:latest
```

--------------------------------

### Start srvadmin services

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Dell-OpenManage.md

Start the Dell OpenManage srvadmin services. This command usually starts them.

```bash
/opt/dell/srvadmin/sbin/srvadmin-services.sh start
```

--------------------------------

### Install prerequisites on RedHat/CentOS

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/SMART.md

Install smartmontools and required Perl modules on RedHat or CentOS systems.

```bash
dnf install smartmontools perl-JSON perl-MIME-Base64
```

--------------------------------

### Arch Linux SNMPv2 setup

Source: https://github.com/librenms/librenms/blob/master/doc/Support/SNMP-Configuration-Examples.md

Steps to configure SNMPv2 on Arch Linux: install net-snmp, create the /etc/snmp/ folder, set the community, contact, and location, then enable and start the service.

```bash
pacman -S net-snmp
```

```bash
mkdir /etc/snmp/
```

```bash
echo rocommunity read_only_community_string >> /etc/snmp/snmpd.conf
```

```bash
echo syscontact Firstname Lastname >> /etc/snmp/snmpd.conf
```

```bash
echo syslocation L69 4RX >> /etc/snmp/snmpd.conf
```

```bash
systemctl enable snmpd.service
```

```bash
systemctl restart snmpd.service
```

--------------------------------

### Install librenms_return_optimizer on Debian/Ubuntu

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications.md

Install the required Perl modules and download the optimizer script on Debian/Ubuntu.

```bash
apt-get install zlib1g-dev cpanminus wget
cpanm Gzip::Faster
cpanm MIME::Base64
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/utils/librenms_return_optimizer -O /usr/local/bin/librenms_return_optimizer
chmod +x /usr/local/bin/librenms_return_optimizer
```

--------------------------------

### Compile and install SELinux policy module

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Compile and install the SELinux policy module as root.

```ssh
checkmodule -M -m -o mycustom-librenms-rsyslog.mod mycustom-librenms-rsyslog.te
semodule_package -o mycustom-librenms-rsyslog.pp -m mycustom-librenms-rsyslog.mod
semodule -i mycustom-librenms-rsyslog.pp
```

--------------------------------

### Install prerequisites for Sagan monitoring

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Sagan.md

Install prerequisites for Sagan monitoring on Debian/Ubuntu, FreeBSD, or generic systems. Each command installs required Perl modules and then installs Sagan::Monitoring via cpanm.

```bash
apt-get install libjson-perl libfile-readbackwards-perl libfile-slurp-perl libmime-base64-perl cpanminus
cpanm Sagan::Monitoring
```

```bash
pkg install p5-JSON p5-File-ReadBackwards p5-File-Slurp p5-MIME-Base64 p5-Time-Piece p5-App-cpanminus
cpanm Sagan::Monitoring
```

```bash
cpanm Sagan::Monitoring
```

--------------------------------

### Install logstash-output-exec plugin

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Installs the logstash-output-exec plugin required for the local Logstash setup.

```bash
/usr/share/logstash/bin/logstash-plugin install logstash-output-exec
```

--------------------------------

### Install BorgBackup dependencies on FreeBSD

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/BorgBackup.md

Installs Perl dependencies on FreeBSD.

```bash
pkg install p5-Config-Tiny p5-JSON p5-File-Slurp p5-MIME-Base64 p5-String-ShellQuote
```

--------------------------------

### Get VRF response JSON

Source: https://github.com/librenms/librenms/blob/master/doc/API/Routing.md

Example JSON response from the get VRF endpoint. Shows the structure of a single vrf object.

```json
{
    "status": "ok",
    "vrf": [
        {
            "vrf_id": "2",
            "vrf_oid": "8.77.103.109.116.45.118.114.102",
            "vrf_name": "Mgmt-vrf",
            "mplsVpnVrfRouteDistinguisher": "",
            "mplsVpnVrfDescription": "",
            "device_id": "8"
        }
    ],
    "count": 1
}
```

--------------------------------

### Run new-os.php helper script

Source: https://github.com/librenms/librenms/blob/master/doc/Developing/Support-New-OS.md

Run the interactive helper script to create basic OS definitions from an existing device. The script is in pre-beta and adds basic sensors but not state sensors.

```bash
./scripts/new-os.php -h 101 -o test-os -t network -v cisco
```

--------------------------------

### Install and configure rrdcached on CentOS 6

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/RRDCached.md

Install and configure rrdcached on CentOS 6 using the Repoforge repository. Steps include installing the repo, enabling the Extra repo, updating rrdtool, editing /etc/sysconfig/rrdcached, creating directories, enabling the service, and starting it.

```bash
rpm -ivh http://pkgs.repoforge.org/rpmforge-release/rpmforge-release-0.5.3-1.el6.rf.x86_64.rpm
```

```bash
vi /etc/yum.repos.d/rpmforge.repo
```

```bash
yum update rrdtool
```

```bash
vi /etc/yum.repos.d/rpmforge.repo
```

```bash
# Settings for rrdcached
OPTIONS="-w 1800 -z 1800 -f 3600 -s librenms -U librenms -G librenms -B -R -j /var/tmp -l unix:/run/rrdcached.sock -t 4 -F -b /opt/librenms/rrd/"
RRDC_USER=librenms
```

```bash
mkdir /var/run/rrdcached
chown librenms:librenms /var/run/rrdcached/
chown librenms:librenms /var/rrdtool/
chown librenms:librenms /var/rrdtool/rrdcached/
```

```bash
chkconfig rrdcached on
```

```bash
service rrdcached start
```

--------------------------------

### Install SAML2 plugin

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/OAuth-SAML.md

Installs the SAML2 socialite provider plugin for LibreNMS.

```bash
lnms plugin:add socialiteproviders/saml2
```

--------------------------------

### Install prerequisites on FreeBSD

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/NFS.md

Install required Perl modules using pkg on FreeBSD systems.

```bash
pkg install p5-JSON p5-File-Slurp p5-MIME-Base64
```

--------------------------------

### Get all port security information (JSON output)

Source: https://github.com/librenms/librenms/blob/master/doc/API/PortSecurity.md

Example JSON response from the get_all_port_security endpoint.

```json
{
  "status": "ok",
  "message": "",
  "ports": [
        {
          "id": "1",
          "port_id": "1",
          "device_id": "1",
          "cpsIfPortSecurityEnable": "true",
          "cpsIfPortSecurityStatus": "secureup",
          "cpsIfMaxSecureMacAddr": 2,
          "cpsIfCurrentSecureMacAddrCount": 2,
          "cpsIfViolationAction": "dropNotify",
          "cpsIfViolationCount": 0,
          "cpsIfSecureLastMacAddress": "0:1e:f7:c3:50:6",
          "cpsIfStickyEnable": "false"
        },
        {
          "id": "2",
          "port_id": "2",
          "device_id": "1",
          "cpsIfPortSecurityEnable": "true",
          "cpsIfPortSecurityStatus": "secureup",
          "cpsIfMaxSecureMacAddr": "2",
          "cpsIfCurrentSecureMacAddrCount": "2",
          "cpsIfViolationAction": "dropNotify",
          "cpsIfViolationCount": "0",
          "cpsIfSecureLastMacAddress": "0:1e:f7:c3:50:6",
          "cpsIfStickyEnable": "false"
        },
        ...
        {
          "id": "100",
          "port_id": "130",
          "device_id": "5",
          "cpsIfPortSecurityEnable": "true",
          "cpsIfPortSecurityStatus": "securedown",
          "cpsIfMaxSecureMacAddr": "5",
          "cpsIfCurrentSecureMacAddrCount": "2",
          "cpsIfViolationAction": "shutdown",
          "cpsIfViolationCount": "10",
          "cpsIfSecureLastMacAddress": "0:1e:f7:c3:50:6",
          "cpsIfStickyEnable": "false"
        },
    ]
}
```

--------------------------------

### Example varnish.params configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Varnish.md

Example varnish.params file with all common settings, including VCL location, listen address/port, admin interface, storage, TTL, user/group, and daemon options.

```vcl
# Set this to 1 to make systemd reload try to switch vcl without restart.
RELOAD_VCL=1

# Main configuration file. You probably want to change it.
VARNISH_VCL_CONF=/etc/varnish/librenms.vcl

# Default address and port to bind to. Blank address means all IPv4
# and IPv6 interfaces, otherwise specify a host name, an IPv4 dotted
# quad, or an IPv6 address in brackets.
VARNISH_LISTEN_ADDRESS=192.168.1.10
VARNISH_LISTEN_PORT=80

# Admin interface listen address and port
VARNISH_ADMIN_LISTEN_ADDRESS=127.0.0.1
VARNISH_ADMIN_LISTEN_PORT=6082

# Shared secret file for admin interface
VARNISH_SECRET_FILE=/etc/varnish/secret

# Backend storage specification, see Storage Types in the varnishd(5)
# man page for details.
VARNISH_STORAGE="malloc,512M"

# Default TTL used when the backend does not specify one
VARNISH_TTL=120

# User and group for the varnishd worker processes
VARNISH_USER=varnish
VARNISH_GROUP=varnish

# Other options, see the man page varnishd(1)
DAEMON_OPTS="-p thread_pool_min=5 -p thread_pool_max=500 -p thread_pool_timeout=300"
```

--------------------------------

### Get port security by port ID (JSON output)

Source: https://github.com/librenms/librenms/blob/master/doc/API/PortSecurity.md

Example JSON response from the get_port_security_by_port endpoint.

```json
{
  "status": "ok",
  "message": "",
  "ports": [
         {
          "id": "1",
          "port_id": "1",
          "device_id": "1",
          "cpsIfPortSecurityEnable": "true",
          "cpsIfPortSecurityStatus": "secureup",
          "cpsIfMaxSecureMacAddr": 2,
          "cpsIfCurrentSecureMacAddrCount": 2,
          "cpsIfViolationAction": "dropNotify",
          "cpsIfViolationCount": 0,
          "cpsIfSecureLastMacAddress": "0:1e:f7:c3:50:6",
          "cpsIfStickyEnable": "false"
        },
        {
          "id": "2",
          "port_id": "2",
          "device_id": "1",
          "cpsIfPortSecurityEnable": "true",
          "cpsIfPortSecurityStatus": "secureup",
          "cpsIfMaxSecureMacAddr": "2",
          "cpsIfCurrentSecureMacAddrCount": "2",
          "cpsIfViolationAction": "dropNotify",
          "cpsIfViolationCount": "0",
          "cpsIfSecureLastMacAddress": "0:1e:f7:c3:50:6",
          "cpsIfStickyEnable": "false"
        },
        ...
        {
          "id": "100",
          "port_id": "130",
          "device_id": "5",
          "cpsIfPortSecurityEnable": "true",
          "cpsIfPortSecurityStatus": "securedown",
          "cpsIfMaxSecureMacAddr": "5",
          "cpsIfCurrentSecureMacAddrCount": "2",
          "cpsIfViolationAction": "shutdown",
          "cpsIfViolationCount": "10",
          "cpsIfSecureLastMacAddress": "0:1e:f7:c3:50:6",
          "cpsIfStickyEnable": "false"
        },
    ]
}
```

--------------------------------

### Install Sneck prerequisites on FreeBSD

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Sneck.md

Installs Sneck prerequisites on FreeBSD using pkg and cpanm.

```bash
pkg install p5-JSON p5-File-Slurp p5-MIME-Base64 p5-App-cpanminus
cpanm Monitoring::Sneck
```

--------------------------------

### Install libpve-apiclient-perl

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Proxmox.md

Install the Perl API client for Proxmox on Debian/Ubuntu systems.

```bash
apt install libpve-apiclient-perl
```

--------------------------------

### Complete SSO configuration example

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Authentication.md

Complete configuration example for a Shibboleth relying party injecting environment variables with the IDP supplying a list of groups.

```php
lnms config:set auth_mechanism sso
lnms config:set sso.auth_logout_handler '/Shibboleth.sso/Logout'
lnms config:set sso.mode env
lnms config:set sso.create_users true
lnms config:set sso.update_users true
lnms config:set sso.realname_attr displayName
lnms config:set sso.email_attr mail
lnms config:set sso.group_strategy map
lnms config:set sso.group_attr member
lnms config:set sso.group_filter '/(librenms-.*)/i'
lnms config:set sso.group_delimiter ';'
lnms config:set sso.group_level_map '{"librenms-admins": 10, "librenms-readers": 1, "librenms-billingcontacts": 5}'
```

--------------------------------

### Install and configure rrdcached on Red Hat/CentOS 8

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/RRDCached.md

Set up rrdcached on Red Hat/CentOS 8: link the service file, compile and install the SELinux policy module, then enable and start the service. The SELinux policy process generates intermediate files like rrdcached_librenms.mod and rrdcached_librenms.pp that can be removed after installation.

```bash
ln -s /opt/librenms/dist/rrdcached/rrdcached.service /etc/systemd/system/
systemctl daemon-reload
```

```bash
checkmodule -M -m -o /tmp/rrdcached_librenms.mod /opt/librenms/dist/rrdcached/rrdcached_librenms.te
```

```bash
semodule_package -o /tmp/rrdcached_librenms.pp -m /tmp/rrdcached_librenms.mod
```

```bash
semodule -i /tmp/rrdcached_librenms.pp
```

```bash
systemctl enable --now rrdcached.service
```

--------------------------------

### Install Munin agent script and prepare directory

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Munin.md

Install the Munin agent script, make it executable, and create the munin scripts directory. Run these commands in order on the agent host.

```bash
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/agent-local/munin -O /usr/lib/check_mk_agent/local/munin
```

```bash
chmod +x /usr/lib/check_mk_agent/local/munin
```

```bash
mkdir -p /usr/share/munin/munin-scripts
```

--------------------------------

### SNMP query against snmpsim

Source: https://github.com/librenms/librenms/blob/master/doc/Developing/os/Test-Units.md

Example SNMP GET query using the community string and host from the snmpsim simulation.

```bash
snmpget -v 2c -c ios_c3560e 127.1.6.1:1161 sysDescr.0
```

--------------------------------

### wlInterfaces.txt example

Source: https://github.com/librenms/librenms/blob/master/doc/Support/Device-Notes/AsuswrtMerlin.md

Maps each wireless interface to its display name in LibreNMS. Edit this file to match your hardware.

```text
wlan0,wl-2.4G
wlan1,wl-5.0G
```

--------------------------------

### Serve LibreNMS documentation locally with mkdocs

Source: https://github.com/librenms/librenms/blob/master/doc/Developing/Creating-Documentation.md

Run the mkdocs serve command to start a local web server for viewing the documentation. The server builds the docs and updates them on changes.

```bash
$ mkdocs serve
INFO    -  Building documentation...
<..>
INFO    -  Documentation built in 12.54 seconds
<..>
INFO    -  Serving on http://127.0.0.1:8000
<..>
INFO    -  Start watching changes

```

--------------------------------

### Install prerequisites on Debian/Ubuntu

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/NFS.md

Install required Perl modules using apt-get on Debian/Ubuntu systems.

```bash
apt-get install libjson-perl libfile-slurp-perl libmime-base64-perl
```

--------------------------------

### Get auth.socialite configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/OAuth-SAML.md

Read the current configuration values for the auth.socialite settings. Use this to verify the listener and other settings if the setup fails.

```bash
lnms config:get auth.socialite
```

--------------------------------

### Install Sneck prerequisites on Debian/Ubuntu

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Sneck.md

Installs Sneck prerequisites on Debian/Ubuntu using apt-get and cpanm.

```bash
apt-get install cpanminus libjson-perl libfile-slurp-perl libmime-base64-perl
cpanm Monitoring::Sneck
```

--------------------------------

### syslog client configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Example configuration for syslog client to send all logs to LibreNMS. Replace librenms.ip with the IP or hostname of your LibreNMS install.

```config
*.*     @librenms.ip
```

--------------------------------

### Install distro binary

Source: https://github.com/librenms/librenms/blob/master/doc/Support/SNMP-Configuration-Examples.md

Copy the /usr/bin/distro binary from the original source repository and make it executable.

```bash
curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
chmod +x /usr/bin/distro
```

--------------------------------

### Install Apache on Version 9.X

Source: https://github.com/librenms/librenms/blob/master/doc/Installation/Install-LibreNMS.md

Installs the Apache HTTP server on Rocky/Alma/Oracle Linux 9.X.

```bash
dnf -y install httpd
```

--------------------------------

### Setup cron for sagan_stat_check

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Sagan.md

Example cron entry to run sagan_stat_check every 5 minutes. Redirects output to /dev/null to suppress logs.

```bash
*/5 * * * * /usr/local/bin/sagan_stat_check > /dev/null
```

--------------------------------

### device:discover command help

Source: https://github.com/librenms/librenms/blob/master/doc/Support/Discovery Support.md

Command help output for device:discover. Shows usage, arguments, and options.

```bash
Description:
  Discover information about existing devices, defines what will be polled

Usage:
  device:discover [options] [--] <device spec>

Arguments:
  device spec            Device spec to discover: device_id, hostname, wildcard (*), odd, even, all

Options:
  -m, --module=MODULE   Specify module(s) to be run. submodules may be added with /.  Multiple values allowed. (multiple values allowed)
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet           Only errors are displayed. All other output is suppressed
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --env[=ENV]       The environment the command should run under
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
```

--------------------------------

### Install SmokePing cron script on Ubuntu/Debian

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Smokeping.md

Copies the example cron script to /etc/cron.hourly and makes it executable. The script updates the SmokePing configuration file.

```bash
sudo cp /opt/librenms/misc/smokeping-debian.example /etc/cron.hourly/librenms-smokeping
sudo chmod +x /etc/cron.hourly/librenms-smokeping
```

--------------------------------

### Install SmokePing cron script on RHEL/CentOS

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Smokeping.md

Copies the example cron script to /etc/cron.hourly and makes it executable. The script updates the SmokePing configuration file.

```bash
sudo cp /opt/librenms/misc/smokeping-rhel.example /etc/cron.hourly/librenms-smokeping
sudo chmod +x /etc/cron.hourly/librenms-smokeping
```

--------------------------------

### Configure Kafka with SSL example

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/metrics/Kafka.md

Example configuration for Kafka with SSL enabled, including broker list, idempotence, topic, device fields exclusion, and SSL settings.

```bash
lnms config:set kafka.enable true
lnms config:set kafka.broker.list 'kafka:9092'
lnms config:set kafka.idempotence true
lnms config:set kafka.topic 'librenms'
lmns config:set kafka.device-fields-exclude "device_id,ip"
lnms config:set kafka.ssl.enable true
lnms config:set kafka.ssl.protocol 'ssl'
lnms config:set kafka.ssl.ca.location '/etc/kafka/secrets/ca-cert'
lnms config:set kafka.ssl.keystore.location '/etc/kafka/secrets/keystore.jks'
lnms config:set kafka.ssl.keystore.password 'pass'
lnms config:set kafka.flush.timeout 1000
```

--------------------------------

### HPE/Aruba Procurve syslog configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Example configuration for HPE/Aruba Procurve to send syslog to LibreNMS. Replace librenms.ip with the IP or hostname of your LibreNMS install.

```config
configure
logging severity warning
logging facility local6
logging librenms.ip control-descr "LibreNMS"
logging notify running-config-change
write memory
```

--------------------------------

### Example log file listing

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/HTTP Access Log Combined.md

Shows example log files in a directory to illustrate auto mode.

```text
foo:80-access.log
foo:80-error.log
foo:443-access.log
foo:443-error.log
bar-access.log
```

--------------------------------

### LibreNMS snmpd.conf example path

Source: https://github.com/librenms/librenms/blob/master/doc/Support/SNMP-Configuration-Examples.md

The LibreNMS server holds a copy of the snmpd.conf example at this path.

```bash
/opt/librenms/snmpd.conf.example
```

--------------------------------

### Cisco NXOS syslog configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Example configuration for Cisco NXOS to send syslog to LibreNMS. Replace librenms.ip with the IP or hostname of your LibreNMS install.

```config
logging server librenms.ip 5 use-vrf default facility local6
```

--------------------------------

### Install System Dependencies for Kafka Testing

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/metrics/Kafka.md

Install the required system packages for Kafka testing on Ubuntu/Debian.

```bash
# On Ubuntu/Debian
sudo apt update
sudo apt install librdkafka-dev libffi-dev
```

--------------------------------

### Run rancid-cvs to initialize

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Rancid.md

Run the rancid-cvs command to set up the repository. Note: do not change cvs to svn here.

```bash
sudo su -c /var/lib/rancid/bin/rancid-cvs -s /bin/bash -l rancid
```

--------------------------------

### Cisco IOS syslog configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Example configuration for Cisco IOS to send syslog to LibreNMS. Replace librenms.ip with the IP or hostname of your LibreNMS install.

```config
logging trap debugging
logging facility local6
logging librenms.ip
```

--------------------------------

### rsyslog client configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Example configuration for rsyslog client to send all logs to LibreNMS on port 514. Replace librenms.ip with the IP or hostname of your LibreNMS install.

```config
*.* @librenms.ip:514
```

--------------------------------

### Enable Prometheus and set basic configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/metrics/Prometheus.md

Enable Prometheus support and configure the PushGateway URL, job name, and metric prefix. Run these commands via the LibreNMS CLI.

```bash
lnms config:set prometheus.enable true
lnms config:set prometheus.url 'http://127.0.0.1:9091'
lnms config:set prometheus.job 'librenms'
lnms config:set prometheus.prefix 'librenms'
```

--------------------------------

### Manage snmp.community with lnms config:get and config:set

Source: https://github.com/librenms/librenms/blob/master/doc/Support/Configuration.md

Examples of using `lnms config:get` and `lnms config:set` to manage the `snmp.community` setting. Shows appending with `.+`, replacing an index, invalid format error, setting a JSON array, and resetting to default with confirmation.

```bash
lnms config:get snmp.community
  [
      "public"
  ]

lnms config:set snmp.community.+ testing

lnms config:get snmp.community
  [
      "public",
      "testing"
  ]


lnms config:set snmp.community.0 private

lnms config:get snmp.community
  [
      "private",
      "testing"
  ]

lnms config:set snmp.community test
  Invalid format

lnms config:set snmp.community '["test", "othercommunity"]'

lnms config:get snmp.community
  [
      "test",
      "othercommunity"
  ]

lnms config:set snmp.community

  Reset snmp.community to the default? (yes/no) [no]:
  > yes


lnms config:get snmp.community
  [
      "public"
  ]
```

--------------------------------

### Huawei SmartAX syslog configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Example configuration for Huawei SmartAX (GPON OLT) to send syslog to LibreNMS. Replace librenms.ip with the IP or hostname of your LibreNMS install.

```config
loghost add librenms.ip librenms
loghost activate name librenms
```

--------------------------------

### Install fcgiwrap and copy default Nginx config

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Smokeping.md

Install fcgiwrap and copy its default Nginx configuration to /etc/nginx/fcgiwrap.conf. Required before configuring the /smokeping/ location.

```bash
apt install fcgiwrap
```

```bash
cp /usr/share/doc/fcgiwrap/examples/nginx.conf /etc/nginx/fcgiwrap.conf
```

--------------------------------

### Download and extract LibreNMS Docker compose files

Source: https://github.com/librenms/librenms/blob/master/doc/Installation/Docker.md

Downloads and extracts the LibreNMS Docker compose example files into a new directory. Run these commands from a terminal after installing Docker.

```bash
mkdir librenms
cd librenms
wget https://github.com/librenms/docker/archive/refs/heads/master.zip
unzip master.zip
cd docker-master/examples/compose
```

--------------------------------

### Count devices, ports, and sensors in MySQL

Source: https://github.com/librenms/librenms/blob/master/doc/Support/Example-Hardware-Setup.md

Run these queries to get the device count, port count, and sensor count for your LibreNMS installation. The queries filter out deleted ports and sensors.

```mysql
select count(*) from devices;
select count(*) from ports where `deleted` = 0;
select count(*) from sensors where `sensor_deleted` = 0;
```

--------------------------------

### Create and activate Python virtual environment for docs

Source: https://github.com/librenms/librenms/blob/master/doc/Developing/Creating-Documentation.md

Create a new virtual environment and activate it before installing the required Python packages for building the documentation.

```bash
python -m venv .python_venvs/docs
source .python_venvs/docs/bin/activate

```

--------------------------------

### Huawei VRP syslog configuration

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Syslog.md

Example configuration for Huawei VRP to send syslog to LibreNMS. Replace librenms.ip with the IP or hostname of your LibreNMS install. The timestamp and filter-id lines are optional.

```config
info-center loghost librenms.ip
info-center timestamp debugging short-date without-timezone // Optional
info-center timestamp log short-date // Optional
info-center timestamp trap short-date // Optional
//This is optional config, especially if the device is in public ip and you dont'want to get a lot of messages of ACL
info-center filter-id bymodule-alias VTY ACL_DENY
info-center filter-id bymodule-alias SSH SSH_FAIL
info-center filter-id bymodule-alias SNMP SNMP_FAIL
info-center filter-id bymodule-alias SNMP SNMP_IPLOCK
info-center filter-id bymodule-alias SNMP SNMP_IPUNLOCK
info-center filter-id bymodule-alias HTTP ACL_DENY
```

--------------------------------

### Dump all configuration values with jq

Source: https://github.com/librenms/librenms/blob/master/doc/Support/Configuration.md

Example output of `lnms config:get --dump | jq` showing the complete current configuration in JSON format. The output is truncated with `...` in the source.

```bash
lnms config:get --dump | jq 
{
  "install_dir": "/opt/librenms",
  "active_directory": {
    "users_purge": 0
  },
  "addhost_alwayscheckip": false,
  "alert": {
    "ack_until_clear": false,
    "admins": true,
    "default_copy": true,
    "default_if_none": false,
    "default_mail": false,
    "default_only": true,
    "disable": false,
    "fixed-contacts": true,
    "globals": true,
    "syscontact": true,
    "transports": {
      "mail": 5
    },
    "tolerance_window": 5,
    "users": false,
    ...
```

--------------------------------

### Install OSLV::Monitor generically

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/OS Level Virtualization Monitoring.md

Install the OSLV::Monitor Perl module and its dependencies generically using cpanm.

```bash
cpanm JSON Clone Mime::Base64 File::Slurp IO::Interface
cpanm OSLV::Monitor
```

--------------------------------

### snmpget discovery operator example

Source: https://github.com/librenms/librenms/blob/master/doc/Developing/os/Initial-Detection.md

Shows the snmpget operator for OS detection, which gets an OID and compares it to a value. Use only when no other method works. The op list includes comparison and regex operators.

```yaml
discovery:
    -
      snmpget:
        - oid: MIB-NAME::someoid
        - op: <["=","!=","==","!==","<=",">=","<",">","starts","ends","contains","regex","not_starts","not_ends","not_contains","not_regex","in_array","not_in_array","exists"]>
        - value: <'string' | boolean>

```

--------------------------------

### Install Galera4 and MariaDB Server

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Galera-Cluster.md

Install MariaDB server, client, and Galera 4 from the OS package manager on Ubuntu.

```bash
sudo apt-get install mariadb-server mariadb-client galera-4
```

--------------------------------

### Install prerequisites on Debian/Ubuntu

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Nextcloud.md

Install required Perl modules and Time::Piece using apt-get and cpanm.

```bash
apt-get install libjson-perl libfile-slurp-perl libmime-base64-perl cpanminus
cpanm Time::Piece
```

--------------------------------

### Get port description via /api/v0/ports/:portid/description

Source: https://github.com/librenms/librenms/blob/master/doc/API/Ports.md

Retrieves the description (`ifAlias`) for a given port ID. The example shows a request for port 323 and the JSON response containing the port description.

```curl
curl -H 'Authorization: Bearer YOURAPITOKENHERE' https://foo.example/api/v0/ports/323/description
```

```json
{
    "status": "ok",
    "port_description": "GigabitEthernet14"
}
```

--------------------------------

### Get all ports with columns | /api/v0/ports

Source: https://github.com/librenms/librenms/blob/master/doc/API/Ports.md

Retrieves all ports across all devices. Use the 'columns' parameter to limit data. The example requests only 'ifName' and 'port_id'. The response shows an array of ports with those fields.

```curl
curl -H 'Authorization: Bearer YOURAPITOKENHERE' https://foo.example/api/v0/ports?columns=ifName%2Cport_id
```

```json
{
  "status": "ok",
  "message": "",
  "ports": [
        {
          "ifName": "Gi0/0/0",
          "port_id": "1"
        },
        {
          "ifName": "Gi0/0/1",
          "port_id": "2"
        },
        ...
        {
          "ifName": "Vlan 3615",
          "port_id": "5488"
        }
    ]
}
```

--------------------------------

### Okta provider event listener setup

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/OAuth-SAML.md

For Okta provider, locate the event listener array, copy the OktaExtendSocialite class reference, and set it as the listener using the lnms config:set command. Ensure the backslash at the start is included.

```php
protected $listen = [
\SocialiteProviders\Manager\SocialiteWasCalled::class => [
    // ... other providers
    \SocialiteProviders\Okta\OktaExtendSocialite::class.'@handle',
],
];
```

```bash
lnms config:set auth.socialite.configs.okta.listener "\SocialiteProviders\Okta\OktaExtendSocialite"
```

--------------------------------

### Create Apache configuration file

Source: https://github.com/librenms/librenms/blob/master/doc/Installation/Install-LibreNMS.md

Command to create the Apache configuration file for LibreNMS using vi.

```bash
vi /etc/httpd/conf.d/librenms.conf
```

--------------------------------

### Microsoft provider event listener setup

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/OAuth-SAML.md

For Microsoft provider, locate the event listener array, copy the MicrosoftExtendSocialite class reference, and set it as the listener using the lnms config:set command. Ensure the backslash at the start is included.

```php
protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        // ... other providers
        \SocialiteProviders\Microsoft\MicrosoftExtendSocialite::class.'@handle',
    ],
];
```

```bash
lnms config:set auth.socialite.configs.microsoft.listener "\SocialiteProviders\Microsoft\MicrosoftExtendSocialite"
```

--------------------------------

### List alerts with GET /api/v0/alerts and filters

Source: https://github.com/librenms/librenms/blob/master/doc/API/Alerts.md

Lists alerts with optional filters: state, severity, alert_rule, and order. The example shows filtering by state=1, severity=critical, ordering by timestamp ascending, and filtering by alert_rule=49. The output shows a single alert.

```curl
curl -H 'Authorization: Bearer YOURAPITOKENHERE' https://foo.example/api/v0/alerts?state=1
```

```curl
curl -H 'Authorization: Bearer YOURAPITOKENHERE' https://foo.example/api/v0/alerts?severity=critical
```

```curl
curl -H 'Authorization: Bearer YOURAPITOKENHERE' https://foo.example/api/v0/alerts?order=timestamp%20ASC
```

```curl
curl -H 'Authorization: Bearer YOURAPITOKENHERE' https://foo.example/api/v0/alerts?alert_rule=49
```

```json
{
 "status": "ok",
 "message": "",
 "count": 1,
 "alerts": [
  {
   "id": "1",
   "device_id": "1",
   "rule_id": "1",
   "state": "1",
   "alerted": "1",
   "open": "1",
   "timestamp": "2014-12-11 14:40:02"
  }]
}
```

--------------------------------

### Install dependencies with composer_wrapper.php

Source: https://github.com/librenms/librenms/blob/master/doc/Developing/os/Test-Units.md

Run this command in the LibreNMS root directory before running tests. It reads composer.json and installs necessary dependencies.

```bash
./scripts/composer_wrapper.php install
```

--------------------------------

### GitHub provider event listener setup

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/OAuth-SAML.md

For GitHub provider, locate the event listener array in the Socialite provider configuration, copy the GitHubExtendSocialite class reference, and set it as the listener using the lnms config:set command. Ensure the backslash at the start is included.

```php
protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        // ... other providers
        \SocialiteProviders\GitHub\GitHubExtendSocialite::class.'@handle',
    ],
];
```

```bash
lnms config:set auth.socialite.configs.github.listener "\SocialiteProviders\GitHub\GitHubExtendSocialite"
```

--------------------------------

### Get port IP info via /api/v0/ports/:portid/ip

Source: https://github.com/librenms/librenms/blob/master/doc/API/Ports.md

Retrieves all IP information (IPv4 and IPv6) for a given port ID. The portid must be an integer. The example shows a request for port 323 and the JSON response containing an IPv4 address entry.

```curl
curl -H 'Authorization: Bearer YOURAPITOKENHERE' https://foo.example/api/v0/ports/323/ip
```

```json
{
  "status": "ok",
  "message": "",
  "addresses": [
    {
      "ipv4_address_id": "290",
      "ipv4_address": "192.168.99.292",
      "ipv4_prefixlen": "30",
      "ipv4_network_id": "247",
      "port_id": "323",
      "context_name": ""
    }
  ]
}
```

--------------------------------

### SNMP Extend setup for Apache monitoring

Source: https://github.com/librenms/librenms/blob/master/doc/Extensions/Applications/Apache.md

Steps to set up Apache monitoring via SNMP extend: download the script, make it executable, create the cache directory, install the urllib3 package, add the extend line to snmpd.conf, restart snmpd, and test with snmpwalk.

```bash
wget https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/apache-stats.py -O /etc/snmp/apache-stats.py
```

```bash
chmod +x /etc/snmp/apache-stats.py
```

```bash
mkdir -p /var/cache/librenms/
```

```bash
apt-get install python3-urllib3
```

```bash
extend apache /etc/snmp/apache-stats.py
```

```bash
sudo systemctl snmpd restart
```

```bash
snmpwalk <various options depending on your setup> localhost NET-SNMP-EXTEND-MIB::nsExtendOutput2Table
```

--------------------------------

### Compile and install SELinux module for fping

Source: https://github.com/librenms/librenms/blob/master/doc/Installation/Install-LibreNMS.md

Compiles the http_fping.tt policy file into a loadable module and installs it. Run these commands after creating http_fping.tt.

```bash
checkmodule -M -m -o http_fping.mod http_fping.tt
semodule_package -o http_fping.pp -m http_fping.mod
semodule -i http_fping.pp
```
Tokens:
Raw