tronyx/nagios repository overview

⁠Docker-Nagios

⁠📝 Notes

A fork of JasonRivers' Docker Nagios image⁠ that pulls in fixes from the open pull requests on his repo, along with other updates and quality-of-life improvements.

⁠🙏 Incorporated PRs

Listed here to give the original authors credit for their work.

• #96⁠ - Fix issue with Nagiosgraph source (fregge⁠)
• #101⁠ - Fixes to allow building on ARM aarch64 architecture (garethrandall⁠)
• #110⁠ - Update to Ubuntu 18.04 LTS (asimzeeshan⁠)
• #112⁠ - Add python3-nagiosplugin for plugins that need it (davralin⁠)
• #116⁠ - Update Nagios to 4.4.6 (mmerian⁠)
• #120⁠ - Add NSCA (mmerian⁠)
• #130⁠ - Add Perl encryption libraries (rehashedsalt⁠)
• #132⁠ - Add rsync (LutzLegu⁠)
• #165⁠ - Added libcrypt-x509-perl and libtext-glob-perl modules (Scott-Jones-COS⁠)

⁠✨ Changes That I've Made

Things that I have changed/updated/added to date:

• Updated the image to Ubuntu 26.04 LTS
• Updated Nagios Core, Nagios Plugins, NRPE, NCPA and NSCA to their latest releases
• Added NagiosTV
• Added check_mysql and check_mysql_query, kept check_radius working on Ubuntu 26.04, and fixed check_game not being built
• Built multi-arch images (amd64 & arm64)
• Switched to a multi-stage build, cutting the image size by nearly 60%
• Removed the default web interface password: set your own, or a random one is generated on first start
• Switched stored passwords from unsalted SHA-1 to bcrypt
• Gave a custom NAGIOSADMIN_USER full admin access in the web interface
• Applied NAGIOS_TIMEZONE and NAGIOS_FQDN at startup instead of at build time
• Fixed SMTP relay authentication
• Made the container shut down cleanly within a few seconds
• Hardened the image: binaries and web files are owned by root, and Apache no longer shows its version
• Pinned every upstream source to an exact version, with a workflow that refreshes the pins every other week
• Added CI that lints, smoke-tests and scans every image for vulnerabilities before publishing it, with SBOM and provenance attestations attached

⁠ℹ️ Information

Nagios Core running on Ubuntu 26.04 LTS with NagiosGraph, NRPE, NCPA, NSCA and NagiosTV.

All of the standard Nagios Plugins are included, plus the extras listed under Extra Plugins⁠.

⁠⚙️ Configuration

• Nagios and NSCA: /opt/nagios/etc
• NagiosGraph: /opt/nagiosgraph/etc
• Your own plugins: /opt/Custom-Nagios-Plugins (use this path in your command definitions)

⁠🐳 Docker

The images are available on Docker Hub⁠ and the GitHub Container Registry⁠:

docker pull tronyx/nagios
docker pull ghcr.io/tronyx/nagios

⁠🏷️ Tags

I occasionally create other branches for testing, such as for a new Ubuntu LTS release, but these two are the main ones.

⁠🚀 Running the Container

To try it out with the example configuration:

docker run --name nagios -p 8080:80 tronyx/nagios

To keep your configuration and data outside the container, mount host directories:

docker run --name nagios \
  -v /path/to/nagios/etc:/opt/nagios/etc \
  -v /path/to/nagios/var:/opt/nagios/var \
  -v /path/to/custom-plugins:/opt/Custom-Nagios-Plugins \
  -v /path/to/nagiosgraph/etc:/opt/nagiosgraph/etc \
  -v /path/to/nagiosgraph/var:/opt/nagiosgraph/var \
  -p 8080:80 tronyx/nagios

Empty directories are filled with the default configuration on first start, and the Nagios and NagiosGraph directories are handed to the container's nagios user (UID/GID 5000) on every start.

A few more options:

