Docker image for LibreNMS
:warning: This document refers to the master branch and does not necessarily correspond to the version that you are running. It is recommended to extract the readme from your preferred release's source code archive. Releases are listed on the Releases page.
docker-librenms is a customizable Docker image for LibreNMS based on Ubuntu.
The container runs nginx 1.18+ with HTTP/2 support and PHP 8.2 FPM with OPCache and rrdcached for maximum performance.
:warning: ARM support is experimental, see here for more details.
You must first generate a unique encryption key.
Generating the key
docker run --rm jarischaefer/docker-librenms generate_key
Output example
base64:Q0+ZV56/5Uwz79vsvS4ZfwQFOty3e9DJEouEy+IXvz8=
:warning: Make sure you keep the key secret, because anyone in possession of it can decrypt sensitive data.
There are currently two methods to pass the encryption key to LibreNMS. Make sure to include the full key (including base64:
)
regardless of the method used.
The key can be passed via the APP_KEY
environment variable in the docker run
command.
Example
The following command is incomplete and only illustrates passing an environment variable:
docker run -e APP_KEY=base64:Q0+ZV56/5Uwz79vsvS4ZfwQFOty3e9DJEouEy+IXvz8= jarischaefer/docker-librenms
Alternatively, you may use the APP_KEY_FILE
environment variable and mount the secret as a file inside the container.
You must first create the file on the host and only then start the container (otherwise Docker creates and mounts a directory instead of a file).
Example
The following command is incomplete and only illustrates passing an environment variable and mounting a file:
docker run -e APP_KEY_FILE=/mount/secret_key -v /path/on/host/secret_key:/mount/secret_key
If you don't have a MySQL server setup either in Docker or elsewhere then you can create a docker container here.
You should read the LibreNMS installation docs for the latest instructions regarding database setup.
As of July 2020, the following settings are required (should apply to both MariaDB and MySQL):
innodb_file_per_table=1
lower_case_table_names=0
You should have a MySQL server running at this point. Make sure the database, user and permissions exist before running the commands.
Next, follow the instructions for running the container. Once the container is up and running, you may use the following commands to populate the database and create an admin user.
Creating the tables
docker exec librenms setup_database
Creating an initial admin user
docker exec librenms create_admin
This creates a user with the following properties:
Creating a custom user
docker exec librenms create_user user password role email
Example:
docker exec librenms create_user admin secret admin admin@example.com
docker exec librenms create_user joe secret normal normal@example.com
docker exec librenms create_user read secret global-read read@example.com
The examples below do not cover all of the available configuration options, check the appropriate section in the docs for a complete list.
In the example below the linked container is named my-database-container
and its alias inside the container is database
.
Make sure my-database-container
matches the MySQL container's name and DB_HOST
matches its alias inside the container if you intend
to modify it.
docker run \
-d \
-h librenms \
-p 80:80 \
-e APP_KEY=the_secret_key_you_have_generated \
-e DB_HOST=database \
-e DB_NAME=librenms \
-e DB_USER=librenms \
-e DB_PASS=secret \
-e BASE_URL=http://localhost \
--link my-database-container:database \
-v /data/logs:/opt/librenms/logs \
-v /data/rrd:/opt/librenms/rrd \
--name librenms \
jarischaefer/docker-librenms
docker run \
-d \
-h librenms \
-p 80:80 \
-e APP_KEY=the_secret_key_you_have_generated \
-e DB_HOST=x.x.x.x \
-e DB_NAME=librenms \
-e DB_USER=librenms \
-e DB_PASS=secret \
-e BASE_URL=http://localhost \
-v /data/logs:/opt/librenms/logs \
-v /data/rrd:/opt/librenms/rrd \
--name librenms \
jarischaefer/docker-librenms
Mount another directory containing ssl.key
, ssl.crt
and optionally ssl.ocsp.crt
to enable HTTPS.
You'll also have to change BASE_URL
and add SESSION_SECURE_COOKIE=true
.
docker run \
-d \
-h librenms \
-p 80:80 \
-p 443:443 \
-e APP_KEY=the_secret_key_you_have_generated \
-e DB_HOST=database \
-e DB_NAME=librenms \
-e DB_USER=librenms \
-e DB_PASS=secret \
-e BASE_URL=https://localhost \
--link my-database-container:database \
-v /data/logs:/opt/librenms/logs \
-v /data/rrd:/opt/librenms/rrd \
-v /data/ssl:/etc/nginx/ssl:ro \
--name librenms \
jarischaefer/docker-librenms
Updating an existing installation requires updating both the image and the database.
docker pull jarischaefer/docker-librenms:{release}
Automatic database updates are the most convenient solution for single-container setups.
Run docker exec librenms setup_database
.
If you would like to update the database automatically on startup, you may pass DAILY_ON_STARTUP=true
.
Keep in mind that restarting more than one container simultaneously could result in concurrency issues and damage your database.
The LibreNMS implementation (as of October 2018) uses a distributed lock via memcache to avoid this scenario. Therefore, if all containers share the same memcache instance, concurrent restarts would be safe.
:warning: The container must be stopped, removed and subsequently restarted in order for configuration changes to take effect.
The following keys can be passed directly via the -e
switch:
Key | Default | Description |
---|---|---|
APP_KEY | Secret encryption key | |
APP_KEY_FILE | Secret encryption key via file/secret | |
BASE_URL | Base URL for LibreNMS (e.g. http://192.168.0.1:8080) | |
DB_HOST | MySQL IP or hostname | |
DB_PORT | 3306 | MySQL port |
DB_NAME | MySQL database name | |
DB_USER | MySQL user | |
DB_PASS | MySQL password | |
DB_PASS_FILE | MySQL password via secret | |
TZ | UTC | Timezone (e.g. Europe/Zurich) |
PUID | User ID | |
PGID | Group ID | |
PHP_FPM_WORKERS_MIN | 1 | Minimum number of PHP-FPM workers |
PHP_FPM_WORKERS_MAX | 4 | Maximum number of PHP-FPM workers |
Key | Default | Description |
---|---|---|
DISABLE_IPV6 | false | Disable nginx IPv6 socket |
MEMCACHED_ENABLE | false | Enable memcached |
MEMCACHED_HOST | memcached IP or hostname | |
MEMCACHED_PORT | 11211 | memcached port |
NGINX_ENABLE | true | Enable nginx |
PHPFPM_ENABLE | true | Enable PHP-FPM |
RRDCACHED_ENABLE | true | Enable rrdcached |
RRDCACHED_CONNECT | unix:/var/run/rrdcached/rrdcached.sock | rrdcached TCP or unix socket where LibreNMS connects to |
RRDCACHED_LISTEN | unix:/var/run/rrdcached/rrdcached.sock | rrdcached TCP or unix socket where rrdcached listens on |
SKIP_CHOWN | false | Disable (slow) chown ing of files at startup (might help with network storage) |
SNMPTRAPD_ENABLE | false | Enable SNMP Trap Handler |
SNMPTRAPD_MIBS | IF-MIB | Passed to snmptrapd via -m |
SNMPTRAPD_MIBDIRS | /opt/librenms/mibs | Passed to snmptrapd via -M |
LIBRENMS_SERVICE_ENABLE | false | Enable librenms-service.py |
LIBRENMS_SERVICE_OPTS | "" | Options for librenms-service.py (e.g. -v ) |
:warning: Some values must be wrapped in quotation marks (e.g. cron schedule).
Key | Default | Description |
---|---|---|
ALERTS_ENABLE | true | Enable LibreNMS alerts |
BILLING_CALCULATE_ENABLE | true | Enable LibreNMS billing calculation |
CHECK_SERVICES_ENABLE | true | Enable LibreNMS service checks |
DAILY_ENABLE | true | Enable LibreNMS daily script |
DAILY_ON_STARTUP | false | Enable LibreNMS daily script on startup |
DISCOVERY_ENABLE | true | Enable LibreNMS discovery |
DISCOVERY_THREADS | 1 | Number of threads for discovery |
ENABLE_SYSLOG | false | Enable LibreNMS syslog (see here) |
POLL_BILLING_ENABLE | true | Enable LibreNMS billing polling |
POLLERS_ENABLE | true | Enable LibreNMS polling |
POLLERS | 8 | Number of LibreNMS pollers |
POLLERS_CRON | "/5 *" | Cron schedule for pollers |
SNMP_SCAN_ENABLE | false | Enable cron for snmp-scan |
SNMP_SCAN_CRON | "0 0 *" | Cron schedule for snmp-scan |
WEATHERMAP_ENABLE | false | Enable cron for weathermap (see here) |
WEATHERMAP_CRON | "/5 *" | Cron schedule for weathermap |
You may apply custom configuration by mounting files matching
*.php
in /opt/librenms/conf.d
.
In the example below /data/config.interfaces.php
on the host
is mounted inside the container at /opt/librenms/conf.d/config.interfaces.php
.
docker run \
-d \
-h librenms \
-p 80:80 \
-p 443:443 \
-e APP_KEY=the_secret_key_you_have_generated \
-e DB_HOST=database \
-e DB_NAME=librenms \
-e DB_USER=librenms \
-e DB_PASS=secret \
-e BASE_URL=https://localhost \
--link my-database-container:database \
-v /data/logs:/opt/librenms/logs \
-v /data/rrd:/opt/librenms/rrd \
-v /data/ssl:/etc/nginx/ssl:ro \
-v /data/config.interfaces.php:/opt/librenms/conf.d/config.interfaces.php \
--name librenms \
jarischaefer/docker-librenms
config.interfaces.php
<?php
$config['bad_if_regexp'][] = '/^docker[-\w].*$/';
$config['bad_if_regexp'][] = '/^lxcbr[0-9]+$/';
$config['bad_if_regexp'][] = '/^veth.*$/';
$config['bad_if_regexp'][] = '/^virbr.*$/';
$config['bad_if_regexp'][] = '/^lo$/';
$config['bad_if_regexp'][] = '/^macvtap.*$/';
$config['bad_if_regexp'][] = '/gre.*$/';
$config['bad_if_regexp'][] = '/tun[0-9]+$/';
If you plan to use this container for a distributed LibreNMS installation, you may want to disable some of
the default cron jobs,
or the local rrdcached, nginx and php-fpm services. You could also increase the number of discovery-wrapper.py
threads.
docker run \
-d \
-h librenms \
-p 80:80 \
-e APP_KEY=the_secret_key_you_have_generated \
-e DB_HOST=database \
-e DB_NAME=librenms \
-e DB_USER=librenms \
-e DB_PASS=secret \
-e BASE_URL=http://localhost \
-e POLLERS=16 \
-e TZ=UTC \
-e DISCOVERY_THREADS=2 \
-e DAILY_ENABLE=false \
-e ALERTS_ENABLE=false \
-e CHECK_SERVICES_ENABLE=false \
-e RRDCACHED_ENABLE=false \
-e NGINX_ENABLE=false \
-e PHPFPM_ENABLE=false \
--link my-database-container:database \
-v /data/logs:/opt/librenms/logs \
-v /data/rrd:/opt/librenms/rrd \
--name librenms \
jarischaefer/docker-librenms
Make sure you source
the environment variables from /etc/librenms_environment
prior to executing commands inside the container.
This is an example demonstrating how to run the validation script.
su - librenms
source /etc/librenms_environment
cd /opt/librenms
php validate.php
The commands above are purely for illustrative purposes. You should customize them to fit your environment.
Also, please note that...
See Issue #145 for information regarding backups. The documentation is still work in progress.
Create a directory structure such as this:
/srv/librenms/web/logs
/srv/librenms/web/rrd
/srv/librenms/db/data
Instead of copying multiple directories, this approach involves only /srv/librenms
.
Backing up
docker stop librenms-web
docker stop librenms-db
tar -cf /srv/backup.tar -C /srv/librenms .
Restoring
mkdir -p /srv/restore
tar -xf /srv/backup.tar -C /srv/restore
docker-compose.yml
or other start-/stop-scriptsdocker-compose.yml
or docker run
to point to /srv/restore
docker-compose.yml
or docker run
, e.g. 3306
to 3307
Backing up
docker stop librenms-web
tar -cf /srv/backup.tar -C /srv/librenms/web .
mysqldump --host=127.0.0.1 --port=3306 --user=librenms -p --single-transaction librenms > /srv/backup.sql
Restoring
mkdir -p /srv/restore
docker-compose.yml
or other start-/stop-scriptsdocker-compose.yml
or docker run
to point to /srv/restore
docker-compose.yml
or docker run
, e.g. 3306
to 3307
librenms
database, otherwise create it and grant privileges:
mysql --host=127.0.0.1 --port=3307 --user=librenms -p
cat /srv/backup.sql | mysql --host=127.0.0.1 --port=3307 --user=librenms -p librenms
rm -r /srv/restore/web && mkdir -p /srv/restore/web
tar -xf /srv/backup.tar -C /srv/restore/web
Nagios plugins are stored in /usr/lib/nagios/plugins
. Choose one of the options below if you would like to add new plugins.
See the corresponding issue for more information.
Option 1 (recommended)
/mount/nagios_plugins
. Example (using Docker CLI): -v /nagios_plugins:/mount/nagios_plugins
/nagios_plugins
on the hostdocker exec librenms ls -al /usr/lib/nagios/plugins
The container will automatically symlink the contents of /mount/nagios_plugins
to /usr/lib/nagios/plugins
.
Example
docker exec librenms ls -al /usr/lib/nagios/plugins/check_xyz
lrwxrwxrwx 1 root root 31 Jan 21 22:19 /usr/lib/nagios/plugins/check_xyz -> /mount/nagios_plugins/check_xyz
Option 2
Make sure the plugin (file) exists on the host before starting the container (Docker creates a directory on startup by default).
Each plugin must be mounted individually (-v
for Docker CLI), for example: -v /nagios_plugins/check_xyz:/usr/lib/nagios/plugins/check_xyz
These are instructions for the LibreNMS syslog extension.
-e ENABLE_SYSLOG=true
to your docker run command-p 514:514
and -p 514:514/udp
to your docker run command*.* @example.com:514
Unfortunately, due to the way Docker works (more specifically, its network modes), the devices and IP addresses
visible in LibreNMS may not be what one would expect. Instead of displaying the host's real IP address,
it is possible that an internal address such as 172.17.0.1
is observed. More information regarding this behavior
can be found in the corresponding issue.
These are instructions for the LibreNMS weathermap plugin.
The weathermap plugin requires additional mounts to persist its data.
/opt/librenms/html/plugins/Weathermap/configs
for the configs/opt/librenms/html/plugins/Weathermap/output
for the generated dataMake sure you set Output Image Filename to output/example.png
and
Output HTML Filename to output/example.html
in the Map Properties
configuration section so the files are persisted in the output
directory.
This project is open-sourced software licensed under the MIT license.
LibreNMS has its own license, this license only covers the Docker part.