LibreNMS is a powerful, open-source network monitoring tool designed for flexibility, scalability, and ease of use. It offers a wide range of features for monitoring devices, collecting performance metrics, and generating alerts, all while giving users full control over their data. This guide will walk you through deploying, configuring, and managing a self-hosted LibreNMS instance, covering installation methods, setting up a reverse proxy, managing logs, backups, and updates, and tapping into LibreNMS’s unique capabilities.
Installing LibreNMS
📦 Docker/Docker Compose Setup
Using Docker simplifies deployment and management. Here’s a docker-compose.yml tailored for LibreNMS:
version: "3.7"
services:
db:
image: mariadb:10.5
container_name: librenms-db
restart: unless-stopped
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: librenms
MYSQL_USER: librenms
MYSQL_PASSWORD: librenms
volumes:
- librenms-db-data:/var/lib/mysql
app:
image: librenms/librenms:latest
container_name: librenms-app
restart: unless-stopped
ports:
- "8000:8000"
environment:
DB_HOST: db
DB_NAME: librenms
DB_USER: librenms
DB_PASS: librenms
BASE_URL: http://localhost:8000
volumes:
- librenms-app-data:/data
- /etc/localtime:/etc/localtime:ro
depends_on:
- db
volumes:
librenms-db-data:
librenms-app-data:
Deploy LibreNMS using the following commands:
docker compose up -d
This will spin up both the database (mariadb) and the LibreNMS application. Access LibreNMS via http://localhost:8000.
🚀 Manual Installation
For a manual Linux installation (e.g., Ubuntu 22.04), execute the following steps:
## Update system and install dependencies
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl unzip apache2 mariadb-server php php-cli php-mysql php-gd php-curl php-mbstring php-xml composer
## Create a database and user for LibreNMS
sudo mysql -u root -p -e "
CREATE DATABASE librenms CHARACTER SET utf8 COLLATE utf8_general_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'librenms';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;"
## Add the LibreNMS user and clone the repository
sudo useradd -r -M -d /opt/librenms librenms
sudo git clone https://github.com/librenms/librenms.git /opt/librenms
sudo chown -R librenms:librenms /opt/librenms
## Install Composer dependencies
cd /opt/librenms
sudo -u librenms composer install --no-dev
## Set up the web server
sudo cp /opt/librenms/librenms.apache /etc/apache2/sites-available/librenms.conf
sudo ln -s /etc/apache2/sites-available/librenms.conf /etc/apache2/sites-enabled/
sudo a2enmod rewrite
sudo systemctl restart apache2
Access LibreNMS via the server’s IP or domain.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To serve LibreNMS through Nginx, create a server block:
sudo nano /etc/nginx/sites-available/librenms
Add the following configuration:
server {
listen 80;
server_name librenms.example.com;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Enable the configuration:
sudo ln -s /etc/nginx/sites-available/librenms /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure the site with Let's Encrypt:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d librenms.example.com
Automate renewal:
sudo crontab -e
## Add:
0 0 * * 0 certbot renew --quiet
🛠️ Testing and Reloading Nginx
Test the Nginx configuration:
sudo nginx -t
sudo systemctl reload nginx
Access LibreNMS via https://librenms.example.com.
Logging and Debugging LibreNMS
🗃️ Enabling Debug Logs
Enable verbose debugging to troubleshoot issues:
nano /opt/librenms/config.php
## Add:
$config['debug'] = true;
📄 Viewing Logs
For Docker users:
docker logs librenms-app
For manual installations:
tail -f /opt/librenms/logs/librenms.log
🛠️ Troubleshooting Common Issues
Check for database connection errors:
sudo mysql -u librenms -p librenms -e "SHOW TABLES;"
Ensure all dependencies are installed:
php /opt/librenms/scripts/composer_wrapper.php install --no-dev
Backup and Restore
🗂️ File-Based Backups
Backup the LibreNMS directory:
tar -czvf librenms-backup-$(date +%F).tar.gz /opt/librenms
🔄 Database Backups
Export the database:
mysqldump -u librenms -p librenms > librenms-db-backup-$(date +%F).sql
Restore the database:
mysql -u librenms -p librenms < librenms-db-backup.sql
📅 Automated Backup Scripts
Schedule backups with a cron job:
crontab -e
## Add:
0 2 * * * /usr/bin/mysqldump -u librenms -plibrenms librenms > /backups/librenms-db-$(date +\%F).sql
Updating and Upgrading LibreNMS
⬆️ Updating Docker Images
Update LibreNMS with Docker:
docker compose pull
docker compose up -d
🛠️ Manual Updates
Update a manual LibreNMS installation:
cd /opt/librenms
sudo git pull
sudo -u librenms composer install --no-dev
php artisan migrate
🔍 Checking for Updates
View available updates within the web UI under the "Updates" section or by running:
php /opt/librenms/daily.sh
Leveraging LibreNMS’s Unique Features
🔧 Enabling APIs
Activate the API and generate authentication tokens:
nano /opt/librenms/config.php
## Add:
$config['api']['enabled'] = true;
Test the API with curl:
curl -X GET -H "X-Auth-Token: YOUR_API_TOKEN" http://localhost/api/v0/devices
🌟 Advanced Configurations
Integrate third-party alerting tools like Slack:
nano /opt/librenms/config.php
## Add:
$config['alerts']['slack']['webhook'] = 'https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK';
Wrapping Up
Deploying, configuring, and managing LibreNMS gives you full control over network monitoring and performance analytics. By following the steps in this guide, you can self-host LibreNMS effectively, secure it with Nginx, troubleshoot issues, and utilize its advanced features. Start exploring its robust functionality to monitor your infrastructure seamlessly!
