search

librenms / docker

LibreNMS Docker image
MIT License
644 stars 272 forks source link
alpine-linux docker librenms nagios-plugins nginx snmpd syslog-ng

readme

Latest Version Build Status Docker Stars Docker Pulls
Become a sponsor Donate Paypal

About

Docker image for LibreNMS, a fully featured network monitoring system that provides a wealth of features and device support.

[!TIP] Want to be notified of new releases? Check out šŸ”” Diun (Docker Image Update Notifier) project!

Features

Demo

Try in PWD

Build locally

$ git clone https://github.com/librenms/docker.git docker-librenms
$ cd docker-librenms

# Build image and output to docker (default)
$ docker buildx bake

# Build multi-platform image
$ docker buildx bake image-all

Image

Following platforms for this image are available:

$ docker run --rm mplatform/mquery librenms/librenms:latest
Image: librenms/librenms:latest
 * Manifest List: Yes
 * Supported platforms:
   - linux/amd64
   - linux/arm/v7
   - linux/arm64
   - linux/386
   - linux/ppc64le
   - linux/s390x

Environment variables

General

Redis

[!NOTE] Redis variables should be set on all containers and are required when running more than one dispatcher.

Dispatcher service

[!WARNING] Only used if you enable and run a sidecar dispatcher container.

Syslog-ng

[!WARNING] Only used if you enable and run a sidecar syslog-ng container.

Snmptrapd

[!WARNING] Only used if you enable and run a sidecar snmptrapd container.

Database

Misc

Volumes

[!WARNING] Note that the volume should be owned by the user/group with the specified PUID and PGID. If you don't give the volume correct permissions, the container may not start.

Ports

Usage

Docker Compose

Docker compose is the recommended way to run this image. Copy the content of folder examples/compose in /var/librenms/ on your host for example. Edit the compose and env files with your preferences and run the following commands:

$ docker compose up -d
$ docker compose logs -f

Command line

You can also use the following minimal command:

$ docker run -d -p 8000:8000 --name librenms \
  -v $(pwd)/data:/data \
  -e "DB_HOST=db" \
  librenms/librenms:latest

[!WARNING] db must be a running MySQL instance.

First launch

When you first access the webui, you will be prompted to create an admin user.

[!NOTE] If you lose access, you can create another one using the lnms command.

Upgrade

To upgrade to the latest version of LibreNMS, pull the newer image and launch the container. LibreNMS will upgrade automatically:

$ docker compose down
$ docker compose pull
$ docker compose up -d

Configuration Management

Initial Configuration

You can set the initial configuration of LibreNMS by placing *.yaml files inside /data/config folder. Let's say you want to edit the WebUI config. Create a file called for example /data/config/webui.yaml with this content :

page_refresh: 300
webui.default_dashboard_id: 0

This configuration will be seeded into the LibreNMS database when it is first deployed and will override the default values.

Live Configuration

You can edit the running configuration via the LibreNMS web UI or lnms config:set

docker compose exec librenms lnms config:set page_refresh 300

Re-Apply YAML Config

Set REAPPLY_YAML_CONFIG=1 to overwrite any settings that are set during initial config or via user config back to their initial values every time the container is deployed.

Live Config

Using this config method, configuration changes will be reflected live on the containers, BUT you will be unable to edit the configured settings from within the LibreNMS web UI or lnms config:set.

The same example using PHP /data/config/webui.php

<?php
$config['page_refresh'] = "300";
$config['webui']['default_dashboard_id'] = 0;

Notes

LNMS command

If you want to use the lnms command to perform common server operations like manage users, database migration, and more, type:

$ docker compose exec librenms lnms

Validate

If you want to validate your installation from the CLI, type the following command:

$ docker compose exec --user librenms librenms php validate.php
====================================
Component | Version
--------- | -------
LibreNMS  | 1.64
DB Schema | 2020_04_19_010532_eventlog_sensor_reference_cleanup (165)
PHP       | 7.3.18
Python    | 3.8.2
MySQL     | 10.4.13-MariaDB-1:10.4.13+maria~bionic
RRDTool   | 1.7.2
SNMP      | NET-SNMP 5.8
====================================

[OK]    Installed from the official Docker image; no Composer required
[OK]    Database connection successful
[OK]    Database schema correct
[WARN]  IPv6 is disabled on your server, you will not be able to add IPv6 devices.
[WARN]  Updates are managed through the official Docker image

Dispatcher service container

If you want to enable the new Dispatcher service, you have to run a "sidecar" container (see dispatcher service in compose.yml example) or run a simple container like this:

$ docker run -d --name librenms_dispatcher \
  --env-file $(pwd)/librenms.env \
  -e SIDECAR_DISPATCHER=1 \
  -e DISPATCHER_NODE_ID=dispatcher1 \
  -v librenms:/data \
  librenms/librenms:latest

[!WARNING] librenms must be a valid volume already attached to a LibreNMS container.

Syslog-ng container

If you want to enable syslog-ng, you have to run a "sidecar" container (see syslog-ng service in compose.yml example) or run a simple container like this:

$ docker run -d --name librenms_syslog \
  --env-file $(pwd)/librenms.env \
  -e SIDECAR_SYSLOGNG=1 \
  -p 514 -p 514/udp \
  -v librenms:/data \
  librenms/librenms:latest

[!WARNING] librenms must be a valid volume already attached to a LibreNMS container.

You have to create a configuration file to enable syslog in LibreNMS too. Create a file called for example /data/config/syslog.yaml with this content :

enable_syslog: true

Snmptrapd container

If you want to enable snmptrapd, you have to run a "sidecar" container (see snmptrapd service in compose.yml example) or run a simple container like this:

$ docker run -d --name librenms_snmptrapd \
  --env-file $(pwd)/librenms.env \
  -e SIDECAR_SNMPTRAPD=1 \
  -p 162 -p 162/udp \
  -v librenms:/data \
  librenms/librenms:latest

[!WARNING] librenms must be a valid volume already attached to a LibreNMS container.

Add a LibreNMS plugin

You can add plugins for LibreNMS in /data/plugins/. If you add a plugin that already exists in LibreNMS, it will be removed and yours will be used (except for Weathermap).

[!WARNING] Container has to be restarted to propagate changes.

Additional Monitoring plugins

You can add a custom Monitoring plugin in /data/monitoring-plugins/.

Some plugins can be found in the Monitoring Plugins repo, or in the unofficial fork for Nagios.

[!WARNING] Container has to be restarted to propagate changes.

Custom alert templates

You can add Laravel alert templates in /data/alert-templates/.

[!WARNING] Container has to be restarted to propagate changes.

Contributing

Want to contribute? Awesome! The most basic way to show your support is to star the project, or to raise issues. You can also support this project by becoming a sponsor on GitHub or by making a PayPal donation to ensure this journey continues indefinitely!

Thanks again for your support, it is much appreciated! :pray:

License

MIT. See LICENSE for more details.