Aug 5, 2024 3 min read

LibreNMS: A Beginner-Friendly Guide to Self-Hosting

LibreNMS: A Beginner-Friendly Guide to Self-Hosting
Table of Contents

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!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.