LibreNMS is an open-source and fully-featured networking monitoring tool that provides a wide range of monitoring features and capabilities for your network devices.
Key features include:
- Automatic discovery of your entire network using ARP, SNMP, BGP, OSPF, LLDP, and FDP protocols.
- An alerting system that is highly customizable and can be tweaked to send alerts via email, Slack, and other channels.
- A simple, and easily customizable dashboard.
- A fully-extensive API for managing and graphing data from your monitoring server.
- Extensive device support – Supports a wide range of hardware vendors such as Cisco, Juniper, HP, and many more.
- Automatic updates and bug fixes.
- Multi-Factor authentication.
- Native support for Android and iOS Apps.
- and many more.
In this guide, we will install the LibreNMS monitoring tool on Debian 11/10.
Step 1: Install Nginx, MariaDB and PHP
To start off, refresh the repositories and install the prerequisite packages as follows:
$ sudo apt update $ sudo apt install software-properties-common wget apt-transport-https
The next step is to install Nginx and additional packages such as curl, git, SNMP, and python packages which will be required by the LibreNMS monitoring tool.
So, run the command:
$ sudo apt install nginx-full curl acl fping graphviz composer git imagemagick mtr-tiny nmap python3-pip python3-memcache python3-mysqldb python3-dotenv python3-pymysql rrdtool snmp snmpd whois python3-redis python3-systemd python3-setuptools python3-systemd
Next, install the MariaDB database server, PHP, and additional PHP extensions which are needed by the LibreNMS monitoring tool.
$ sudo apt install mariadb-server php php-fpm php-cli php-xml php-common php-gd php-json php-snmp php-pdo php-mysql php-zip php-curl php-mbstring php-pear php-bcmath
Once installed, be sure to enable Nginx, php-fpm, MariaDB, and SNMP services as shown.
$ sudo systemctl enable --now nginx $ sudo systemctl enable --now php7.4-fpm $ sudo systemctl enable --now mariadb $ sudo systemctl enable --now snmpd.service
Step 2: Configure TimeZone for PHP
The next step requires us to configure or set the PHP timezone. This is done in the php.ini file which is the default PHP configuration file.
Access the php.ini configuration files in the following paths using your favorite editor.
$ sudo nano /etc/php/7.4/fpm/php.ini $ sudo nano /etc/php/7.4/cli/php.ini
Navigate to the date.timezone parameter and set it to your timezone. To get a comprehensive list of all the supported Timezone, head over to the official PHP site.
In this example, we are setting the timezone to UTC.
date.timezone = UTC
Then save the changes and exit the files.
Step 3: Create a Database for LibreNMS
In this step, we will create a database for LibreNMS installation. But first, let us secure the database secure by running the following script:
$ sudo mysql_secure_installation
Follow the detailed prompts that will guide you on how to create the MariaDB root password, remove anonymous users and test the database and finally disallow remote root login.
Next, log into MariaDB:
$ sudo mysql -u root -p
Then run the following commands to create a database and database user and assign all privileges to the database user.
CREATE DATABASE librenms_db CHARACTER SET utf8 COLLATE utf8_unicode_ci; CREATE USER 'librenms_user'@'localhost' IDENTIFIED BY '[email protected]'; GRANT ALL PRIVILEGES ON librenms_db.* TO 'librenms_user'@'localhost';
Then save the changes and exit the MariaDB prompt.
FLUSH PRIVILEGES; EXIT;
Some database fine-tuning is needed. So open the MariaDB configuration file shown:
$ sudo vim /etc/mysql/mariadb.conf.d/50-server.cnf
Then paste the following lines of code in the ‘mysqld’ section.
Save the changes and exit the file. To apply the changes, restart the database server.
$ sudo systemctl restart mariadb
Step 4: Add LibreNMS User
You also need to create a new LibreNMS user. This is the user that LibreNMS will be running under. In this example, we are creating a user called librenms with the following attributes.
$ sudo useradd librenms -d /opt/librenms -M -r -s /bin/bash $ sudo usermod -aG librenms www-data
-doption sets the home directory for the librenms user to the /opt/librenms directory.
-roption configures the librenms user as the system user.
-Moption skips creating a home directory for the user since it has already been defined using the
-soption specifies the type of shell, in this case, bash.
Step 5: Clone LibreNMS Git Repository
Shifting gears, we are now going to clone the LibreNMS git repository to begin setting it up.
Run the following commands to clone the Git repository
$ cd /opt $ sudo git clone https://github.com/librenms/librenms.git
Then switch back to the home directory.
$ cd ~
Next, we need to assign directory ownership and permissions to the Librenms home directory. To achieve this, run the following commands:
$ sudo chown -R librenms:librenms /opt/librenms $ sudo chmod 771 /opt/librenms
Additionally, modify the access control lists for the Librenms home directory using the setfacl command. This grants the Librenms group permission to read and write on the subdirectories in the home directory.
$ sudo setfacl -d -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/
Step 6: Install PHP Dependencies
Some dependencies are required by PHP during the setup of the LibreNMS monitoring tool. To do this, you need to be logged in as the librenmsuser.
$ sudo su - librenms
Next, install all the PHP dependencies as follows.
$ ./scripts/composer_wrapper.php install --no-dev
Once the installation of the dependencies is complete, exit the librenms user.
Step 7: Configure PHP-FPM for LibreNMS Installation
Moving on, we need to make a few changes to PHP-FPM in order to support LibreNMS.
To accomplish this. Copy the ‘www.conf‘ file which is the default pool configuration file to the ‘librenms.conf‘ file as follows.
$ sudo cp /etc/php/7.4/fpm/pool.d/www.conf /etc/php/7.4/fpm/pool.d/librenms.conf
Next, edit the ‘librenms.conf‘ file.
$ sudo nano /etc/php/7.4/fpm/pool.d/librenms.conf
Change the user and group parameters to librenms as shown
user = librenms group = librenms
Next, modify the listen attribute to /run/php-fpm-librenms.sock as follows.
listen = /run/php-fpm-librenms.sock
Save the changes and exit the configuration. Be sure to restart the PHP-FPM service to apply the changes.
$ sudo systemctl restart php7.4-fpm
Step 8: Configure the SNMP Daemon
The SNMP protocol is a TCP/IP protocol that collects and organizes metrics or information from managed devices across a network.
Most monitoring tools such as Cacti leverage the SNMP service to collect information from remote hosts. And so does LibreNMS.
To configure the SNMP service, go ahead and copy the snmpd.conf.example file to the /etc/snmp/snmpd.conf file.
$ sudo cp /opt/librenms/snmpd.conf.example /etc/snmp/snmpd.conf
Next, edit the snmpd.conf file.
$ sudo vim /etc/snmp/snmpd.conf
Locate the RANDOMSTRINGGOESHERE string.
com2sec readonly default RANDOMSTRINGGOESHERE
Change it to librenms.
com2sec readonly default librenms
Save the changes and exit.
Next, download the distro file, which is a file that automatically detects the OS of the managed nodes and distinguishes its distribution.
$ sudo curl -o /usr/bin/distro https://raw.githubusercontent.com/librenms/librenms-agent/master/snmp/distro
Make it executable and restart the SNMP service.
$ sudo chmod +x /usr/bin/distro $ sudo systemctl restart snmpd
Step 9: Configure Nginx for LibreNMS
With Nginx as our preferred web server, we need to go an extra step and configure it in order to server LibreNMS.
First, we will create an Nginx server block as shown.
$ sudo nano /etc/nginx/sites-available/librenms
Paste the following lines of codes. For the server_name attribute, provide your server’s registered domain name or IP address.
Save the changes and exit the configuration file. Next, enable the Nginx server block by creating a symbolic link as shown.
$ sudo ln -s /etc/nginx/sites-available/librenms /etc/nginx/sites-enabled/
Then restart Nginx to apply the changes made to the configuration.
$ sudo systemctl restart nginx
Additionally, you can confirm that all the Nginx settings are okay by running the command:
$ sudo nginx -t
Step 10: Copy the Logrotate and Cron Configuration
By default, LibreNMS stores its logs in the /opt/librenms/logs directory. Over time, this can easily fill up and present space problems. To prevent this, rotation of old log files is recommended.
Therefore copy the logrotate file in the LibreNMS directory to the /etc/logrotate.d/ directory.
$ sudo cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms
Equally important, copy the cron job file as follows to allow automatic polling & discovery of new devices
$ sudo cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms
Step 11: Complete the Setup of LibreNMS from a Browser
To complete the setup from a browser, head over to the following URL:
This takes you to the pre-installation checklist shown. If all look good, click on the ‘database’ icon to the right.
Be sure to fill in all the database details and click ‘Check Credentials’.
Once the database details have been validated, click on ‘Build Database’.
When you get past this step, click the next icon to create an Admin user. Provide the username, password, and the email of the Admin user and click ‘Add user’.
Finally, click on the last button to finish the installation.
You will bump into this error informing you that the installer ‘Failed to write file: /opt/librenms/.env’.
But don’t worry. Simply manually update the /opt/librenms/.env file afresh with the database details provided. These details will vary in your case.
So, access the file.
$ sudo nano /opt/librenms/.env
Delete all the content in the file and paste the details provided above into the file and save the changes.
Next head back and click the ‘Retry’ button. This takes you to the LibreNMS login page. Provide the login credentials and click ‘Login’.
Once logged in you will get such a dashboard. From here, you can begin adding your hosts and monitor various metrics.
And that’s it. In this guide, we have walked you through the installation of the LibreNMS monitoring tool on Debian 11/10.