diff --git a/README.md b/README.md index fcd2d9d..0e9a55a 100644 --- a/README.md +++ b/README.md @@ -16,17 +16,46 @@ If you are interested, [check out](https://hub.docker.com/r/crazymax/) my other 💡 Want to be notified of new releases? Check out 🔔 [Diun (Docker Image Update Notifier)](https://github.com/crazy-max/diun) project! -## Demo +___ -[![Try in PWD](https://raw.githubusercontent.com/play-with-docker/stacks/master/assets/images/button.png)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/librenms/docker/master/examples/pwd/librenms.yml) +* [Features](#features) +* [Demo](#demo) +* [Build locally](#build-locally) +* [Image](#image) +* [Environment variables](#environment-variables) + * [General](#general) + * [Dispatcher service](#dispatcher-service) + * [Syslog-ng](#syslog-ng) + * [Snmptrapd](#snmptrapd) + * [Database](#database) + * [Misc](#misc) +* [Volumes](#volumes) +* [Ports](#ports) +* [Usage](#usage) + * [Docker Compose](#docker-compose) + * [Command line](#command-line) + * [First launch](#first-launch) +* [Upgrade](#upgrade) +* [Notes](#notes) + * [Edit configuration](#edit-configuration) + * [LNMS command](#lnms-command) + * [Validate](#validate) + * [Dispatcher service container](#dispatcher-service-container) + * [Syslog-ng container](#syslog-ng-container) + * [Snmptrapd container](#snmptrapd-container) + * [Add a LibreNMS plugin](#add-a-librenms-plugin) + * [Additional Monitoring plugins](#additional-monitoring-plugins) + * [Custom alert templates](#custom-alert-templates) +* [Contributing](#contributing) +* [License](#license) ## Features * Run as non-root user * Multi-platform image -* [Dispatcher service](doc/docker/environment-variables.md#dispatcher-service) as "sidecar" container -* Syslog-ng support through a ["sidecar" container](doc/docker/environment-variables.md#syslog-ng) -* Snmp-trap support through a ["sidecar" container](doc/docker/environment-variables.md#snmptrapd) +* [Dispatcher service](#dispatcher-service) as "sidecar" container +* Syslog-ng support through a ["sidecar" container](#syslog-ng) +* Snmp-trap support through a ["sidecar" container](#snmptrapd) * Built-in LibreNMS [Weathermap plugin](https://docs.librenms.org/Extensions/Weathermap/) * Ability to add custom Monitoring plugins * Ability to add custom alert templates @@ -38,20 +67,24 @@ If you are interested, [check out](https://hub.docker.com/r/crazymax/) my other * [msmtpd SMTP relay](https://github.com/crazy-max/docker-msmtpd) image to send emails * [MariaDB](https://github.com/docker-library/mariadb) image as database instance +## Demo + +[![Try in PWD](https://raw.githubusercontent.com/play-with-docker/stacks/master/assets/images/button.png)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/librenms/docker/master/examples/pwd/librenms.yml) + ## Build locally -```shell -git clone https://github.com/librenms/docker.git docker-librenms -cd docker-librenms +```console +$ git clone https://github.com/librenms/docker.git docker-librenms +$ cd docker-librenms # Build image and output to docker (default) -docker buildx bake +$ docker buildx bake # Build multi-platform image -docker buildx bake image-all +$ docker buildx bake image-all ``` -## Multi-platform image +## Image Following platforms for this image are available: @@ -69,23 +102,299 @@ Image: librenms/librenms:latest - linux/s390x ``` -## Documentation +## Environment variables -* Docker - * [Environment variables](doc/docker/environment-variables.md) - * [Volumes](doc/docker/volumes.md) - * [Ports](doc/docker/ports.md) -* [Usage](doc/usage.md) -* Notes - * [Edit configuration](doc/notes/edit-config.md) - * [LNMS command](doc/notes/lnms-command.md) - * [Validate](doc/notes/validate.md) - * [Dispatcher service](doc/notes/dispatcher-service.md) - * [Add a LibreNMS plugin](doc/notes/plugins.md) - * [Syslog-ng](doc/notes/syslog-ng.md) - * [Additional Monitoring plugins](doc/notes/additional-monitoring-plugins.md) - * [Custom alert templates](doc/notes/alert-templates.md) -* [Upgrade](doc/upgrade.md) +### General + +* `TZ`: The timezone assigned to the container (default `UTC`) +* `PUID`: LibreNMS user id (default `1000`) +* `PGID`: LibreNMS group id (default `1000`) +* `MEMORY_LIMIT`: PHP memory limit (default `256M`) +* `MAX_INPUT_VARS`: PHP max input vars (default `1000`) +* `UPLOAD_MAX_SIZE`: Upload max size (default `16M`) +* `CLEAR_ENV`: Clear environment in FPM workers (default `yes`) +* `OPCACHE_MEM_SIZE`: PHP OpCache memory consumption (default `128`) +* `LISTEN_IPV6`: Enable IPv6 for Nginx (default `true`) +* `REAL_IP_FROM`: Trusted addresses that are known to send correct replacement addresses (default `0.0.0.0/32`) +* `REAL_IP_HEADER`: Request header field whose value will be used to replace the client address (default `X-Forwarded-For`) +* `LOG_IP_VAR`: Use another variable to retrieve the remote IP address for access [log_format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) on Nginx. (default `remote_addr`) + +### Dispatcher service + +> **Warning** +> +> Only used if you enable and run a [sidecar dispatcher container](#dispatcher-service-container). + +* `SIDECAR_DISPATCHER`: Set to `1` to enable sidecar dispatcher mode for this container (default `0`) +* `DISPATCHER_NODE_ID`: Unique node ID for your dispatcher service +* `DISPATCHER_ARGS`: Additional args to pass to the [dispatcher service](https://github.com/librenms/librenms/blob/master/librenms-service.py) +* `REDIS_HOST`: Redis host for poller synchronization +* `REDIS_SENTINEL`: Redis Sentinel host for high availability Redis cluster +* `REDIS_SENTINEL_SERVICE`: Redis Sentinel service name (default `librenms`) +* `REDIS_SCHEME`: Redis scheme (default `tcp`) +* `REDIS_PORT`: Redis port (default `6379`) +* `REDIS_PASSWORD`: Redis password +* `REDIS_DB`: Redis database (default `0`) + +### Syslog-ng + +> **Warning** +> +> Only used if you enable and run a [sidecar syslog-ng container](#syslog-ng-container). + +* `SIDECAR_SYSLOGNG`: Set to `1` to enable sidecar syslog-ng mode for this container (default `0`) + +### Snmptrapd + +> **Warning** +> +> Only used if you enable and run a [sidecar snmptrapd container](#snmptrapd-container). + +* `SIDECAR_SNMPTRAPD`: Set to `1` to enable sidecar snmptrapd mode for this container (default `0`) +* `SNMP_PROCESSING_TYPE`: Sets which type of processing (`log`, `execute`, and/or `net`) to use with the SNMP trap (default `log,execute,net`) +* `SNMP_USER`: Defines what username to authenticate with (default `librenms_user`) +* `SNMP_AUTH`: Defines what password to authenticate with (default `auth_pass` should not be used, but will work) +* `SNMP_PRIV`: Defines what password to encrypt packages with (default `priv_pass` should not be used, but will work) +* `SNMP_AUTH_PROTO`: Sets what protocol (`MD5`|`SHA`) to use for authentication (default `SHA`) +* `SNMP_PRIV_PROTO`: Sets what protocol (`DES`|`AES`) to use for encryption of packages (default `AES`) +* `SNMP_SECURITY_LEVEL`: Sets what security level (`noauth`|`priv`) to use (default `priv`) +* `SNMP_ENGINEID`: Defines what SNMP EngineID to use (default `1234567890`) +* `SNMP_DISABLE_AUTHORIZATION`: Will disable the above access control checks, and revert to the previous behaviour of accepting all incoming notifications. (default `yes`) + +### Database + +* `DB_HOST`: MySQL database hostname / IP address +* `DB_PORT`: MySQL database port (default `3306`) +* `DB_NAME`: MySQL database name (default `librenms`) +* `DB_USER`: MySQL user (default `librenms`) +* `DB_PASSWORD`: MySQL password (default `librenms`) +* `DB_TIMEOUT`: Time in seconds after which we stop trying to reach the MySQL server (useful for clusters, default `60`) + +### Misc + +* `LIBRENMS_BASE_URL`: URL of your LibreNMS instance (default `/`) +* `LIBRENMS_SNMP_COMMUNITY`: This container's SNMP v2c community string (default `librenmsdocker`) +* `LIBRENMS_WEATHERMAP`: Enable LibreNMS [Weathermap plugin](https://docs.librenms.org/Extensions/Weathermap/) (default `false`) +* `LIBRENMS_WEATHERMAP_SCHEDULE`: CRON expression format (default `*/5 * * * *`) +* `MEMCACHED_HOST`: Hostname / IP address of a Memcached server +* `MEMCACHED_PORT`: Port of the Memcached server (default `11211`) +* `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` and `PGID`. If you don't give the volume correct permissions, the +> container may not start. + +## Ports + +* `8000`: HTTP port +* `514 514/udp`: Syslog ports (only used if you enable and run a [sidecar syslog-ng container](#syslog-ng-container)) +* `162 162/udp`: Snmptrapd ports (only used if you enable and run a [sidecar snmptrapd container](#snmptrapd-container)) + +## Usage + +### Docker Compose + +Docker compose is the recommended way to run this image. Copy the content of +folder [examples/compose](examples/compose) in `/var/librenms/` on your host +for example. Edit the compose and env files with your preferences and run the +following commands: + +```console +$ docker-compose up -d +$ docker-compose logs -f +``` + +### Command line + +You can also use the following minimal command: + +```console +$ 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 + +On first launch, an initial administrator user will be created: + +| Login | Password | +|------------|------------| +| `librenms` | `librenms` | + +> **Note** +> +> You can create another one using the [`lnms` command](#lnms-command). + +## Upgrade + +To upgrade to the latest version of LibreNMS, pull the newer image and launch the container. LibreNMS will upgrade automatically: + +```console +$ docker-compose down +$ docker-compose pull +$ docker-compose up -d +``` + +## Notes + +### Edit configuration + +You can edit configuration of LibreNMS by placing `*.php` files inside +`/data/config` folder. Let's say you want to edit the [WebUI config](https://docs.librenms.org/Support/Configuration/#webui-settings). +Create a file called for example `/data/config/webui.php` with this content: + +```php + **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 [docker-compose.yml](examples/compose/docker-compose.yml) +example) or run a simple container like this: + +```console +$ 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.php` with this content: + +```php + **Warning** +> +> `librenms` must be a valid volume already attached to a LibreNMS container. + +### Add a LibreNMS plugin + +You can add [plugins for LibreNMS](https://docs.librenms.org/Extensions/Plugin-System/) +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](https://github.com/monitoring-plugins/monitoring-plugins#readme) +repo, or in the [unofficial fork for Nagios](https://github.com/nagios-plugins/nagios-plugins#readme). + +> **Warning** +> +> Container has to be restarted to propagate changes. + +### Custom alert templates + +You can add [Laravel alert templates](https://docs.librenms.org/Alerting/Templates/#base-templates) +in `/data/alert-templates/`. + +> **Warning** +> +> Container has to be restarted to propagate changes. ## Contributing diff --git a/doc/docker/environment-variables.md b/doc/docker/environment-variables.md deleted file mode 100644 index 2c3e0aa..0000000 --- a/doc/docker/environment-variables.md +++ /dev/null @@ -1,71 +0,0 @@ -## Environment variables - -### General - -* `TZ`: The timezone assigned to the container (default `UTC`) -* `PUID`: LibreNMS user id (default `1000`) -* `PGID`: LibreNMS group id (default `1000`) -* `MEMORY_LIMIT`: PHP memory limit (default `256M`) -* `MAX_INPUT_VARS`: PHP max input vars (default `1000`) -* `UPLOAD_MAX_SIZE`: Upload max size (default `16M`) -* `CLEAR_ENV`: Clear environment in FPM workers (default `yes`) -* `OPCACHE_MEM_SIZE`: PHP OpCache memory consumption (default `128`) -* `LISTEN_IPV6`: Enable IPv6 for Nginx (default `true`) -* `REAL_IP_FROM`: Trusted addresses that are known to send correct replacement addresses (default `0.0.0.0/32`) -* `REAL_IP_HEADER`: Request header field whose value will be used to replace the client address (default `X-Forwarded-For`) -* `LOG_IP_VAR`: Use another variable to retrieve the remote IP address for access [log_format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) on Nginx. (default `remote_addr`) - -### Dispatcher service - -> :warning: Only used if you enable and run a [sidecar dispatcher container](../notes/dispatcher-service.md) - -* `SIDECAR_DISPATCHER`: Set to `1` to enable sidecar dispatcher mode for this container (default `0`) -* `DISPATCHER_NODE_ID`: Unique node ID for your dispatcher service -* `DISPATCHER_ARGS`: Additional args to pass to the [dispatcher service](https://github.com/librenms/librenms/blob/master/librenms-service.py) -* `REDIS_HOST`: Redis host for poller synchronization -* `REDIS_SENTINEL`: Redis Sentinel host for high availability Redis cluster -* `REDIS_SENTINEL_SERVICE`: Redis Sentinel service name (default `librenms`) -* `REDIS_SCHEME`: Redis scheme (default `tcp`) -* `REDIS_PORT`: Redis port (default `6379`) -* `REDIS_PASSWORD`: Redis password -* `REDIS_DB`: Redis database (default `0`) - -### Syslog-ng - -> :warning: Only used if you enable and run a [sidecar syslog-ng container](../notes/syslog-ng.md) - -* `SIDECAR_SYSLOGNG`: Set to `1` to enable sidecar syslog-ng mode for this container (default `0`) - -### Snmptrapd - -> :warning: Only used if you enable and run a [sidecar snmptrapd container](../notes/snmptrapd.md) - -* `SIDECAR_SNMPTRAPD`: Set to `1` to enable sidecar snmptrapd mode for this container (default `0`) -* `SNMP_PROCESSING_TYPE`: Sets which type of processing (`log`, `execute`, and/or `net`) to use with the SNMP trap (default `log,execute,net`) -* `SNMP_USER`: Defines what username to authenticate with (default `librenms_user`) -* `SNMP_AUTH`: Defines what password to authenticate with (default `auth_pass` should not be used, but will work) -* `SNMP_PRIV`: Defines what password to encrypt packages with (default `priv_pass` should not be used, but will work) -* `SNMP_AUTH_PROTO`: Sets what protocol (`MD5`|`SHA`) to use for authentication (default `SHA`) -* `SNMP_PRIV_PROTO`: Sets what protocol (`DES`|`AES`) to use for encryption of packages (default `AES`) -* `SNMP_SECURITY_LEVEL`: Sets what security level (`noauth`|`priv`) to use (default `priv`) -* `SNMP_ENGINEID`: Defines what SNMP EngineID to use (default `1234567890`) -* `SNMP_DISABLE_AUTHORIZATION`: Will disable the above access control checks, and revert to the previous behaviour of accepting all incoming notifications. (default `yes`) - -### Database - -* `DB_HOST`: MySQL database hostname / IP address -* `DB_PORT`: MySQL database port (default `3306`) -* `DB_NAME`: MySQL database name (default `librenms`) -* `DB_USER`: MySQL user (default `librenms`) -* `DB_PASSWORD`: MySQL password (default `librenms`) -* `DB_TIMEOUT`: Time in seconds after which we stop trying to reach the MySQL server (useful for clusters, default `60`) - -### Misc - -* `LIBRENMS_BASE_URL`: URL of your LibreNMS instance (default `/`) -* `LIBRENMS_SNMP_COMMUNITY`: This container's SNMP v2c community string (default `librenmsdocker`) -* `LIBRENMS_WEATHERMAP`: Enable LibreNMS [Weathermap plugin](https://docs.librenms.org/Extensions/Weathermap/) (default `false`) -* `LIBRENMS_WEATHERMAP_SCHEDULE`: CRON expression format (default `*/5 * * * *`) -* `MEMCACHED_HOST`: Hostname / IP address of a Memcached server -* `MEMCACHED_PORT`: Port of the Memcached server (default `11211`) -* `RRDCACHED_SERVER`: RRDcached server (eg. `rrdcached:42217`) diff --git a/doc/docker/ports.md b/doc/docker/ports.md deleted file mode 100644 index 95040bd..0000000 --- a/doc/docker/ports.md +++ /dev/null @@ -1,4 +0,0 @@ -## Ports - -* `8000`: HTTP port -* `514 514/udp`: Syslog ports (only used if you enable and run a [sidecar syslog-ng container](../notes/syslog-ng.md)) diff --git a/doc/docker/volumes.md b/doc/docker/volumes.md deleted file mode 100644 index a32cea1..0000000 --- a/doc/docker/volumes.md +++ /dev/null @@ -1,6 +0,0 @@ -## 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` and `PGID`. If you don't -> give the volume correct permissions, the container may not start. diff --git a/doc/notes/additional-monitoring-plugins.md b/doc/notes/additional-monitoring-plugins.md deleted file mode 100644 index 2a04693..0000000 --- a/doc/notes/additional-monitoring-plugins.md +++ /dev/null @@ -1,7 +0,0 @@ -## Additional Monitoring plugins - -You can add a custom Monitoring plugin in `/data/monitoring-plugins/`. - -> :warning: Container has to be restarted to propagate changes - -Some plugins can be found in the [Monitoring Plugins](https://github.com/monitoring-plugins/monitoring-plugins#readme) repo, or in the [unofficial fork for Nagios](https://github.com/nagios-plugins/nagios-plugins#readme). diff --git a/doc/notes/alert-templates.md b/doc/notes/alert-templates.md deleted file mode 100644 index 58023a7..0000000 --- a/doc/notes/alert-templates.md +++ /dev/null @@ -1,5 +0,0 @@ -## Alert templates - -You can add [Laravel alert templates](https://docs.librenms.org/Alerting/Templates/#base-templates) in `/data/alert-templates/`. - -> :warning: Container has to be restarted to propagate changes diff --git a/doc/notes/dispatcher-service.md b/doc/notes/dispatcher-service.md deleted file mode 100644 index 1151319..0000000 --- a/doc/notes/dispatcher-service.md +++ /dev/null @@ -1,15 +0,0 @@ -## Dispatcher service - -If you want to enable the new [Dispatcher service](https://docs.librenms.org/Extensions/Dispatcher-Service/), you have to run a "sidecar" container (see dispatcher service in [docker-compose.yml](../../examples/compose/docker-compose.yml) example) or run a simple container like this: - -```bash -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 -``` - -> `-v librenms:/data`
-> :warning: `librenms` must be a valid volume already attached to a LibreNMS container diff --git a/doc/notes/edit-config.md b/doc/notes/edit-config.md deleted file mode 100644 index 102710a..0000000 --- a/doc/notes/edit-config.md +++ /dev/null @@ -1,11 +0,0 @@ -## Edit configuration - -You can edit configuration of LibreNMS by placing `*.php` files inside `/data/config` folder. Let's say you want to edit the [WebUI config](https://docs.librenms.org/Support/Configuration/#webui-settings). Create a file called for example `/data/config/webui.php` with this content : - -```php - ⚠️ Container has to be restarted to propagate changes diff --git a/doc/notes/snmptrapd.md b/doc/notes/snmptrapd.md deleted file mode 100644 index 3a3b67d..0000000 --- a/doc/notes/snmptrapd.md +++ /dev/null @@ -1,12 +0,0 @@ -## Snmptrapd - -If you want to enable snmptrapd, you have to run a "sidecar" container (see snmptrapd service in [docker-compose.yml](../../examples/compose/docker-compose.yml) example) or run a simple container like this : - -```bash -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 -``` diff --git a/doc/notes/syslog-ng.md b/doc/notes/syslog-ng.md deleted file mode 100644 index 7e6d736..0000000 --- a/doc/notes/syslog-ng.md +++ /dev/null @@ -1,19 +0,0 @@ -## Syslog-ng - -If you want to enable syslog-ng, you have to run a "sidecar" container (see syslog-ng service in [docker-compose.yml](../../examples/compose/docker-compose.yml) example) or run a simple container like this : - -```bash -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 -``` - -You have to create a configuration file to enable syslog in LibreNMS too. Create a file called for example `/data/config/syslog.php` with this content : - -```php - `-e "DB_HOST=db"`
-> :warning: `db` must be a running MySQL instance - -### First launch - -On first launch, an initial administrator user will be created: - -| Login | Password | -|------------|------------| -| `librenms` | `librenms` | - -You can create another one using the [`lnms` command](notes/lnms-command.md).