Skip to content

FAQ

Getting started

How do I install LibreNMS?

The doc folder of the installation files holds the full instructions.

Read the installation document.

How do I add a device?

There are two ways to add a new device to LibreNMS.

1: On the command line, connect with ssh. Then change to the directory of your LibreNMS install and run:

lnms device:add [hostname or ip]

For all the options, run lnms device:add -h.

A community with a special character such as $ needs single quotation marks around it. An example is 'Pa$$w0rd'.

2: In the web interface, go to Devices, then Add Device. Enter the details of the device. Then click Add Host.

How do I get help?

Getting Help

What are the supported OSes for installing LibreNMS on?

These distributions have official support:

  • Ubuntu and Debian
  • Red Hat and CentOS
  • Gentoo

We help with other distributions where we can. If your distribution is not in the list, try the installation. For help, join our discord server.

Do you have a demo available?

Yes. The demo is at https://demo.librenms.org.

Support

How does LibreNMS use MIBs?

LibreNMS does not parse MIBs to discover the sensors of a device. LibreNMS uses static discovery definitions in YAML or PHP. An update of a MIB alone therefore does not improve the OS support. The definitions also need an update. LibreNMS uses MIBs only to make OIDs easier to read.

Why do I get blank pages sometimes in the WebUI?

To enable debug information, set APP_DEBUG=true in your .env file. Do not leave this setting enabled, because it can leak private data.

If the page holds a large amount of data, increase the PHP memory limit in config.php.

Why do I not see any graphs?

Become the librenms user and run ./validate.php in your install directory. The output gives the cause of the problem.

A restricted snmpd.conf file or a restricted SNMP view is another cause. Such a restriction limits the data that the device returns. For net-snmp, we recommend the supplied snmpd.conf file.

How do I debug pages not loading correctly?

LibreNMS has a debug system. This system shows the PHP errors, the PHP warnings, and the PHP notices. It also shows the MySQL queries of the page.

To enable debug information, set APP_DEBUG=true in your .env file. Do not leave this setting enabled, because it can leak private data. For more information, run ./scripts/composer_wrapper.php install. This command installs more debug tools. It adds a debug bar at the bottom of each page with detailed debug information.

How do I debug the discovery process?

For more information, read the Discovery Support document.

How do I debug the poller process?

For more information, read the Poller Support document.

Why do I get a lot apache or rrdtool zombies in my process list?

The cause is a problem in PHP. The PHP developers do not plan a correction. We added a workaround, so this problem must not occur. If it does occur, report it in issue 443.

Why do I see traffic spikes in my graphs?

A spike occurs at a counter reset. It also occurs when the device returns bad data that looks like a counter reset. LibreNMS can set a maximum value for the RRD files of the ports.

Before this feature, all RRD files had a maximum value of 100G. You can now limit the maximum value to the real port speed.

rrdtool tune changes the maximum value when the interface speed changes. It sets a minimum value for 10M and higher. The supplied script lnms port:tune does the same. For more information, read the RRDTune doc.

The SNMP objects ifInOctets and ifOutOctets are counters. Each counter starts at 0 at the boot of the device and counts up. LibreNMS records the value every 5 minutes. It calculates the rate from the difference between the previous value and the current value. The counter also returns to 0 at its maximum value.

RRD is our time series storage. When no value arrives for some time, RRD does not record a 0. It records the last value, because a 0 causes worse problems. LibreNMS then gets the current ifInOctets value or ifOutOctets value and records it. All the traffic since the last good value therefore appears in the last 5-minute interval.

A spike therefore means that no data arrived from the device for several polling intervals. The causes are different: a bad SNMP implementation, intermittent network connectivity, a broken poller, and more.

Why do I see gaps in my graphs?

The most common cause is a poller run of more than 300 seconds. To find the devices with this problem, open /poll-log/ in the web interface.

Find the devices with the longest run. Then open the polling module graph under Graphs -> Poller -> Poller Modules Performance. Find the modules with the longest time and disable the unused modules.

If you poll many devices or many ports, run a local recursive DNS server such as pdns-recursor.

We also recommend RRDCached for a large install. It gives a benefit at each install size.

How do I change the IP / hostname of a device?

The renamehost.php tool is in your librenms root directory. A rename also changes the IP address or the hostname for the monitoring.

Usage:

./renamehost.php <old hostname> <new hostname>

