search

fboaventura / dckr-mrtg

:whale: Docker MRTG Instance that will configure monitoring from the environment variable.
https://hub.docker.com/r/fboaventura/dckr-mrtg/
MIT License
26 stars 17 forks source link
automated-build docker docker-container docker-hub docker-image mrtg

readme

GitHub license FOSSA Status DockerPulls DockerPulls GitHub forks GitHub stars GitHub issues

fboaventura/dckr-mrtg

Docker instance to run MRTG - The Multi Router Traffic Grapher.

This image is built for all the architectures supported by Alpine image. Although not all of them were tested and validated to be working.

Architecture Validated?
amd64 Yes
arm64v8 Yes
arm32v6 No
arm32v7 No
i386 No
ppc64le No
s390x No
riscv64 No

Table of Contents

Versioning

Until version 2.2.0, I used NGINX, and all the HTML files were statically built by MRTG.
From 2.3.0 onwards, I've implemented the support for rrdtool and replaced NGINX with LIGHTTPD, since I needed the support to run CGI scripts.

From version 2.3.0 the WEBDIR went from /usr/share/nginx/html to /mrtg/html. So please, check all your configuration files if you are getting some path-related error on the graphics.
It's also possible to pass the environment variable WEBDIR on the docker-compose.yml or command line (-e).

Starting on version 2.5.5 the development will be made using branches. The master will be the stable version, and the development will be made on the versioned branches. The auto-build will create images with -dev suffix and pure dev, instead of latest, for the development branches and these images will be deleted as soon as new stable release is made.

MIBs A.K.A. Good to know information

MRTG uses SNMP to monitor the devices. The SNMP protocol look up for an OID (Object Identifier) in the device and return the value of that OID.

OID is the Object Identifier. It is a unique identifier for a piece of data in the MIB. The OID is a sequence of numbers separated by periods. For example, the OID for the device's name is .1.3.6.1.2.1.1.5.

To make life easier, SNMP can use a MIB (Management Information Base) file. The MIB file is a text file that describes the data that can be retrieved from a device. For example, using SNMPv2-MIB file we can reach the device's name using sysName.0 instead of the OID.

Some vendors provide the MIB files for their devices. If you have the MIB file, you can use it to translate the OID to a human-readable name.

This container adds the net-snmp-libs packages that contains these MIB files. You can add your custom MIB files to the /mrtg/mibs folder. And you may find some useful MIB files at OIDView, in the observium repository or, in some cases, at the vendor' support site.

How to use

This instance is published at Docker Hub, and all you need to run is:

$ docker run -d -p 8880:80 -e "HOSTS='public:localhost:2,community:ipaddress'" fboaventura/dckr-mrtg:latest

You can, of course, pass some custom values to make it more prone to your usage. The variables and their defaults are:

Environment

ENV CFGMAKEROPTIONS=""
ENV ENABLE_V6="no"
ENV GRAPHOPTIONS="growright, bits"
ENV GROUPID="101"
ENV HOSTS "community:host[:version[:port]]"
ENV INDEXMAKEROPTIONS=""
ENV MIBSDIR="/mrtg/mibs"
ENV MRTG_COLUMNS=2
ENV PATHPREFIX=""
ENV REGENERATEHTML="yes"
ENV TZ="UTC"
ENV USERID="100"
ENV WEBDIR="/mrtg/html"

The variable CFGMAKEROPTIONS (default: empty string) allows you to add any extra options passed to cfgmaker, e.g. --zero-speed=1000000000 --show-op-down. The options can be found in the manpage for cfgmaker.

The variable ENABLE_V6 (default: "no") will enable IPv6 support in the container. If you need to monitor IPv6 devices, set this to "yes".

The variable GRAPHOPTIONS (default: "growright, bits") will configure the graphs generated by MRTG. The default is to grow the graph from left to right and show the values in bits. You can change this to your needs and the available options can be found here.

