Networking Solutions- Monitoring switches using LibreNMS

LibreNMS Installation and Configuration Guide

Purpose: Detailed internal documentation for installing and configuring
LibreNMS on Ubuntu 24.04 LTS. Includes all steps, explanations, and
troubleshooting information. Designed to be usable for system/network
admins in similar environments.

Table of Contents

1. Problem statement

2. Introduction

3. Prerequisites and Why They Matter

4. Step-by-Step Installation

5. MariaDB Configuration and Table Values

6. Setting Up the .env File

7. Laravel: What and Why?

8. Clearing Cache: When and How

9. SNMP Configuration on Network Switches

10. Adding Devices in LibreNMS

11. Troubleshooting and Fixes

12. Final output

1. Problem Statement

Our 300-acre academy campus has grown organically for two decades.

65 switches (core, distribution, access) – many >10 years old – span
buildings that sit kilometres apart.

Recurrent Layer 2/3 faults meant outages were diagnosed ad-hoc, often by
physically hopping buildings.

The small network team was firefighting rather than proactively
monitoring.

Objective – deploy an open-source NMS that:

• Discovers all switches, links and servers automatically.

• Maps Layer 2/3 topology so we can see choke-points and loops.

• Sends alerts (email / Telegram) within 60 seconds of an interface or
  route change.

• Fits on spare hardware and can be rolled out in < 1 week alongside
  normal duties.

We chose LibreNMS, validated it in a lab, and completed a full
production rollout in five working days using a free Ubuntu Server VM.

2. Introduction

LibreNMS is a powerful, open-source network monitoring and management
tool. It supports auto-discovery of devices using SNMP and provides
visual dashboards, alerting, performance metrics, and logs.

This guide walks you through setting up LibreNMS from scratch, including
resolving common errors.

3. Prerequisites and Why They Matter

3.1 Install Core Packages

Bash:

sudo apt update && sudo apt install -y \
apache2 mariadb-server \
php php-cli php-mysql php-gd php-json php-snmp php-xml php-mbstring \
libapache2-mod-php rrdtool git fping imagemagick python3-dotenv \
snmp snmp-mibs-downloader unzip curl

Why Each Package Is Needed

• Apache2: Web server to host LibreNMS GUI.

• MariaDB: Relational database to store device information, polling
  history, user accounts, etc.

• PHP & Modules: LibreNMS is written in PHP and Laravel. Modules like
  php-snmp are essential for SNMP querying.

• rrdtool: For graph generation.

• fping: For ICMP-based device polling.

• imagemagick: Required by some components for image handling.

• git: To clone LibreNMS repository.

• snmp/snmp-mibs-downloader: For device communication and MIBs.

• python-dotenv: To manage environment files.

4. Step-by-Step Installation

4.1 Clone LibreNMS

Bash:

cd /opt
sudo git clone https://github.com/librenms/librenms.git
sudo chown -R www-data:www-data /opt/librenms

4.2 Configure Apache

Create the Apache config file:

Bash:

sudo nano /etc/apache2/sites-available/librenms.conf

Add this content (inside nano ):

<VirtualHost *:80>
  DocumentRoot /opt/librenms/html
  ServerName librenms.local

  <Directory "/opt/librenms/html">
    Require all granted
    AllowOverride All
    Options FollowSymLinks MultiViews
  </Directory>
</VirtualHost>

After this:

Bash:

sudo a2ensite librenms.conf
sudo a2enmod rewrite
sudo systemctl reload apache2

4.3 Composer Install

Bash:

cd /opt/librenms
composer install --no-dev

If folder permissions block composer, use sudo carefully.

5. MariaDB Configuration and Table Values

5.1 Secure MariaDB and Create Database

Bash:

sudo mysql_secure_installation

Then (SQL commands) :

CREATE DATABASE librenms CHARACTER SET utf8mb4 COLLATE
utf8mb4_unicode_ci;

