🚀 LibreNMS Containerized Deployment

Production-Ready LibreNMS Deployment

Automated network monitoring for RHEL 10 using Podman and Quadlet

Key Features

🔐 Automated HTTPS with self-signed certificate generation • 🐳 Podman containerization with Quadlet systemd integration • 🔄 Idempotent deployment safe to re-run • 💾 Persistent storage with bind mounts • 🛡️ SELinux enforcing with proper contexts • 🔥 Auto-configured firewalls (firewalld/ufw/iptables/nftables) • 📡 SNMP trap daemon with testing utilities • 🏥 Comprehensive health checks • 🗑️ Clean uninstall with data preservation • 🤖 Helper scripts for common operations • 🔒 Secrets management via environment variables • 📚 Complete documentation with troubleshooting guides

📋 Table of Contents

🎯 Overview
🏗️ Architecture
📦 Requirements
💾 Persistent Storage & Bind Mounts
🚀 Quick Start
⚙️ Configuration
🔐 HTTPS/SSL Support
🔧 Usage
🛡️ Security
🔥 Firewall Configuration
📊 Health Checks
🗑️ Uninstallation
🆘 Troubleshooting
📚 Helper Scripts
🧪 Testing SNMP Traps
📝 License

🎯 Overview

This project provides fully automated deployment of LibreNMS (network monitoring system) using containerized architecture on RHEL 10. It leverages Podman for rootless-capable container management and Quadlet for native systemd service integration, with comprehensive automation for security, networking, and operations.

Why This Solution?

🔐 Automated HTTPS: Self-signed certificates auto-generated, configured, and mounted
✅ Idempotent: Safe to re-run without causing errors or duplicating resources
🏭 Production-ready: SELinux enforcing with semanage, auto-configured firewalls
⚡ Fully Automated: Zero-touch deployment from prerequisites to health checks
💾 Persistent Data: Bind mounts at /opt/librenms survive reboots and uninstalls
🔒 Security First: Complex random database passwords, secrets in .env, never in git
🔥 Smart Firewall: Auto-detects and configures firewalld/ufw/iptables/nftables
📡 SNMP Ready: Includes trap daemon with built-in testing utilities
🏥 Health Monitoring: Comprehensive validation of all components
🛠️ Operational Tools: Helper scripts for adding hosts, testing traps
🗑️ Clean Removal: Uninstall with optional data preservation or complete wipe
📚 Well Documented: Extensive guides, troubleshooting, and visual documentation

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         RHEL 10 Host                            │
├─────────────────────────────────────────────────────────────────┤
│                         Internet/Network                        │
│                               ▼                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │            Nginx Reverse Proxy (When HTTPS enabled)        │ │
│  │            🔐 SSL/TLS Termination                          │ │
│  │                                                            │ │
│  │  TCP 80 (HTTP) ───────────► 301 Redirect to HTTPS        │ │
│  │  TCP 443 (HTTPS) ──────────► Forward to LibreNMS:8000    │ │
│  └────────────────────────────────────────────────────────────┘ │
│                               │                                 │
│  ┌────────────────────────────┼─────────────────────────────┐  │
│  │        Podman Network: librenms-net                       │  │
│  │                            │                              │  │
│  │  ┌──────────────┐  ┌───────▼──────┐  ┌──────────────┐   │  │
│  │  │   MariaDB    │  │  LibreNMS    │  │    Redis     │   │  │
│  │  │ 🗄️ Database  │  │  🌐 Web App  │  │  💨 Cache    │   │  │
│  │  │              │  │              │  │              │   │  │
│  │  │ Port: 3306   │  │ Port: 8000   │  │ Port: 6379   │   │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘   │  │
│  │         │                 │                               │  │
│  │         └─────────┬───────┴─────────────────┐            │  │
│  │                   │                         │            │  │
│  │         ┌─────────▼────────────┐  ┌─────────▼─────────┐  │  │
│  │         │  SNMP Trap Daemon    │  │  Nginx Reverse    │  │  │
│  │         │  📡 Trap Handler     │  │  Proxy (HTTPS)    │  │  │
│  │         │                      │  │                   │  │  │
│  │         │  UDP Port: 162       │  │  Ports: 80, 443   │  │  │
│  │         └──────────────────────┘  └───────────────────┘  │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │              Systemd Quadlet Services                     │ │
│  │  • librenms-db.service          • librenms.service       │ │
│  │  • librenms-redis.service       • librenms-snmptrapd.s.. │ │
│  │  • librenms-nginx-proxy.service (when HTTPS enabled)     │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │         Persistent Storage: /opt/librenms                 │ │
│  │  • db/          • logs/            • config/              │ │
│  │  • rrd/         • plugins/         • alerting-templates/  │ │
│  │  • certs/       • nginx-proxy/     (SSL configs)          │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │                   Firewall Rules                          │ │
│  │  • UDP 161 (SNMP)        • UDP 162 (SNMP Traps)          │ │
│  │  • TCP 80 (HTTP)         • TCP 443 (HTTPS) 🔐            │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │         SSL/TLS Certificates (if HTTPS enabled)           │ │
│  │  Auto-generated self-signed in: /opt/librenms/certs/     │ │
│  │  • librenms.crt  • librenms.key                           │ │
│  │  Reverse proxy config: /opt/librenms/nginx-proxy/        │ │
│  └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

