Network monitoring is a critical aspect of managing any IT infrastructure. At ENGINYRING, we understand the importance of having reliable monitoring tools to keep track of your network's performance and health. LibreNMS is a powerful, open-source network monitoring solution that provides comprehensive insights into your infrastructure. In this step-by-step tutorial, we will guide you through installing and configuring LibreNMS on your Virtual Server plan.

What is LibreNMS?

LibreNMS is a fully-featured network monitoring system that provides a wealth of features including automatic discovery of network devices, detailed performance metrics, alerting capabilities, and an intuitive web interface. It supports a wide range of devices and operating systems, making it an excellent choice for monitoring diverse network environments.

The main advantages of LibreNMS include:

  • Auto-discovery of network devices using CDP, LLDP, OSPF, BGP, SNMP, and ARP
  • Customizable alerting system with multiple notification methods
  • Detailed performance graphs and statistics
  • Support for a wide range of device types (routers, switches, servers, etc.)
  • Active community and regular updates

Prerequisites

Before we begin, ensure that your Virtual Server meets the following requirements:

  • A Linux-based operating system (we recommend Ubuntu 22.04 LTS for this tutorial)
  • Minimum 2GB RAM (4GB recommended for larger networks)
  • At least 20GB of storage space
  • A static IP address
  • Root or sudo access to your server

If you need assistance with Proxmox Server Management or setting up your virtual environment, our team at ENGINYRING can help you configure the perfect infrastructure for your monitoring needs.

Step 1: Update Your System

Start by updating your system packages to ensure you have the latest versions. This helps prevent compatibility issues and security vulnerabilities during the installation process.

sudo apt update
sudo apt upgrade -y

Explanation: The first command refreshes your package lists, while the second upgrades all installed packages to their latest versions. The -y flag automatically answers "yes" to any prompts during the upgrade process.

Step 2: Install Required Dependencies

LibreNMS requires several dependencies to function properly. Install them using the following commands:

sudo apt install -y software-properties-common
sudo add-apt-repository universe
sudo apt update
sudo apt install -y acl curl composer fping git graphviz imagemagick mariadb-client mariadb-server mtr-tiny nginx-full nmap php-cli php-curl php-fpm php-gd php-json php-mbstring php-mysql php-snmp php-xml php-zip rrdtool snmp snmpd whois unzip python3-pymysql python3-dotenv python3-redis python3-setuptools

Explanation: This comprehensive package installation includes:

  • Web server components: Nginx and PHP modules for serving the LibreNMS web interface
  • Database software: MariaDB for storing LibreNMS data
  • SNMP tools: For collecting data from network devices
  • Additional utilities: Tools like fping, nmap, and mtr for network operations
  • Python dependencies: Required for specific LibreNMS functionalities

Step 3: Configure MariaDB

Next, we need to configure the MariaDB server for LibreNMS. This includes setting up a dedicated database and user with appropriate permissions.

First, secure your MariaDB installation (recommended for new installations):

sudo mysql_secure_installation

Follow the prompts to set a root password and answer 'Y' to all security questions.

Now, let's create the database and user for LibreNMS:

sudo mysql -u root -p

Enter your MariaDB root password when prompted. At the MariaDB prompt, execute the following commands:

CREATE DATABASE librenms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;
exit;

Detailed Explanation:

  • The first line creates a new database named "librenms" with UTF8MB4 character encoding, which supports all Unicode characters including emojis
  • The second line creates a dedicated user for LibreNMS with a secure password (replace 'your_secure_password' with a strong password)
  • The third line grants this user full access to the librenms database
  • The fourth line applies the changes immediately

Security Note: Use a strong, unique password and never use the database root user for application access. Store your password in a secure location as you'll need it later.

Step 4: Install LibreNMS

Now we'll install LibreNMS by cloning the repository and setting the appropriate permissions:

sudo mkdir -p /opt/librenms
sudo chown www-data:www-data /opt/librenms
sudo git clone https://github.com/librenms/librenms.git /opt/librenms

Set the correct permissions using Access Control Lists (ACLs) to ensure LibreNMS can write to its directories:

sudo chmod 770 /opt/librenms
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/

Explanation: These commands set default and recursive ACLs on critical directories that LibreNMS needs to write to. The -d flag sets default ACLs for new files/directories, -R applies recursively to existing content, and -m g::rwx grants read, write, and execute permissions to the group.

Step 5: Configure PHP

Create a dedicated PHP-FPM pool for LibreNMS to isolate its PHP processes:

sudo cp /etc/php/8.1/fpm/pool.d/www.conf /etc/php/8.1/fpm/pool.d/librenms.conf

Note: If you're using a different PHP version, adjust the path accordingly (e.g., replace "8.1" with your version).

Edit the configuration file:

sudo nano /etc/php/8.1/fpm/pool.d/librenms.conf

Change the following settings (look for each setting and modify it):

[librenms]
user = www-data
group = www-data
listen = /run/php-fpm-librenms.sock
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35

