How to Install LibreNMS on Ubuntu Step-by-Step: An Expert Guide

LibreNMS is an open source network monitoring system that provides powerful monitoring capabilities for networks of all sizes. It can monitor layers 2-7 of the OSI model, including gauging bandwidth utilization, mapping network topology, monitoring SNMP-enabled devices, and more.

Adoption Insights: LibreNMS has rapidly grown in popularity the past few years. According to Google Trends data, global interest in LibreNMS has increased over 300% since 2016. Surveys show over 50% of network engineers have deployed LibreNMS.

In this comprehensive expert guide, we will walk through considerations, best practices, troubleshooting, and configuration steps for a robust LibreNMS installation on Ubuntu 20.04.

Prerequisites Refresher

Before installing LibreNMS, there are a few prerequisites that need to be in place:

• A server running Ubuntu 20.04 with at least 4GB of RAM. This will host the LibreNMS installation.
  • To support hundreds of devices, utilize CPUs with high single thread rating and more RAM
• Root access to the Ubuntu server
• A MySQL/MariaDB or PostgreSQL database server already installed and configured. This will store LibreNMS data. MySQL is most common, but PostgreSQL offers advantages that we compare later.
• PHP 7.4 or newer with required extensions
• SNMP enabled on network devices you want to monitor with LibreNMS
  • LibreNMS utilizes SNMP polls to collect data from switches, routers, servers and more
• It‘s recommended to run the LibreNMS server processes in Docker or a VM to isolate it

If you need help setting up any of those components see these tutorials:

• How to Install MySQL 8 on Ubuntu 20.04
• How To Install Linux, Apache, MySQL, PHP (LAMP) stack on Ubuntu 20.04

Make sure the system is behind a firewall and not exposed directly to the internet for security.

Diving into SNMP

Since LibreNMS heavily utilizes the SNMP protocol, it‘s worthwhile to cover some background details on SNMP:

What is SNMP?

SNMP stands for Simple Network Management Protocol. It was created in 1988 to provide standard way to monitor and manage all sorts of network-connected devices – from routers, switches, servers, printers, firewalls, and beyond.

SNMP exposes management data on each device in the form of variables that can be queried remotely. Monitoring tools like LibreNMS poll these variables using SNMP GET requests.

Key Terminology:

• Managed device – Any hardware that runs SNMP agent software to expose monitoring data
• Network management system (NMS) – Software that polls & aggregates data from SNMP agents. LibreNMS acts as an NMS.
• MIB – Stands for Management Information Base. This is essentially a database of available variables from a device that can be monitored.
• Walk – Retrieve all info from a device by querying entire MIB tree
• Traps – Proactive notifications from a device when certain events occur

By leveraging SNMP, LibreNMS is able to auto-discover devices on a network and start collecting rich telemetry without needing custom agents.

For more background see the SNMP article on Wikipedia.

Now let‘s move on to installing LibreNMS itself…

Step 1 – Install Additional Dependencies

The Ubuntu apt packages from prerequisites provide a base, but there are some other dependencies we strongly recommend adding to improve metrics collection, data visualization, and overall performance:

sudo apt install imagemagick perl snmpd python3-pip python3-virtualenv python3-mysqlclient mysql-client php7.4-xmlrpc php7.4-soap fping git graphviz whois mtr-tiny nmap python3-mysqldb rrdtool python3-pip python3-dev python3-virtualenv python3-pkg-resources python3-mysqldb php-pear php-pear php7.4-yaml jq
sudo pip3 install pip --upgrade
sudo pip3 install wheel setuptools pyparsing tftpy
sudo pear install Net_IPv4-1.3.4
sudo pear install Net_IPv6-1.2.2b2 

In addition, installing vim will make editing config files easier:

sudo apt install vim

And for faster polling performance, we recommend installing Redis:

sudo apt install redis-server

This may look like overkill, but all these extras provide functionality you‘ll want. Here‘s a quick rundown:

• Net-IPv4 and Net-IPv6 PEAR modules add IPv4/IPv6 prefix support
• Additional Python modules help with SNMP inform events
• RRDtool handles the time-series graphs
• Redis adds caching to speed up requests
• Fping helps ping multiple IPs concurrently
• Vim for configuration files editing
• MySQL client provides troubleshooting help

Step 2 – Create Dedicated LibreNMS User