CREATE USER 'librenms'@'localhost' IDENTIFIED BY
'YourStrongPassword';```

 \#Remember this password as it your authentication
password

GRANT ALL PRIVILEGES ON librenms.\* TO 'librenms'@'localhost';

FLUSH PRIVILEGES;

**Complete setting up the .env file before proceeding (set it up before any Artisan commands that rely on it like php artisan migrate or php artisan user:add) This step is covered in Step 6. **

5.2 Populate LibreNMS Database Schema (Important)

Once the database and user are created, you must populate the database with all required tables.

Bash:

bash
cd /opt/librenms
php artisan migrate

This command creates all the required tables (users, roles, permissions, etc.,)

Add Initial Admin User :

After populating the database schema, create your first LibreNMS user (typically an administrator) using Laravel’s Artisan command:

Bash:

bash
cd /opt/librenms
php artisan user:add

This command will:

Prompt you to enter a username

Prompt for a password

NOTE:

This step is mandatory — skipping it means you won’t be able to log into the LibreNMS web interface.

If you enter only the username without role prompts, and see errors like
“There is no role named 'user' for guard 'web’”,
it may mean your roles table is empty (see next section).

5.3 Understanding Role-Based Tables

LibreNMS uses Laravel's built-in role-based access control (RBAC) system, which involves several interlinked tables to manage permissions.

Key Tables:

• users: Contains all registered users in the system.
• roles: Defines different access levels (e.g., admin, user).
• role_user or model_has_roles: These are pivot tables that connect users to their assigned roles.

How They Relate:

Each user entry in the users table must be associated with at least one
role from the roles table. This relationship is stored in the
model_has_roles table (or role_user in some Laravel setups). If this
linking is missing, users may be unable to access certain pages, such as
"Add Device", and may see "Insufficient Permissions" errors.

If these tables are missing data (especially after a manual install),
you may need to manually insert rows using SQL commands.

Optional Table: password_reset_tokens

This table is used for password recovery flows via email. It is not
required unless you plan to enable password resets from the login
page.

SQL Example:

-- Insert admin role

INSERT INTO roles (name, guard_name) VALUES ('admin', 'web');

-- Link user ID 1 to admin role (assuming ID 1 is your admin user)

INSERT INTO model_has_roles (role_id, model_type, model_id)

VALUES (1, 'App\Models\User', 1);

Make sure model_id matches the user_id of the user from the users table.

• Ensure roles table has values (admin/user roles).

• Ensure users table has at least one user (admin).

• Ensure role_user table links users to their roles.

• Ensure model_has_roles table has the proper entries.

You may need to manually insert data using SQL if the web setup fails.

So, to summarize:

• users: Stores individual login accounts.

• roles: Defines what types of users exist (admin, user, etc.).

• role_user or model_has_roles: Links users to their roles.

Note: Ensure the password_reset_tokens table exists. It's used by
Laravel for handling password reset functionality. No need to populate
it unless you're enabling reset flows via email.

6. Setting Up the .env File

What Is .env?

The .env file holds Laravel's environment variables: DB config, app URL,
log settings, etc.

Sample .env Content

APP_KEY= # Set by artisan key:generate

DB_HOST=localhost

DB_DATABASE=librenms

DB_USERNAME=librenms

DB_PASSWORD=YourStrongPassword

APP_URL=http://your-server-ip (the
machine IP) #Remember to change this if machine IP changes

LOG_CHANNEL=stack

LOG_LEVEL=debug

SESSION_ENCRYPT=false

Explanation of Each Line

• APP_KEY: Used by Laravel to encrypt sessions. Must be set.

• DB_*: Database connection settings.

• APP_URL: Needed for redirection and URL generation.

• LOG_*: Logging mode and verbosity.

• SESSION_ENCRYPT: Basic session handling config.

Run this to generate your artisan key.

Bash:

bash
php artisan key:generate

7. Laravel: What and Why?

Laravel is the PHP framework behind LibreNMS. It manages:

• Routing (URLs)

• Authentication (users/roles)

• Logging and sessions

• Database schema via migrations

Without Laravel, LibreNMS would be a pile of raw PHP.

8. Clearing Cache

When to Do It

• After modifying .env

• After adding new users manually

• After any Laravel upgrade

Bash:

bash
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear

9. SNMP Configuration on Switches

Common Steps

1. Login to your switch web GUI

2. Navigate to SNMP Settings

3. Enable SNMP (v1/v2c)

4. Set Read-Only Community to public

5. Save and apply

Then test from your VM:

Bash:

bash
snmpwalk -v2c -c public 192.168.X.X

If this command gives results, your device is SNMP-ready.

10. Adding Devices in LibreNMS

Navigate to Devices > Add Device:

• Hostname or IP: The IP of the switch/router

• SNMP Community: public or your set string

• Version: SNMPv2c

• Port: 161 (default for SNMP)

Troubleshooting tip: check /opt/librenms/logs/librenms.log for failures.

11. Troubleshooting & Fixes

• librenms.log permission denied → fix folder ownership to www-data

• Database errors like "table doesn't exist" → rerun web setup or insert
  manually

• 500 Internal Server Error → clear Laravel cache

• Can't access Add Device page → make sure user has admin role

12. Final Output

Add more switches/pc’s and enjoy your central device management as the
network/sys admin of your organization.