You can also rename a device in the web interface. Open the device, then click the settings icon -> Edit.

My device does not finish polling within 300 seconds

Try these corrections:

  • Disable the unnecessary polling modules under edit device.
  • Set a max repeater value in the SNMP settings of the device. The best value is difficult to find. Run an snmpbulkwalk with -Cr10 to -Cr50 and compare the results. 50 is usually a good value for a device with enough capacity.

Things are not working correctly?

Become the librenms user and run ./validate.php in your install directory.

Correct each problem in the output. Then run ./validate.php again.

For an unusual problem, join our discord server.

What do the values mean in my graphs?

The graphs give metric values. A post on Reddit lists these values:

10^-18  a - atto
10^-15  f - femto
10^-12  p - pico
10^-9   n - nano
10^-6   u - micro
10^-3   m - milli
0    (no unit)
10^3    k - kilo
10^6    M - mega
10^9    G - giga
10^12   T - tera
10^15   P - peta

Why does a device show as a warning?

The warning means that the device rebooted in the last 24 hours. This period is the default. To change the threshold, set $config['uptime_warning'] = '86400'; in config.php. The value is in seconds.

Why do I not see all interfaces in the Overall traffic graph for a device?

By default, this graph excludes many interface types and interface descriptions. These are the excluded defaults:

$config['device_traffic_iftype'][] = '/loopback/';
$config['device_traffic_iftype'][] = '/tunnel/';
$config['device_traffic_iftype'][] = '/virtual/';
$config['device_traffic_iftype'][] = '/mpls/';
$config['device_traffic_iftype'][] = '/ieee8023adLag/';
$config['device_traffic_iftype'][] = '/l2vlan/';
$config['device_traffic_iftype'][] = '/ppp/';

$config['device_traffic_descr'][] = '/loopback/';
$config['device_traffic_descr'][] = '/vlan/';
$config['device_traffic_descr'][] = '/tunnel/';
$config['device_traffic_descr'][] = '/bond/';
$config['device_traffic_descr'][] = '/null/';
$config['device_traffic_descr'][] = '/dummy/';

To include the l2vlan interfaces again, first unset the configuration array. Then set your own options:

unset($config['device_traffic_iftype']);
$config['device_traffic_iftype'][] = '/loopback/';
$config['device_traffic_iftype'][] = '/tunnel/';
$config['device_traffic_iftype'][] = '/virtual/';
$config['device_traffic_iftype'][] = '/mpls/';
$config['device_traffic_iftype'][] = '/ieee8023adLag/';
$config['device_traffic_iftype'][] = '/ppp/';

How do I migrate my LibreNMS install to another server?

For a move to a different CPU architecture, dump the RRD files and create them again. Use Dan Brown's migration scripts.

For a move to another server with the same CPU architecture, do these steps:

  • Install LibreNMS as in our normal documentation. Do not use the web installer and do not build the SQL schema.
  • Stop cron. Comment out all lines in /etc/cron.d/librenms.
  • Dump the MySQL database librenms on your old server (mysqldump librenms -u root -p > librenms.sql).
  • Import the dump into your new server (mysql -u root -p librenms < librenms.sql).
  • Copy the rrd/ folder to the new server.
  • Copy the .env file and the config.php file to the new server.
  • Find the modified files, such as a specific OS, with git status. Then migrate these files.
  • Set the ownership of the copied files and folders with chown -R librenms:librenms /opt/librenms. Use your own user if it is different.
  • Remove the old pollers in the web interface (gear icon --> Pollers --> Pollers).
  • Validate your installation with /opt/librenms/validate.php.
  • Enable cron again. Remove the comment from all lines in /etc/cron.d/librenms.

Why is my EdgeRouter device not detected?

The cause is usually service snmp description in your configuration. Remove this setting. Ubiquiti made this value override the sysDescr value, and the override breaks our detection.

If the setting is not in your configuration, the cause is an EdgeOS update or a new device type. Please create an issue.

Why are some of my disks not showing?

On a Linux server, net-snmp does not always expose all disks through hrStorage (HOST-RESOURCES-MIB). LibreNMS also reads the disks from dskTable (UCD-SNMP-MIB). To expose these disks, add more configuration to your snmpd.conf file. For example, /dev/sda1 can have the mount point /storage. To expose this disk, use one of these lines:

disk /dev/sda1

Or

disk /storage

Restart snmpd. LibreNMS then adds the disk at the next discovery.