📦 Requirements

Operating System

Primary: RHEL 10.1 (fully tested) ✅
Secondary: Ubuntu 22.04 (best-effort) ⚠️

System Resources

CPU: 2+ cores recommended
RAM: 4GB minimum, 8GB+ recommended
Disk: 20GB+ for LibreNMS data and RRD files
Network: Internet access for container image pulls

Pre-installed Software

The deployment script will automatically install these if missing:

Podman (4.0+) - Container runtime
net-snmp & net-snmp-utils - SNMP tools for monitoring
policycoreutils-python-utils - SELinux management (semanage)
firewalld - Firewall management (or ufw/iptables/nftables)
openssl - SSL/TLS certificate generation and management
curl - HTTP client for health checks and testing
tar - Archive utility for backup/restore operations

Privileges

Root or sudo access required for installation

💾 Persistent Storage & Bind Mounts

All LibreNMS data is stored in persistent bind mounts at /opt/librenms/ to ensure data survives container restarts and host reboots.

Storage Structure

/opt/librenms/
├── db/                      (MariaDB database files)
├── logs/                    (Application and trap logs)
├── rrd/                     (RRD graph data)
├── config/                  (LibreNMS configuration)
├── plugins/                 (Installed plugins)
├── alerting-templates/      (Alert notification templates)
├── monitoring-plugins/      (Monitoring check plugins)
├── certs/                   (SSL certificates - if HTTPS enabled)
├── nginx/                   (LibreNMS nginx files - extracted from container)
└── nginx-proxy/             (Reverse proxy config - if HTTPS enabled)

Container Bind Mounts

MariaDB Container (`librenms-db`)

Host Path	Container Path	Mode	Purpose
`/opt/librenms/db`	`/var/lib/mysql`	RW	Database storage

LibreNMS Container (`librenms`)

Host Path	Container Path	Mode	Purpose
`/opt/librenms/logs`	`/data/logs`	RW	Application logs
`/opt/librenms/rrd`	`/data/rrd`	RW	RRD time-series data
`/opt/librenms/config`	`/data/config`	RW	Configuration files
`/opt/librenms/plugins`	`/opt/librenms/html/plugins`	RW	Web plugins
`/opt/librenms/alerting-templates`	`/opt/librenms/resources/templates`	RW	Alert templates
`/opt/librenms/monitoring-plugins`	`/usr/lib/monitoring-plugins`	RW	Monitoring checks

SNMP Trap Daemon Container (`librenms-snmptrapd`)

Host Path	Container Path	Mode	Purpose
`/opt/librenms/logs`	`/data/logs`	RW	Trap daemon logs

Nginx Reverse Proxy Container (`librenms-nginx-proxy`)

Host Path	Container Path	Mode	Purpose
`/opt/librenms/nginx-proxy/nginx.conf`	`/etc/nginx/nginx.conf`	RO	Reverse proxy config
`/opt/librenms/certs`	`/etc/nginx/certs`	RO	SSL certificates

*Only deployed when LIBRENMS_ENABLE_HTTPS=true

SELinux Contexts

All bind mounts are configured with proper SELinux contexts:

Label: container_file_t
Mode: :Z (private unshared volume)
Tool: semanage (persistent across reboots)

Backup Considerations

To backup all LibreNMS data, simply backup /opt/librenms/:

# Backup
sudo tar -czf librenms-backup-$(date +%Y%m%d).tar.gz /opt/librenms/

# Restore
sudo tar -xzf librenms-backup-YYYYMMDD.tar.gz -C /

Disk Space Monitoring

Monitor disk usage of persistent storage:

# Check total usage
du -sh /opt/librenms/

