Awesome
<p align="center"><a href="https://github.com/librenms/docker" target="_blank"><img height="128" src="https://raw.githubusercontent.com/librenms/docker/master/.github/docker-librenms.jpg"></a></p> <p align="center"> <a href="https://hub.docker.com/r/librenms/librenms/tags?page=1&ordering=last_updated"><img src="https://img.shields.io/github/v/tag/librenms/docker?label=version&style=flat-square" alt="Latest Version"></a> <a href="https://github.com/librenms/docker/actions?workflow=build"><img src="https://img.shields.io/github/actions/workflow/status/librenms/docker/build.yml?branch=master&label=build&logo=github&style=flat-square" alt="Build Status"></a> <a href="https://hub.docker.com/r/librenms/librenms/"><img src="https://img.shields.io/docker/stars/librenms/librenms.svg?style=flat-square&logo=docker" alt="Docker Stars"></a> <a href="https://hub.docker.com/r/librenms/librenms/"><img src="https://img.shields.io/docker/pulls/librenms/librenms.svg?style=flat-square&logo=docker" alt="Docker Pulls"></a> <br /><a href="https://github.com/sponsors/crazy-max"><img src="https://img.shields.io/badge/sponsor-crazy--max-181717.svg?logo=github&style=flat-square" alt="Become a sponsor"></a> <a href="https://www.paypal.me/crazyws"><img src="https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal&style=flat-square" alt="Donate Paypal"></a> </p>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
- Build locally
- Image
- Environment variables
- Volumes
- Ports
- Usage
- Upgrade
- Configuration Management
- Notes
- Contributing
- License
Features
- Run as non-root user
- Multi-platform image
- Dispatcher service as "sidecar" container
- Syslog-ng support through a "sidecar" container
- Snmp-trap support through a "sidecar" container
- Built-in LibreNMS Weathermap plugin
- Ability to add custom Monitoring plugins
- Ability to add custom alert templates
- OPCache enabled to store precompiled script bytecode in shared memory
- s6-overlay as process supervisor
- Traefik as reverse proxy and creation/renewal of Let's Encrypt certificates (see this template)
- Redis image ready to use for better scalability
- RRDcached image ready to use for data caching and graphs
- msmtpd SMTP relay image to send emails
- MariaDB image as database instance
Demo
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 buildx imagetools inspect librenms/librenms --format "{{json .Manifest}}" | \
jq -r '.manifests[] | select(.platform.os != null and .platform.os != "unknown") | .platform | "\(.os)/\(.architecture)\(if .variant then "/" + .variant else "" end)"'
linux/386
linux/amd64
linux/arm/v7
linux/arm64
linux/ppc64le
linux/s390x
Environment variables
General
TZ
: The timezone assigned to the container (defaultUTC
)PUID
: LibreNMS user id (default1000
)PGID
: LibreNMS group id (default1000
)MEMORY_LIMIT
: PHP memory limit (default256M
)MAX_INPUT_VARS
: PHP max input vars (default1000
)UPLOAD_MAX_SIZE
: Upload max size (default16M
)CLEAR_ENV
: Clear environment in FPM workers (defaultyes
)FPM_PM_MAX_CHILDREN
: FPM max Children (default:15
)FPM_PM_START_SERVERS
: FPM start servers (default:2
)FPM_PM_MIN_SPARE_SERVERS
: FPM min spare servers (default:1
)FPM_PM_MAX_SPARE_SERVERS
: FPM max spare servers (default:6
)OPCACHE_MEM_SIZE
: PHP OpCache memory consumption (default128
)LISTEN_IPV6
: Enable IPv6 for Nginx (defaulttrue
)REAL_IP_FROM
: Trusted addresses that are known to send correct replacement addresses (default0.0.0.0/32
)REAL_IP_HEADER
: Request header field whose value will be used to replace the client address (defaultX-Forwarded-For
)LOG_IP_VAR
: Use another variable to retrieve the remote IP address for access log_format on Nginx. (defaultremote_addr
)SESSION_DRIVER
: Driver to use for session storage (defaultfile
)CACHE_DRIVER
: Driver to use for cache and locks (defaultdatabase
)
Redis
[!NOTE] Redis variables should be set on all containers and are required when running more than one dispatcher.
REDIS_HOST
: Redis host for poller synchronizationREDIS_SENTINEL
: Redis Sentinel host for high availability Redis clusterREDIS_SENTINEL_SERVICE
: Redis Sentinel service name (defaultlibrenms
)REDIS_SCHEME
: Redis scheme (defaulttcp
)REDIS_PORT
: Redis port (default6379
)REDIS_PASSWORD
: Redis passwordREDIS_DB
: Redis database (default0
)REDIS_CACHE_DB
: Redis cache database (default1
)
Dispatcher service
[!WARNING] You need at least one dispatcher sidecar, otherwise poller will not run sidecar dispatcher container.
SIDECAR_DISPATCHER
: Set to1
to enable sidecar dispatcher mode for this container (default0
)DISPATCHER_NODE_ID
: Unique node ID for your dispatcher serviceDISPATCHER_ARGS
: Additional args to pass to the dispatcher service
Syslog-ng
[!WARNING] Only used if you enable and run a sidecar syslog-ng container.
SIDECAR_SYSLOGNG
: Set to1
to enable sidecar syslog-ng mode for this container (default0
)
Snmptrapd
[!WARNING] Only used if you enable and run a sidecar snmptrapd container.
SIDECAR_SNMPTRAPD
: Set to1
to enable sidecar snmptrapd mode for this container (default0
)SNMP_PROCESSING_TYPE
: Sets which type of processing (log
,execute
, and/ornet
) to use with the SNMP trap (defaultlog,execute,net
)SNMP_USER
: Defines what username to authenticate with (defaultlibrenms_user
)SNMP_AUTH
: Defines what password to authenticate with (defaultauth_pass
should not be used, but will work)SNMP_PRIV
: Defines what password to encrypt packages with (defaultpriv_pass
should not be used, but will work)SNMP_AUTH_PROTO
: Sets what protocol (MD5
|SHA
) to use for authentication (defaultSHA
)SNMP_PRIV_PROTO
: Sets what protocol (DES
|AES
) to use for encryption of packages (defaultAES
)SNMP_SECURITY_LEVEL
: Sets what security level (noauth
|priv
) to use (defaultpriv
)SNMP_ENGINEID
: Defines what SNMP EngineID to use (default1234567890
)SNMP_DISABLE_AUTHORIZATION
: Will disable the above access control checks, and revert to the previous behaviour of accepting all incoming notifications. (defaultyes
)SNMP_EXTRA_MIB_DIRS
: Additional directories where MIB files are for SNMP Traps (example/opt/librenms/mibs/veeam
)
Database
DB_HOST
: MySQL database hostname / IP addressDB_PORT
: MySQL database port (default3306
)DB_NAME
: MySQL database name (defaultlibrenms
)DB_USER
: MySQL user (defaultlibrenms
)DB_PASSWORD
: MySQL password (defaultlibrenms
)DB_TIMEOUT
: Time in seconds after which we stop trying to reach the MySQL server (useful for clusters, default60
)
Misc
LIBRENMS_BASE_URL
: URL of your LibreNMS instance (default/
)LIBRENMS_SNMP_COMMUNITY
: This container's SNMP v2c community string (defaultlibrenmsdocker
)LIBRENMS_WEATHERMAP
: Enable LibreNMS Weathermap plugin (defaultfalse
)LIBRENMS_WEATHERMAP_SCHEDULE
: CRON expression format (default*/5 * * * *
)MEMCACHED_HOST
: Hostname / IP address of a Memcached serverMEMCACHED_PORT
: Port of the Memcached server (default11211
)RRDCACHED_SERVER
: RRDcached server (eg.rrdcached:42217
)
Volumes
/data
: Contains configuration, plugins, rrd database, logs, additional Monitoring plugins, additional syslog-ng config files
[!WARNING] Note that the volume should be owned by the user/group with the specified
PUID
andPGID
. If you don't give the volume correct permissions, the container may not start.
Ports
8000
: HTTP port514 514/udp
: Syslog ports (only used if you enable and run a sidecar syslog-ng container)162 162/udp
: Snmptrapd ports (only used if you enable and run a sidecar snmptrapd container)
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.