Detailed Explanation:

  • Changing [www] to [librenms] renames the pool
  • The listen directive changes the socket path to avoid conflicts
  • Process management (pm) settings control how PHP-FPM spawns and manages worker processes:
    • pm.max_children: Maximum number of child processes
    • pm.start_servers: Number of child processes created at startup
    • pm.min_spare_servers: Minimum number of idle processes
    • pm.max_spare_servers: Maximum number of idle processes

Adjust the PHP settings for LibreNMS:

sudo nano /etc/php/8.1/fpm/php.ini

Find and modify the following values (use Ctrl+W to search in nano):

date.timezone = UTC
memory_limit = 512M
upload_max_filesize = 16M
post_max_size = 16M

Tip: Set the timezone to match your local timezone instead of UTC if preferred. For example, use 'America/New_York' for Eastern Time.

Restart PHP-FPM to apply the changes:

sudo systemctl restart php8.1-fpm

Step 6: Configure Nginx

Create a new Nginx server block configuration file for LibreNMS:

sudo nano /etc/nginx/sites-available/librenms

Add the following configuration:

server {
    listen 80;
    server_name librenms.example.com;
    root /opt/librenms/html;
    index index.php;

    charset utf-8;
    gzip on;
    gzip_types text/css application/javascript text/javascript application/x-javascript image/svg+xml text/plain text/xsd text/xsl text/xml image/x-icon;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php {
        include fastcgi.conf;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php-fpm-librenms.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

Important: Replace librenms.example.com with your server's actual domain name or IP address.

Configuration Breakdown:

  • The listen directive tells Nginx to listen on port 80
  • server_name specifies which requests this configuration handles
  • root points to LibreNMS's HTML directory
  • gzip settings enable compression for faster page loads
  • The location blocks define how different types of requests are handled
  • The PHP block passes PHP requests to the dedicated LibreNMS PHP-FPM socket we configured earlier

Enable the site and restart Nginx:

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

Step 7: Configure SNMP

Simple Network Management Protocol (SNMP) is crucial for LibreNMS to collect data from network devices. Let's configure the SNMP daemon on our server:

sudo nano /etc/snmp/snmpd.conf

Replace its contents with:

com2sec readonly default your_community_string
group MyROGroup v2c readonly
view all included .1
access MyROGroup "" any noauth exact all none none
syslocation Server Room, Main Office, City Name [40.7128, -74.0060]
syscontact Admin 
sysname LibreNMS-Server
extend distro /usr/local/bin/distro
extend hardware '/usr/bin/env bash -c "cat /sys/devices/virtual/dmi/id/product_name 2>/dev/null || echo unknown"'
extend manufacturer '/usr/bin/env bash -c "cat /sys/devices/virtual/dmi/id/sys_vendor 2>/dev/null || echo unknown"'
extend serial '/usr/bin/env bash -c "cat /sys/devices/virtual/dmi/id/product_serial 2>/dev/null || echo unknown"'

Critical Configuration Elements:

  • Community String: Replace your_community_string with a secure string of your choice. This acts like a password for SNMP access and should be treated as sensitive.
  • System Location: Update syslocation with your actual server location details and coordinates.
  • System Contact: Replace admin@example.com with your actual contact email.
  • The "extend" directives: These enable LibreNMS to collect additional system information.

Download the distro script required by the configuration:

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

Restart the SNMP service to apply the changes:

sudo systemctl restart snmpd

Verify SNMP is working correctly:

snmpwalk -v 2c -c your_community_string localhost system

You should see system information displayed. If you get errors, double-check your snmpd.conf file for syntax issues.

Step 8: Set Up LibreNMS Configuration

Copy the sample configuration file:

cd /opt/librenms
sudo cp config.php.default config.php
sudo chown www-data:www-data config.php

Edit the configuration file:

sudo nano config.php

Update the database connection details:

$config['db_host'] = 'localhost';
$config['db_user'] = 'librenms';
$config['db_pass'] = 'your_secure_password';
$config['db_name'] = 'librenms';

Important: Replace 'your_secure_password' with the password you set for the LibreNMS database user.

You can also customize additional settings in this file:

// Server timezone
$config['site_style'] = 'light';  // Interface theme (light/dark)
$config['update'] = 0;            // Disable auto-updates if required
$config['auth_mechanism'] = 'mysql'; // Authentication method

Step 9: Install LibreNMS Dependencies

Install Composer dependencies required by LibreNMS:

sudo su - www-data -c "cd /opt/librenms && ./scripts/composer_wrapper.php install --no-dev"

Explanation: This command runs as the www-data user to ensure proper file permissions and installs PHP dependencies defined in LibreNMS's composer.json file, excluding development dependencies.

Step 10: Set Up the LibreNMS Cron Job

Create a cron file for LibreNMS to enable scheduled tasks like data collection and alerts:

sudo cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms

Verify the cron job is set up correctly:

sudo cat /etc/cron.d/librenms

You should see various scheduled tasks with different intervals. These tasks handle device polling, alert processing, and maintenance operations.

Step 11: Set Up Log Rotation

Configure log rotation to prevent LibreNMS logs from growing too large:

sudo cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms

Step 12: Run the LibreNMS Install Script

Now, run the validation script to ensure everything is set up correctly:

cd /opt/librenms
sudo su - www-data -c "php /opt/librenms/validate.php"

This script will check your installation for common issues and provide guidance on how to fix them. Pay close attention to any "Error" messages and fix them before proceeding.

After resolving any issues identified by the validation script, initialize the database:

sudo su - www-data -c "php /opt/librenms/build-base.php"

Step 13: Complete the Web Installation

Open your web browser and navigate to your server's IP address or domain name. You should see the LibreNMS installation wizard. Follow these steps:

  1. Create an admin user with a strong password (use a combination of uppercase, lowercase, numbers, and special characters)
  2. Set your community string (use the same one you configured in your SNMP configuration)
  3. Configure your location and other preferences
  4. Complete the installation process

Security Note: After installation, consider setting up HTTPS with a valid SSL certificate to encrypt traffic to your LibreNMS instance. You can use Let's Encrypt for free certificates.

Step 14: Add Devices to Monitor

Once the installation is complete, you can start adding devices to monitor:

  1. Log in to the LibreNMS web interface
  2. Go to Devices > Add Device
  3. Enter the hostname or IP address of the device
  4. Select the SNMP version (usually v2c for most devices, consider v3 for higher security)
  5. Enter the community string
  6. Optionally, select a device group or location
  7. Click "Add Device"

Pro Tip: For large networks, you can use the auto-discovery feature to scan IP ranges:

  1. Go to Discover > Nets
  2. Add IP ranges in CIDR notation (e.g., 192.168.1.0/24)
  3. Configure discovery settings
  4. Click "Add" to begin discovery

Step 15: Configure Alerts and Notifications

To set up alerts:

  1. Go to Alerts > Alert Rules
  2. Click "Create Rule" to define conditions that trigger alerts
  3. Go to Alerts > Transport to configure how notifications are sent (email, Slack, Discord, etc.)
  4. Set up alert schedules if needed

Email Notification Setup:

  1. Go to Global Settings > Alerting
  2. Configure your email settings (SMTP server, port, credentials)
  3. Send a test email to verify configuration

Common Troubleshooting Tips

Here are solutions to common issues you might encounter:

Database Connection Issues

Symptom: "Cannot connect to database" error in web interface

Solutions:

  • Verify database credentials in config.php
  • Check MariaDB is running: sudo systemctl status mariadb
  • Ensure the librenms user has proper permissions: sudo mysql -u root -p GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost'; FLUSH PRIVILEGES;

SNMP Not Working

Symptom: Devices added but no data is collected

Solutions:

  • Verify SNMP is running: sudo systemctl status snmpd
  • Test SNMP locally: snmpwalk -v 2c -c your_community_string localhost system
  • Check firewall rules to ensure UDP ports 161/162 are open
  • Verify the community string matches between devices and configuration

Permission Issues

Symptom: "Permission denied" errors in logs

Solutions:

  • Reset directory permissions: sudo chown -R www-data:www-data /opt/librenms sudo chmod 770 /opt/librenms 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/

Web Interface Not Loading

Symptom: Blank page or 502 Bad Gateway error

Solutions:

  • Check Nginx status: sudo systemctl status nginx
  • Check PHP-FPM status: sudo systemctl status php8.1-fpm
  • Verify Nginx configuration: sudo nginx -t
  • Check error logs: sudo tail -f /var/log/nginx/error.log

High CPU or Memory Usage

Symptom: Server becoming slow or unresponsive

Solutions:

  • Adjust polling frequency in Global Settings > Poller
  • Increase PHP memory limit in php.ini
  • Optimize MariaDB for your server resources
  • Consider using distributed polling for larger deployments

Performance Optimization Tips

For better performance with LibreNMS, consider these optimizations:

  1. Database Optimization: Add these settings to /etc/mysql/mariadb.conf.d/50-server.cnf: [mysqld] innodb_file_per_table=1 innodb_buffer_pool_size=256M max_connections=200 tmp_table_size=64M max_heap_table_size=64M
  2. Faster polling: Enable RRDCached for improved performance with large installations
  3. Reduce polling frequency: For less critical devices, adjust polling to 5 or 15 minutes instead of the default 1 minute

Upgrading LibreNMS

To keep LibreNMS updated with the latest features and security fixes:

cd /opt/librenms
sudo ./daily.sh

Consider adding this to a weekly cron job for automatic updates.

Conclusion

Congratulations! You have successfully installed and configured LibreNMS on your Virtual Server from ENGINYRING. You now have a powerful network monitoring solution that provides comprehensive visibility into your network's performance and health.

For optimal server management, consider our Proxmox Server Management or cPanel Server Management services. We also offer reliable Web Hosting solutions if you're looking for managed hosting options.

If you encounter any issues or need assistance with your LibreNMS setup, don't hesitate to contact our support team. At ENGINYRING, we're committed to helping you get the most out of your virtual infrastructure.