# Check per-directory usage
du -sh /opt/librenms/*

# Check RRD data growth (typically largest)
du -sh /opt/librenms/rrd/

📚 For detailed storage planning: See Storage Sizing Guide for:

Storage requirements by device count
Growth rate formulas
LVM setup procedures
Capacity planning examples

🚀 Quick Start

1️⃣ Clone the Repository

git clone https://github.com/yourusername/deploy-containerize-libreNMS.git
cd deploy-containerize-libreNMS

2️⃣ Configure Environment

# Copy the environment template
cp env-example .env

# Edit with your settings
vi .env

Required Configuration:

LIBRENMS_DB_PASSWORD: Database password
MYSQL_ROOT_PASSWORD: MySQL root password
LIBRENMS_ADMIN_USER: Admin username
LIBRENMS_ADMIN_PASSWORD: Admin password
LIBRENMS_BASE_URL: Your server URL (e.g., http://192.168.1.100)
LIBRENMS_BIND_IP: Bind IP (use 0.0.0.0 for all interfaces)

3️⃣ Deploy LibreNMS

sudo ./scripts/deploy-librenms.sh

This will:

✅ Install all dependencies
✅ Configure firewall rules
✅ Create persistent storage
✅ Set up SELinux contexts
✅ Deploy containers via Quadlet
✅ Enable and start services
✅ Run health check

4️⃣ Access LibreNMS

Open your browser and navigate to:

HTTP: http://YOUR_SERVER_IP
HTTPS: https://YOUR_SERVER_IP (if enabled in .env)

Default Credentials (if using defaults from .env):

Username: admin
Password: (as set in LIBRENMS_ADMIN_PASSWORD)

Enable HTTPS (Optional): Set LIBRENMS_ENABLE_HTTPS=true in .env before deploying

⚙️ Configuration

Environment Variables

The .env file contains all configuration. Never commit this file to git!

Core Settings

# Database
LIBRENMS_DB_PASSWORD=your_secure_password
MYSQL_ROOT_PASSWORD=your_secure_root_password

# Admin Account
LIBRENMS_ADMIN_USER=admin
LIBRENMS_ADMIN_PASSWORD=your_admin_password

# Network
LIBRENMS_BASE_URL=http://192.168.1.100
LIBRENMS_BIND_IP=0.0.0.0

Container Images

# Use specific versions for production
LIBRENMS_IMAGE=docker.io/librenms/librenms:latest
MARIADB_IMAGE=docker.io/library/mariadb:10.11
REDIS_IMAGE=docker.io/library/redis:7-alpine

Optional: Email Alerts

LIBRENMS_SMTP_HOST=smtp.gmail.com
LIBRENMS_SMTP_PORT=587
LIBRENMS_SMTP_USER=your_email@gmail.com
LIBRENMS_SMTP_PASSWORD=your_app_password

Optional: Resource Limits

Purpose: Prevent containers from consuming excessive CPU/memory

When to use:

Monitoring 50+ devices
Shared hosting environments
Production deployments
Resource-constrained environments

Configuration:

# Enable resource limits
RESOURCE_LIMITS_ENABLED=true

# CPU quotas (percentage of cores)
LIBRENMS_DB_CPU_QUOTA=200%       # 2 cores for database
LIBRENMS_CPU_QUOTA=300%          # 3 cores for LibreNMS
LIBRENMS_REDIS_CPU_QUOTA=100%    # 1 core for Redis

# Memory limits
LIBRENMS_DB_MEMORY_MAX=2G        # 2 GB for database
LIBRENMS_MEMORY_MAX=4G           # 4 GB for LibreNMS
LIBRENMS_REDIS_MEMORY_MAX=512M   # 512 MB for Redis

Recommended limits by device count:

Device Count	DB CPU/Memory	LibreNMS CPU/Memory	Redis CPU/Memory
10-50	200% / 2G	300% / 4G	100% / 512M
50-100	400% / 4G	600% / 8G	200% / 1G
100-500	600% / 8G	800% / 16G	300% / 2G

📚 Detailed guides:

Resource Limits Documentation - CPU quota, memory limits, performance tuning
SELinux & Poller Fixes - fping errors, poller not running, AVC denials

🔐 HTTPS/SSL Support

Automated Self-Signed Certificates with Nginx Reverse Proxy

This deployment automatically generates and configures HTTPS with self-signed certificates using an nginx reverse proxy for SSL termination.

Enable HTTPS:

Edit .env file:
```
LIBRENMS_ENABLE_HTTPS=true
```
Deploy:
```
sudo ./scripts/deploy-librenms.sh
```

Access LibreNMS:

https://your-server-ip    (HTTPS - uses self-signed cert)
http://your-server-ip     (HTTP - redirects to HTTPS)

Architecture:

Browser → Nginx Reverse Proxy (port 443) → LibreNMS (port 8000)
          🔐 SSL/TLS Termination          HTTP (internal only)

What Happens Automatically:

✅ Generates 10-year self-signed certificate (RSA 2048-bit, SHA-256)
✅ Stores certificates in /opt/librenms/certs/ (persistent bind mount)
✅ Creates nginx reverse proxy container (librenms-nginx-proxy)
✅ Configures SSL termination with TLS 1.2 and 1.3
✅ HTTP (port 80) automatically redirects to HTTPS (port 443)
✅ Mounts certificates into reverse proxy container
✅ Opens firewall ports 80 and 443
✅ Adds security headers (HSTS, X-Frame-Options, etc.)
✅ Detects existing certificates and reuses them

Certificate Location:

/opt/librenms/certs/
├── librenms.crt  (SSL certificate - public)
├── librenms.key  (Private key - secure)

Browser Warning: Self-signed certificates trigger browser security warnings - this is normal for internal deployments. Click "Advanced" → "Proceed" to accept.

For Details: See SSL Certificates Documentation

Generate Certificates Manually:

sudo ./scripts/installer-scripts-additional/generate-ssl-cert.sh \
  --domain librenms.local --ip 192.168.1.100

🔧 Usage

Deployment Commands

# Standard deployment
sudo ./scripts/deploy-librenms.sh

# Dry-run (see what would be done)
sudo ./scripts/deploy-librenms.sh --dry-run

# Skip health check
sudo ./scripts/deploy-librenms.sh --skip-health-check

Service Management

# Check service status
systemctl status librenms.service
systemctl status librenms-db.service
systemctl status librenms-redis.service
systemctl status librenms-snmptrapd.service

# View logs
journalctl -u librenms.service -f
podman logs -f librenms

# Restart services
systemctl restart librenms.service

Container Management

# List running containers
podman ps

# Execute commands in container
podman exec -it librenms bash

# View container logs
podman logs librenms
podman logs librenms-snmptrapd

🛡️ Security

Secrets Management

✅ All secrets stored in .env file
✅ .env excluded from git via .gitignore
✅ Pre-commit hooks scan for accidental secret commits
✅ No credentials hardcoded in scripts

SELinux Configuration

The deployment script configures SELinux properly:

# Verify SELinux status
getenforce  # Should show "Enforcing"

# Check contexts
ls -Z /opt/librenms

# View SELinux denials
ausearch -m avc -ts recent

Important: Uses semanage (permanent) not chcon (temporary)!

Firewall Rules

Automatically configured ports:

UDP 161: SNMP polling
UDP 162: SNMP traps
TCP 80: HTTP web interface
TCP 443: HTTPS (if configured)

🔥 Firewall Configuration

The script auto-detects your firewall system:

Firewalld (RHEL default)

# View rules
sudo firewall-cmd --list-all

# Verify ports
sudo firewall-cmd --list-ports

UFW (Ubuntu)

# View rules
sudo ufw status

# Verify ports
sudo ufw status numbered

Manual Configuration (if auto-detection fails)

Firewalld:

sudo firewall-cmd --permanent --add-port=161/udp
sudo firewall-cmd --permanent --add-port=162/udp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload

UFW:

sudo ufw allow 161/udp
sudo ufw allow 162/udp
sudo ufw allow 80/tcp

📊 Health Checks

Run the health check script to validate your deployment:

sudo ./scripts/health-check.sh

# Verbose mode
sudo ./scripts/health-check.sh --verbose

What It Checks

✅ Container status (running/stopped)
✅ Systemd services (active/inactive)
✅ Persistent storage directories
✅ Podman network configuration
✅ Firewall rules
✅ SELinux contexts
✅ Web interface accessibility
✅ Database connectivity

Example Output

======================================================================
  LibreNMS Health Check
======================================================================

[INFO] Checking container status...
[✅ PASS] Container librenms-db is running
[✅ PASS] Container librenms-redis is running
[✅ PASS] Container librenms is running
[✅ PASS] Container librenms-snmptrapd is running

======================================================================
  Health Check Summary
======================================================================
Passed: 24
Failed: 0

✅ All checks passed!

🗑️ Uninstallation

Standard Uninstall (Preserves Data)

sudo ./scripts/uninstall-librenms.sh

This removes:

❌ All containers
❌ Systemd service files
❌ Podman network
❌ Firewall rules
✅ Data preserved at /opt/librenms

Complete Removal (Including Data)

sudo ./scripts/uninstall-librenms.sh --remove-data

⚠️ WARNING: This permanently deletes all LibreNMS data!

Keep Firewall Rules

sudo ./scripts/uninstall-librenms.sh --keep-firewall

📚 Backup Before Uninstall: See Backup and Restore Guide for:

VM snapshot procedures (fastest)
LVM snapshot procedures
Tar backup procedures
Complete restore procedures

🆘 Troubleshooting

Containers Won't Start

Check logs:

journalctl -u librenms.service -n 50
podman logs librenms

Common causes:

Missing .env file
Invalid database password
Port conflicts (80, 161, 162 already in use)
SELinux denials

Web Interface Not Accessible

Verify service is running:

systemctl status librenms.service
curl http://localhost:80
# Or for HTTPS:
curl -k https://localhost:443

Check firewall:

sudo firewall-cmd --list-ports

See Firewall Configuration for expected ports and manual configuration.

Check container port binding:

podman port librenms
# Should show: 8000/tcp -> 0.0.0.0:80
# If HTTPS enabled: 8443/tcp -> 0.0.0.0:443

HTTPS Not Working

Check certificates exist:

ls -la /opt/librenms/certs/
# Should show: librenms.crt and librenms.key

Check nginx reverse proxy:

podman ps | grep nginx-proxy
podman logs librenms-nginx-proxy

Test certificate:

openssl s_client -connect localhost:443 -showcerts

Check if HTTPS is enabled in reverse proxy:

podman exec librenms-nginx-proxy cat /etc/nginx/nginx.conf | grep 443

SNMP Traps Not Received

Check trap daemon:

systemctl status librenms-snmptrapd.service
podman logs librenms-snmptrapd

Test connectivity:

./scripts/post-deploy/test-snmptraps.sh

Verify firewall:

sudo firewall-cmd --list-ports | grep 162

SELinux Denials

View denials:

ausearch -m avc -ts recent

Fix contexts:

sudo restorecon -Rv /opt/librenms

Database Connection Issues

Check database container:

podman exec -it librenms-db mysql -u root -p

Verify network:

podman network inspect librenms-net

📚 Helper Scripts

Add Monitored Host

Add devices to LibreNMS for monitoring:

./scripts/helpers/add-host.sh

# Non-interactive
./scripts/helpers/add-host.sh --hostname switch01.example.com --ip 192.168.1.10

Interactive prompts for:

Hostname/FQDN
IP address
SNMP version (v1, v2c, v3)
SNMP community string

Features

✅ Input validation
✅ Hostname and IP format checking
✅ Confirmation before adding
✅ Executes directly in LibreNMS container

Verify Admin Login Credentials

Verify that admin user credentials are correctly configured:

sudo ./scripts/post-deploy/verify-login.sh

Performs comprehensive checks:

✅ Verifies .env credentials are set
✅ Checks user exists in database
✅ Validates user is enabled
✅ Confirms admin role is assigned
✅ Tests WebUI accessibility

Example Output:

==========================================
LibreNMS Login Verification
==========================================

[✓] .env credentials configured
  Username: admin

[✓] User exists in database
  User ID: 1
  Email: admin@example.com
  Role: admin
  Enabled: 1

[✓] User is enabled
[✓] User has 'admin' role (full privileges)
[✓] WebUI is accessible at https://10.1.10.58

[✓] All checks passed!

You can now log in to LibreNMS:
  URL: https://10.1.10.58
  Username: admin
  Password: (as set in .env)

Reset Admin Password

Reset the admin password without redeploying:

# Use credentials from .env
sudo ./scripts/installer-scripts-additional/reset-admin-password.sh

# Or specify custom credentials
sudo ./scripts/installer-scripts-additional/reset-admin-password.sh myusername newpassword

Use cases:

✅ Password forgotten or lost
✅ Password needs to be changed quickly
✅ Password in .env was updated
✅ Testing different password complexity

Note: After running, you can immediately log in with the new password.

Verify Poller and fping Functionality

Verify that polling and fping (ICMP ping) are working correctly:

sudo ./scripts/post-deploy/verify-poller-fping.sh

# Test with specific target IP
sudo ./scripts/post-deploy/verify-poller-fping.sh 10.1.10.58