
How to Install and Configure LibreNMS on Your Virtual Server
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 processespm.start_servers
: Number of child processes created at startuppm.min_spare_servers
: Minimum number of idle processespm.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 handlesroot
points to LibreNMS's HTML directorygzip
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:
- Create an admin user with a strong password (use a combination of uppercase, lowercase, numbers, and special characters)
- Set your community string (use the same one you configured in your SNMP configuration)
- Configure your location and other preferences
- 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:
- Log in to the LibreNMS web interface
- Go to Devices > Add Device
- Enter the hostname or IP address of the device
- Select the SNMP version (usually v2c for most devices, consider v3 for higher security)
- Enter the community string
- Optionally, select a device group or location
- Click "Add Device"
Pro Tip: For large networks, you can use the auto-discovery feature to scan IP ranges:
- Go to Discover > Nets
- Add IP ranges in CIDR notation (e.g., 192.168.1.0/24)
- Configure discovery settings
- Click "Add" to begin discovery
Step 15: Configure Alerts and Notifications
To set up alerts:
- Go to Alerts > Alert Rules
- Click "Create Rule" to define conditions that trigger alerts
- Go to Alerts > Transport to configure how notifications are sent (email, Slack, Discord, etc.)
- Set up alert schedules if needed
Email Notification Setup:
- Go to Global Settings > Alerting
- Configure your email settings (SMTP server, port, credentials)
- 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:
- 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
- Faster polling: Enable RRDCached for improved performance with large installations
- 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.