• To use the GitHub image, replace tronyx/nagios with ghcr.io/tronyx/nagios.
• To accept passive check results from remote hosts via NSCA, also publish its port with -p 5667:5667.
• For best results, give the container access to both IPv4 and IPv6 networks.

⁠🧩 Using Docker Compose

The included docker-compose.yml⁠ uses named volumes by default, with a commented-out bind mount alternative and examples for setting the admin password:

docker compose up -d

⁠🔧 Environment Variables

⁠🔑 Credentials

On first start, the login for NAGIOSADMIN_USER (default nagiosadmin) gets its password from the first of these that's set:

1. The file named by NAGIOSADMIN_PASS_FILE
2. NAGIOSADMIN_PASS
3. If neither is set, a random password is generated and printed once in the container log:

$ docker logs nagios 2>&1 | grep 'Generated password'
Generated password for nagiosadmin: ddUoZ0rcvn4qe6sbami72LGTVnk3vt

With Docker Compose, a secret keeps the password out of the container's environment, where docker inspect would show it:

services:
  nagios:
    environment:
      NAGIOSADMIN_PASS_FILE: /run/secrets/nagiosadmin_pass
    secrets:
      - nagiosadmin_pass

secrets:
  nagiosadmin_pass:
    file: ./nagiosadmin_pass.txt

To change the password later (it prompts for the new one):

docker exec -it nagios htpasswd -B /opt/nagios/etc/htpasswd.users nagiosadmin

This also upgrades a password set by an older version of the image to the stronger bcrypt format.

⁠📡 Using check_radius

check_radius comes from Ubuntu's Monitoring Plugins package, built against radcli⁠, because Nagios Plugins can't build it on Ubuntu 26.04. It takes the same options as before, but needs a radcli configuration listing your RADIUS servers. Copy the default one into your etc volume once:

docker exec nagios sh -c 'cp -r /etc/radcli /opt/nagios/etc/radcli && sed -i "s|/etc/radcli/|/opt/nagios/etc/radcli/|" /opt/nagios/etc/radcli/radiusclient.conf && chown -R nagios:nagios /opt/nagios/etc/radcli && chmod 600 /opt/nagios/etc/radcli/servers'

Then add your servers and shared secrets to /opt/nagios/etc/radcli/servers, and pass -F /opt/nagios/etc/radcli/radiusclient.conf to check_radius.

⁠🔒 Reverse Proxy and TLS

When setting up the proxy:

• Proxy a whole hostname, e.g. https://nagios.example.com/, not a sub-path. Nagios, NagiosGraph and NagiosTV use the absolute paths /nagios/, /cgi-bin/ and /nagiostv/.
• Set NAGIOS_FQDN to that hostname.
• If the proxy reaches the container over a Docker network, you don't need to publish port 80 on the host.

⁠🩺 Health Check

The image's Docker health check reports healthy when Apache is answering requests and Nagios is running. It doesn't log in, so it works whatever password you set.

⁠🔌 Extra Plugins

⁠🛠️ Maintaining the Image

Every upstream source is pinned to an exact version: git repositories to a commit (the *_COMMIT build args), the Ubuntu base image to a digest (BASE_IMAGE), and downloaded files to a SHA-256 checksum. Tagged releases are also checked at build time, so the build fails if a tag has been moved.

• Updating pins: run scripts/update-pinned-checksums.sh⁠, which needs git, curl and docker buildx. It updates both Dockerfiles and summarises what changed; review the diff before committing. The update-pins workflow runs it every other week and opens a pull request against develop.
• Bumping a component: change its *_VERSION build arg (e.g. NAGIOS_VERSION) in both Dockerfiles, then run the script to update its commit and checksums.
• Updating CI tools: buildx, BuildKit and Trivy (in build.yml) and hadolint, shellcheck and actionlint (in lint.yml) are pinned by hand, and the script doesn't update them. Bump them now and then.
• Testing an image: scripts/smoke-test.sh <image> starts the image and checks logins, the web interface, key plugins, file permissions and a clean shutdown. CI runs it on every build before anything is published.