Deploy LibreNMS on a VPS

Target: LibreNMS on Nginx + PHP-FPM + MariaDB + RRDtool, with SNMP polling and the lnms fping/dispatcher cron pipeline. Sized for monitoring a small-to-mid fleet (dozens to low hundreds of hosts) on a 2 vCPU / 4GB RamNode KVM instance.

0. Assumptions

Fresh Ubuntu 24.04 LTS VPS, non-root sudo user
You have (or will create) an SNMP community string / v3 creds for the devices you're polling (hypervisor nodes, switches, etc.)

1. Base packages

shell

sudo apt update && sudo apt upgrade -y
sudo apt install -y software-properties-common curl composer git \
    fping graphviz imagemagick mtr-tiny nmap python3-pip \
    python3-dotenv python3-pymysql python3-redis python3-setuptools \
    python3-systemd python3-pip snmp snmpd rrdtool whois unzip

2. Create the librenms system user

shell

sudo useradd librenms -d /opt/librenms -M -r -s "$(command -v bash)"

3. Fetch LibreNMS

shell

cd /opt
sudo git clone https://github.com/librenms/librenms.git
sudo chown -R librenms:librenms /opt/librenms
sudo chmod 771 /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/

4. PHP 8.2+ and required extensions

Ubuntu 24.04's default repo PHP (8.3) works fine — no need for Ondrej's PPA unless you want a newer minor version.

shell

sudo apt install -y php php-fpm php-cli php-mysql php-gd php-json \
    php-curl php-snmp php-xml php-mbstring php-zip php-bcmath php-gmp

Set timezone in PHP config (must match system):

shell

TZ=$(cat /etc/timezone)
sudo sed -i "s/;date.timezone =/date.timezone = ${TZ//\//\\/}/" /etc/php/8.3/fpm/php.ini
sudo sed -i "s/;date.timezone =/date.timezone = ${TZ//\//\\/}/" /etc/php/8.3/cli/php.ini

5. MariaDB

shell

sudo apt install -y mariadb-server mariadb-client
sudo systemctl enable --now mariadb
sudo mysql_secure_installation

Tune /etc/mysql/mariadb.conf.d/50-server.cnf — add under [mysqld]:

shell

innodb_file_per_table=1
lower_case_table_names=0

Restart and create the DB:

shell

sudo systemctl restart mariadb
sudo mysql -u root -p <<'EOF'
CREATE DATABASE librenms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'librenms'@'localhost' IDENTIFIED BY 'CHANGE_ME_STRONG_PW';
GRANT ALL PRIVILEGES ON librenms.* TO 'librenms'@'localhost';
FLUSH PRIVILEGES;
EOF

6. PHP-FPM pool

shell

sudo cp /etc/php/8.3/fpm/pool.d/www.conf /etc/php/8.3/fpm/pool.d/librenms.conf
sudo sed -i 's/\[www\]/[librenms]/' /etc/php/8.3/fpm/pool.d/librenms.conf
sudo sed -i 's/user = www-data/user = librenms/' /etc/php/8.3/fpm/pool.d/librenms.conf
sudo sed -i 's/group = www-data/group = librenms/' /etc/php/8.3/fpm/pool.d/librenms.conf
sudo sed -i 's|listen = .*|listen = /run/php-fpm-librenms.sock|' /etc/php/8.3/fpm/pool.d/librenms.conf
sudo systemctl restart php8.3-fpm

7. Nginx vhost

shell

sudo apt install -y nginx
sudo rm -f /etc/nginx/sites-enabled/default

/etc/nginx/sites-available/librenms:

shell

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(/|$) {
        fastcgi_pass unix:/run/php-fpm-librenms.sock;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        include fastcgi.conf;
    }

    location /api/v0 {
        try_files $uri $uri/ /api_v0.php?$query_string;
    }
}

shell

sudo ln -s /etc/nginx/sites-available/librenms /etc/nginx/sites-enabled/librenms
sudo nginx -t && sudo systemctl reload nginx

Layer TLS with certbot the same way as any other vhost:

shell

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d librenms.example.com

8. lnms CLI and dependencies

shell

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

Symlink the CLI helper:

shell

sudo ln -s /opt/librenms/lnms /usr/bin/lnms
sudo cp /opt/librenms/misc/lnms-completion.bash /etc/bash_completion.d/

9. Web installer

Browse to http://librenms.example.com/install (or https:// once TLS is up) and walk through the guided DB setup — it writes /opt/librenms/.env for you. Alternatively do it headless:

shell

cd /opt/librenms
sudo -u librenms cp .env.example .env
sudo -u librenms php artisan key:generate

Then edit .env:

shell

APP_URL=https://librenms.example.com
DB_HOST=localhost
DB_DATABASE=librenms
DB_USERNAME=librenms
DB_PASSWORD=CHANGE_ME_STRONG_PW

Run migrations and create the first admin user:

shell

sudo -u librenms php artisan migrate --force
sudo -u librenms /opt/librenms/lnms user:add -r admin -e you@example.com admin

10. SNMPd (only needed if this VPS itself is a polled device)

shell

sudo cp /opt/librenms/misc/snmpd.conf.example /etc/snmp/snmpd.conf
sudo sed -i 's/RANDOMSTRINGGOESHERE/YOUR_RO_COMMUNITY/' /etc/snmp/snmpd.conf
sudo systemctl enable --now snmpd

For polling other devices (the actual point of LibreNMS), no local snmpd config is needed — creds are stored per-device in the web UI or via lnms device:add.

11. Cron / scheduler

shell

sudo cp /opt/librenms/librenms.nonroot.cron /etc/cron.d/librenms

This drives discovery, polling, alerting, and billing every minute via the dispatcher service. For higher-scale polling, switch to the distributed poller service instead of cron-based polling:

shell

sudo cp /opt/librenms/librenms.service /etc/systemd/system/
sudo systemctl enable --now librenms

Logrotate:

shell

sudo cp /opt/librenms/misc/librenms.logrotate /etc/logrotate.d/librenms

12. Add your first device

shell

sudo -u librenms lnms device:add nlxsvz71.ramnode.com -v v2c -c YOUR_RO_COMMUNITY
sudo -u librenms lnms discovery:run -h all
sudo -u librenms lnms poller:run -h all

13. Validate

shell

sudo -u librenms php /opt/librenms/validate.php

This checks permissions, PHP extensions, cron health, and DB schema version — fix anything it flags before relying on the install.

14. Firewall

shell

sudo ufw allow OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable

Polling traffic (SNMP/ICMP outbound to monitored hosts) doesn't need inbound rules unless devices are configured to send traps back — if so, also open 162/udp.