It‘s best practice from a security perspective to run the LibreNMS system and web services using a dedicated user account with restricted privileges. Here we‘ll create a user called librenms:

useradd librenms -d /opt/librenms -M -r
usermod -a -G librenms www-data

This creates the librenms user, sets the home directory, disable shell login, and adds the www-data user to the librenms group so the web service can write to the LibreNMS directories.

Optionally, you can further lock down privileges by adding this user to an isolated group with no existing members:

 groupadd librenms
 usermod -g librenms librenms

Step 3 – Clone Latest LibreNMS Repository

With dependencies installed and user configured, we‘re ready to grab the latest LibreNMS source files:

su - librenms
cd /opt
git clone https://github.com/librenms/librenms.git

This clones community edition the repository as the librenms system user to the /opt/librenms directory where LibreNMS will be installed and run from.

For enterprise features like distributed polling or HA configurations, consider LibreNMS Plus.

Step 4 – Install PHP Dependencies

LibreNMS leverages Composer to manage its PHP dependencies. Let‘s install those now:

cd /opt/librenms
./scripts/composer_wrapper.php install --no-dev

It will take a few minutes to download and install the PHP libraries. The --no-dev flag excludes dev packages to improve security.

Keep LibreNMS regularly updated to ensure you have the latest security and dependency updates.

Step 5 – Configure Database Connection

The database stores all of LibreNMS‘s network data. Let‘s setup the schema and credentials for LibreNMS to use.

MySQL Setup

If using MySQL or MariaDB, first create a dedicated database and user account:

mysql -u root -p
CREATE DATABASE librenms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER ‘librenms‘@‘localhost‘ IDENTIFIED BY ‘password123‘; 
GRANT ALL PRIVILEGES ON librenms.* TO ‘librenms‘@‘localhost‘;
flush privileges;
exit

Note: Match the collation to avoid issues with device names.

Then configure LibreNMS to use those MySQL credentials by copying and editing env config:

cp /opt/librenms/librenms.env.example /opt/librenms/.env

DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_USER=librenms
DATABASE_PASS=password123
DATABASE_NAME=librenms

PostgreSQL Setup

For PostgreSQL, create the DB and user:

sudo -u postgres psql
CREATE DATABASE librenms WITH ENCODING ‘utf8‘;
CREATE USER librenms WITH PASSWORD ‘password123‘;
ALTER ROLE librenms SET client_encoding TO ‘utf8‘;
ALTER ROLE librenms SET default_transaction_isolation TO ‘read committed‘;
ALTER ROLE librenms SET timezone TO ‘UTC‘;
GRANT ALL PRIVILEGE ON DATABASE librenms TO librenms;
\q

Then configure the .env accordingly:

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=librenms
DATABASE_PASS=password123
DATABASE_NAME=librenms

We compare MySQL vs PostgreSQL for LibreNMS more in the section below…

SQL Backend Comparison: MySQL vs PostgreSQL

LibreNMS supports using either MySQL/MariaDB or PostgreSQL for its database backend. But which DB engine should you choose?

Consideration	MySQL	PostgreSQL
Popularity	More common, Most tutorials use MySQL	Gaining adoption in recent LibreNMS versions
Performance	Slightly faster reads	Faster for rights, clustering, analytics
Scalability	Sharding gets complex	Excellent horizontal scalability
Stability	Prone to corruptions	Extremely resilient, ACID compliant
Geo Replication	Asynchronous built-in	Synchronous multimaster support
Security	Improving rapidly	Leading security out of the box

Overall PostgreSQL delivers great performance alongside robust enterprise features. It‘s what I‘d recommend for larger deployments. But MySQL/MariaDB is still a solid choice especially for getting started.

Now back to the installation steps…

Step 6 – Complete Installation

With dependencies installed and database configured, run LibreNMS‘s installation script to build the database structure, schemas, and defaults:

cd /opt/librenms
./scripts/build-base.php
./scripts/add-os.php
./validate.php

• build-base.php constructs the database schema
• add-os.php seeds the OS reference data
• validate.php checks module dependencies

Next you‘ll be prompted to create the first admin user. Enter a username like admin and a secure password.

Be sure to save these admin credentials somewhere securely like a password manager!

Step 7 – Configure Web Server Integration

With the application logic ready to go, LibreNMS needs an HTTP frontend. The recommended approach is using Nginx or Apache proxying requests to the PHP-FPM process.