Why are my disks reporting an incorrect size?

net-snmp has a known problem. It reports an incorrect disk size and an incorrect disk use for a disk or a raid of more than 16TB. A workaround exists, but it is not active on CentOS 6.8 by default. The workaround breaks the official SNMP specification and can therefore cause an unexpected result in other SNMP tools. To enable the workaround, add this line to /etc/snmp/snmpd.conf:

realStorageUnits 0

What does mean \"ignore alert tag\" on device, component, service and port?

The ignore alert tag marks a device, a component, a service, or a port. The alert checks still run. An alert rule can read the tag. For example, a device can have the condition devices.ignore = 0 or macros.device = 1. With the ignore alert tag on, the alert rule does not match. LibreNMS ignores the alert rule.

How do I clean up alerts from my switches and routers about ports being down or changing speed

Some properties for alerting end in _prev. LibreNMS updates these properties only at a change, not at each poller run. A permanent change to your network can therefore leave an alert that does not clear. Examples of such a change are the removal of a device, a major firmware upgrade, and a downgrade of a WAN connection.

If a port stays down permanently, set it to administratively down on the device. This setting also stops malicious access. You can then run alerts only on the ports with ifAdminStatus = up. If you do not do this, you must reset the port state history of the device.

On the device with the alerts, click the cog button to open the edit device page. The button Reset Port State is at the top of the device settings pane. This button clears the historic state of all ports on that device. The active alerts then clear.

Why cannot Normal and Global View users see Oxidized?

A device configuration often holds sensitive data. Only a global administrator can therefore see the configurations.

What is the Demo User for?

A demo user has full access with three limits. A demo user cannot add or edit users, cannot remove devices, and cannot change passwords.

Why does modifying 'Default Alert Template' fail?

The entry of this template can be absent from the database. Run this command in the LibreNMS directory:

php artisan db:seed --class=DefaultAlertTemplateSeeder

Why does an alert un-mute itself?

An alert that un-mutes itself usually cleared and then triggered again. For the details, read the eventlog.

How do I change the Device Type?

Open the device, then click the gear icon -> Edit. For your own custom types, we recommend Device Groups. The menu shows device groups in the same way as device types.

Editing large device groups gives error messages

A device group with many devices can give form errors in the web interface, even with correct data. The cause is the PHP variable max_input_vars. The PHP error log confirms this cause.

On a basic installation with Ubuntu 22.04 LTS, Nginx, and PHP 8.1 FPM, edit the file /etc/php/8.1/fpm/php.ini. Set max_input_vars to at least the size of the large group. A value of 10000 is enough for a large installation.

Where do I update my database credentials?

If you changed your database credentials, put the new details into LibreNMS. Edit the .env file.

.env:

DB_HOST=
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=
DB_PORT=

My reverse proxy is not working

Your proxy must pass the correct variables. The minimum set is X-Forwarded-For and X-Forwarded-Proto. Add X-Forwarded-Port when your setup needs it.

You must also set the proxies as trusted.

If the subdirectory is on the reverse proxy and not on the web server, set APP_URL and $config['base_url'].

My alerts are not delivered on time

If MySQL or MariaDB runs on a separate machine or container, set the timezone correctly on the LibreNMS instance and on the database instance. LibreNMS delivers alerts on the time of the database. A difference between the two timezones therefore delays the alerts. This occurs when the timezone of LibreNMS is later than the timezone of the database.

My alert templates stopped working

Read the documentation on the new template syntax. The syntax changed in version 1.42. Convert your templates and your titles to this new syntax.

How do I use trend prediction in graphs

Version 1.55 added a simple linear prediction in port graphs.

The prediction works only on port graphs. It does not work on other graphs or on consolidated graphs.

To see a prediction:

  • Click a port graph of a network device.
  • Select a From date. This date must not be earlier than the date of the device in LibreNMS. Then select a future date in the To field.
  • Click update.

The graph then shows a linear prediction line.

How do I move only the DB to another server?