The variable GROUPID (default: 101) defines the groupid for the lighttpd user. Normally this value should be set to the same value as USERID, but other values can be used depending on your needs.

The variable HOSTS is where you may set the hosts that MRTG will monitor. The format to be used is community:host[:version[:port]],community:host[:version:[port]],...

Where:

The variable INDEXMAKEROPTIONS (default: empty string) allows you to add any extra options passed to indexmaker, e.g. --nolegend. The options can be found in the manpage for indexmaker.

The variable MIBSDIR (default: "/mrtg/mibs") is the path where the custom MIB files can be stored. If you have custom MIB files, you can mount a volume to this path to make them available to MRTG. Take into consideration that all files in this directory will be loaded by MRTG.

The variable MRTG_COLUMNS (default: 2) defines the number of columns in the index.html file. This is useful if you have a large number of hosts and want to display them in multiple columns.

The variable PATHPREFIX (default: empty string) is the path passed to indexmaker to prefix URLs to rrdviewer or any images. The format must NOT include a trailing slash. For example, "/mrtg" Used with a reverse proxy, this allows mrtg to exist at a subpath rather than the root.

The variable WEBDIR (default: "/mrtg/html") is the path where the HTML files are stored. This is the path where the index.html file is generated and where the RRD files are stored. If you need to change this path, you can set this variable to the desired path.

The variable TZ will configure the timezone used by the OS and MRTG to show dates and times.

The variable USERID (default: 100) defines the userid for the lighttpd user. The files in the html directory will be owned by this user. Normally this value should be set to 1000 (or above), depending on your needs for mapped volumes.

The variable REGENERATEHTML (default: "yes") determines if the index.html file will be regenerated at container restart. The original index.html will be renamed index.old (overwriting any earlier file with that name). You should set this value to anything other than "yes" if you have any custom changes to index.html that you do not want overwritten at container restart.

Persistence

The container will create and use the following directories to store the data and configuration:

If you plan on keeping this instance running as your MRTG service, you may pass volumes to be used to save the information produced by MRTG. To achieve this:

From the command line:

$ mkdir html conf.d
$ docker run -d -p 8880:80 -e "HOSTS='public:localhost,community:ipaddress'" -v `pwd`/html:/mrtg/html -v `pwd`/conf.d:/etc/mrtg/conf.d fboaventura/dckr-mrtg:latest

docker-compose

---
services:
  mrtg:
    image: fboaventura/dckr-mrtg:latest
    hostname: mrtg
    restart: always
    ports:
      - "8880:80"
    volumes:
      - "./conf.d:/etc/mrtg/conf.d"
      - "./html:/mrtg/html"
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/timezone:/etc/timezone:ro"
    environment:
        TZ: "Brazil/East"
        HOSTS: "public:192.168.0.123"
        WEBDIR: "/mrtg/html"
        USERID: 1000
        GROUPID: 1000
        REGENERATEHTML: "yes"
        INDEXMAKEROPTIONS: ""
        CFGMAKEROPTIONS: "--zero-speed=1000000000"
        MRTG_COLUMNS: 2
    tmpfs:
      - "/run"

Once the instance is running, all you have to do is open a web browser and point it to http://localhost:8880 or http://<server_ip>:8880 and you will see the MRTG index page.

ChangeLog

v2.5.6 - 2024.09.20

v2.5.5 - 2024.08.22

v2.5.4 - 2024.07.11

v2.5.3 - 2023.11.25

v2.5.2 - 2023.08.29

v2.5.1 - 2023.01.15

v2.5.0 - 2023.01.15

v2.4.0 - 2022.08.26

v2.3.2 - 2022.08.25

v2.3.1 - 2021.09.03

v2.3.0 - 2021.06

v2.2.0 - 2020.04

v2.1.1 - 2019.10

v1.3 - 2019.08

v1.2 - 2019.05

v1.1 - 2018.10

v1.0.0 - 2017.08

License

FOSSA Status