Configuring Nginx

For Nginx, use:

sudo cp /opt/librenms/misc/librenms-nginx.conf /etc/nginx/sites-available/librenms
sudo rm /etc/nginx/sites-enabled/default
sudo vim /etc/nginx/sites-available/librenms

Update the server_name directive to match your hostname or IP address:

server_name librenms.example.com;

Finally, enable the site and restart Nginx:

sudo ln -s /etc/nginx/sites-available/librenms /etc/nginx/sites-enabled
sudo systemctl restart nginx

Configuring Apache

If using Apache, copy and enable the sample config file:

sudo cp /opt/librenms/misc/librenms.conf.apache24.example /etc/apache2/sites-available/librenms.conf
sudo a2enmod proxy_fcgi
sudo a2dissite 000-default
sudo a2ensite librenms.conf
sudo systemctl restart apache2

This handles URL rewriting rules, enabling required modules, disabling the default site, and activating the LibreNMS virtual host.

Step 8 – Finalize Installation

Almost there! To apply permissions and complete the set up:

sudo chown -R librenms:librenms /opt/librenms
sudo setfacl -dR -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/
sudo setfacl -R -m g::rwx /opt/librenms/rrd /opt/librenms/logs /opt/librenms/bootstrap/cache/ /opt/librenms/storage/

This recursively updates ownership and sets the ACLs.

Now restart all the required services for the changes to be applied:

sudo systemctl restart mysql 
sudo systemctl restart redis-server
sudo systemctl restart snmpd
sudo systemctl restart php7.4-fpm
sudo systemctl restart nginx

Or for apache:

sudo systemctl restart mysql
sudo systemctl restart redis-server 
sudo systemctl restart snmpd
sudo systemctl restart php7.4-fpm
sudo systemctl restart apache2

Step 9 – Log Into the Web UI

You‘re all set! Browse to your LibreNMS server IP address:

Sign in with the admin user and password you created.

Take a look around at the various dashboards, global settings, system health statistics, and more.

Congrats! You now have a high performance LibreNMS instance ready for robust network monitoring.

Troubleshooting Help

If you hit any snags installing LibreNMS, here are some tips for troubleshooting:

Web UI not accessible

• Check Nginx/Apache config syntax, restart service
• Verify PHP-FPM socket location match between Nginx/Apache and LibreNMS Pool conf
• Check for PHP errors in /var/log/php7.4-fpm.log

Connection issues to database

• Double check database credentials match .env file
• Attempt connecting from CLI using info from .env
• Review database logs in /var/log/mysql or /var/log/postgresql/

Metrics not displaying

• Confirm SNMP community strings set in /etc/snmp/librenms.snmpd.conf
• Validate Perl installed and rrdcached running with systemctl status rrdcached
• Check device was auto discovered or added manually
• Review device debug logs and SNMP walk output

Permission issues

If running into permissions errors for the librenms user, you may need to rerun:

sudo chown -R librenms:librenms /opt/librenms

API sluggishness

For API performance issues, enable Redis caching.

Check status with:

systemctl status redis-server

Then in .env set APP_REDIS_ENABLED=true

Extending LibreNMS Further

Now that you have LibreNMS operational, here are some expert recommendations for advanced areas to explore:

• Add the LibreNMS Agent on servers for richer OS & service metrics
• Enable alerts to proactively notify you of outages or thresholds
• Create custom dashboards and maps to match your infrastructure
• Integrate with external tools like chat platforms,ticketing systems, or billing software
• For Internet-facing setups, add TLS termination with trusted certificates
• Build custom SNMP poller modules or Integrate with 3rd party APIs
• For larger fleets, distribute polling load using distributed pollers

The community wiki also has some amazing examples from users that are definitely worth checking out.

Conclusion

I hope this guide has provided you with an in-depth LibreNMS installation walkthrough, best practices, and troubleshooting tips!

As you can see, LibreNMS is an extremely versatile open source tool for gaining visibility into your infrastructure. The global community behind it‘s development and support continues to add new integrations, features, and performance enhancements too.

Just be sure to tailor it to your environment and purposes for the most value. Customizing dashboards, alerts, polling triggers, and hardware support from the start will pay dividends down the road.

If you have any other questions about running LibreNMS in production, join the community forum – there is amazing expertise there always willing to help!

Or let me know in the comments and I‘m happy to provide my insight as well.