Another section describes a move of the whole LibreNMS installation to another server. The steps below divide an all-in-one installation into one LibreNMS installation and one separate database installation. *Note: this section assumes a MySQL instance or a MariaDB instance.

  • Stop the apache service and the mysql service on your LibreNMS installation.
  • Comment out all the cron entries in /etc/cron.d/librenms.
  • Dump your librenms database on your current install with mysqldump librenms -u root -p > librenms.sql.
  • Stop and disable the MySQL server on your current install.
  • On your new server, create a new database with the standard install command. A user for localhost is not necessary.
  • Copy the dump to your new database server and import it with mysql -u root -p librenms < librenms.sql.
  • Open mysql and add the permissions with these two commands: 
    GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'IP_OF_YOUR_LNMS_SERVER' IDENTIFIED BY 'PASSWORD' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'FQDN_OF_YOUR_LNMS_SERVER' IDENTIFIED BY 'PASSWORD' WITH GRANT OPTION;
FLUSH PRIVILEGES;
exit;
  • Enable and restart the MySQL server.
  • Edit your config.php file. Point the install to the new database server.
  • Very important: your install directory on the LibreNMS server holds a .env file. Edit the DBHOST parameter in this file. Point it to your new server.
  • Enable all the cron entries again and start apache.

What are the "optional requirements message" when I add SNMPv3 devices?

The web interface can show the message "Optional requirements are not met so some options are disabled" when you add a device. This message means that your system does not have openssl >= 1.1 and net-snmp >= 5.8. These are the minimum versions for the authentication algorithms SHA-224, SHA-256, SHA-384, and SHA-512. The crypto algorithms AES-192 and AES-256 need net-snmp with the compile option --enable-blumenthal-aes.

Developing

How do I add support for a new OS?

To write all the supporting code yourself, read Supporting a new OS. If you can supply only the information and want help with the code, do the steps below.

What information do you need to add a new OS?

Open a feature request in the community forum. Supply the output of Discovery, Poller, and snmpwalk as separate pastebin links. The links must not expire. We recommend https://paste.rs/ or https://paste.sh/.

Use the command line to get the information, because snmpwalk returns a large amount of data. In the commands below, replace HOSTNAME and COMMUNITY with your own values. For a v1 device, use snmpwalk instead of snmpbulkwalk.

These commands upload the data to the https://paste.rs/ servers. You can use another service.

lnms device:discover -vv HOSTNAME | curl --data-binary @- https://paste.rs/
lnms device:poll -vv HOSTNAME | curl --data-binary @- https://paste.rs/
snmpbulkwalk -OUneb -v2c -c COMMUNITY HOSTNAME . | curl --data-binary @- https://paste.rs/

Put the links from these commands into your community post.

If the OS is new, also give the correct OS name. Add any useful link, such as the MIBs from the vendor and the logo.

What can I do to help?

Everyone can contribute something different. These are some ways to help LibreNMS.

  • Code. Code support is the largest area of help. The software must develop and change to meet the needs of the users. Code support does not only mean the discovery of a new device:
  • Web interface. The new look and feel is not complete. Make suggestions, find and correct bugs, and update the design and the layout.
  • Poller and discovery code. Make it faster, add support for new devices, and update the old devices.
  • The main LibreNMS website. GitHub hosts this site, in the same way as the main repository. We accept contributions here too.
  • Hardware. We do not need the physical device. SNMP access to the device makes new device support much easier.
  • MIBs are also useful.
  • Permission from the vendor to use their logo is also useful.
  • Bugs. Report each bug that you find. Most corrections start with a report from a user.
  • Feature requests. If you cannot write code, put a feature request in our community forum with enough detail. Someone then examines it. Often another person needs the same feature or has the time to write it. Please be patient, because every contributor works in their own time.
  • Documentation. Every improvement to the documentation helps. Some features have no documentation or poor documentation, and there are spelling mistakes. You can send updates through the GitHub website. You do not need git experience.
  • Be nice. This is the foundation of this project. We expect everyone to be nice. People disagree, but they must do so with respect.
  • Ask questions. A question often starts a deeper conversation with a good result. Never be afraid to ask a question.

How can I test another users branch?

Anyone can develop LibreNMS. Another person can therefore work on a new feature or on support for a device that you want. Tests from other users help. Git makes these tests easy.

cd /opt/librenms

First, make sure that your current branch is in a good state:

git status

The output must show nothing to commit, working directory clean.

For example, the user f0o has a new development branch issue-1337. To test that branch, run these commands:

git remote add f0o https://github.com/f0o/librenms.git
git remote update f0o
git checkout issue-1337

After the tests, go back to the master branch:

git checkout master

To get the new updates from the branch of f0o, stay on that branch and run:

git pull f0o issue-1337