netbox-checkmk

NetBox plugin that shows live Checkmk monitoring state on devices, virtual machines and clusters, in a dedicated "Checkmk" tab on each object's detail page.

• Tab label badges: the "Checkmk" tab shows the number of OK / WARN / CRIT / UNKNOWN services as number-only badges in the state's color (zero counts hidden), plus a DOWN / UNREACH badge when the host is down. They are visible from every tab of the object.
• Device / Virtual machine tab: host state (UP/DOWN/UNREACH/PEND), acknowledgement and downtime flags, plugin output, service state counts, last check time, and the full service list (worst state first) with each service's output. The host and every service link straight to their views in Checkmk.
• Cluster tab: overall (worst) state across all member devices and VMs, the cluster's own Checkmk host (if one exists with that name), and a member table sorted worst-first. The tab label badges show the service counts summed over all members.
• List column: an optional "Checkmk" column for the device, virtual machine and cluster lists (host state + service counts), enabled per user via Configure Table.
• English and German: the UI follows the NetBox user's language setting.
• Multiple Checkmk sites: queried in configured order; the first site that knows a host wins.
• Non-blocking: the tab loads its content asynchronously (htmx), so a slow or unreachable Checkmk site never delays the NetBox page. State is fetched from Checkmk at most every check_interval seconds (default 300 = 5 min), and an open tab reloads itself at that interval. The tab's Refresh button bypasses the cache.
• Read-only: the plugin only reads monitoring status from the Checkmk REST API.
• Standard plugin APIs only: an extra tab via register_model_view/ViewTab, the list column via register_table_column, and the plugin's own views. NetBox's code and templates are not touched.

The screenshots are generated by the integration test against a throwaway Checkmk site with demo services: SCREENSHOT_DIR=docs/screenshots NETBOX_VERSIONS=v4.7.2 scripts/integration_test.sh. That mode needs python3 on the machine running the script.

Host name mapping

A NetBox object is matched to the Checkmk host with the same name, case-insensitively (NB-VM1 in NetBox finds nb-vm1 in Checkmk). If the names differ, set the custom field Checkmk host name (checkmk_hostname) on the object; its value is then used instead of the object name.

The plugin creates this text custom field for devices, virtual machines and clusters on manage.py migrate if it doesn't exist yet. An existing field with that name is never changed. To name it differently, set hostname_custom_field; to create it yourself, set create_custom_field: False.

Requirements

• NetBox 4.3 or newer
• Checkmk 2.5 or 3.0 (REST API), with a user per site for NetBox (see below).

Checkmk user for NetBox

The plugin only reads, so a dedicated automation user with the built-in "Guest user" role is all it needs. That role may see all hosts and services, and can't change anything. Don't use a personal account: its password ends up in NetBox's configuration.

In each Checkmk site:

1. Setup → Users → Users → Add user
2. Username e.g. netbox, Full name e.g. NetBox
3. Authentication: Automation secret for machine accounts, then generate a secret and copy it
4. Roles: only Guest user; no contact groups, no notifications needed
5. Save and activate changes

Or with the REST API, as an admin. This is the call the integration test uses:

curl -u 'cmkadmin:<password>' -X POST -H 'Content-Type: application/json' \
  https://cmk.example.com/mysite/check_mk/api/1.0/domain-types/user_config/collections/all \
  -d '{"username": "netbox", "fullname": "NetBox", "roles": ["guest"],
       "auth_option": {"auth_type": "automation", "secret": "<long random secret>"}}'

Then put username and secret into the site entry of the configuration (see Configuration below). Check it from the NetBox host:

curl -s -H 'Authorization: Bearer netbox <secret>' \
  https://cmk.example.com/mysite/check_mk/api/1.0/version

Installation

The plugin is on PyPI as netbox-checkmk. Each GitLab release also carries the wheel. The plugin has no database models and no static files. Run manage.py migrate once anyway: that's where it creates its custom field.

Classic installation (/opt/netbox, systemd)

These steps were used on a real NetBox 4.7.1 installation (Debian 13, /opt/netbox, services netbox and netbox-rq):

# 1. Back up the configuration
cp -a /opt/netbox/netbox/netbox/configuration.py /root/configuration.py.bak-$(date +%F)

# 2. Install it into NetBox's venv
/opt/netbox/venv/bin/pip install netbox-checkmk

# 3. So that NetBox's own upgrade.sh reinstalls the plugin on NetBox upgrades
echo netbox-checkmk >> /opt/netbox/local_requirements.txt

4. In /opt/netbox/netbox/netbox/configuration.py, add "netbox_checkmk" to PLUGINS and append the plugin configuration (see Configuration below).

# 5. Validate, create the custom field, restart, check
cd /opt/netbox/netbox && runuser -u netbox -- /opt/netbox/venv/bin/python manage.py check
runuser -u netbox -- /opt/netbox/venv/bin/python manage.py migrate
systemctl restart netbox netbox-rq
systemctl is-active netbox netbox-rq

6. Open a device or VM: the tab bar now has a Checkmk tab.

To update: /opt/netbox/venv/bin/pip install -U netbox-checkmk, then run migrate and restart both services as in step 5.

Without internet access on the NetBox host, copy the wheel there (e.g. to /opt/netbox/local_plugins/), pip install that file, and put its path into local_requirements.txt instead of the package name.

netbox-docker

Build a custom image with the plugin. plugin_requirements.txt:

netbox-checkmk

Dockerfile-Plugins:

FROM netboxcommunity/netbox:v4.7.2
COPY ./plugin_requirements.txt /opt/netbox/
RUN /usr/local/bin/uv pip install --python /opt/netbox/venv/bin/python \
    -r /opt/netbox/plugin_requirements.txt

docker-compose.override.yml:

services:
  netbox:
    image: netbox:latest-plugins
    pull_policy: never
    build:
      context: .
      dockerfile: Dockerfile-Plugins
  netbox-worker:
    image: netbox:latest-plugins
    pull_policy: never
  netbox-housekeeping:
    image: netbox:latest-plugins
    pull_policy: never

Put the configuration into configuration/plugins.py, then run docker compose build --no-cache && docker compose up -d.

The Dockerfile-Plugins build was verified (the plugin installs into the image), and the integration test runs the plugin in the same image with its config in plugins.py. The full docker compose stack itself has not been run.

Configuration

PLUGINS = ["netbox_checkmk"]

PLUGINS_CONFIG = {
    "netbox_checkmk": {
        "sites": [
            {
                "name": "main",                             # label shown in NetBox
                "url": "https://cmk.example.com/mysite",    # site URL, without /check_mk
                "username": "netbox",                       # automation user
                "secret": "…",                              # its automation secret
                "verify_ssl": True,                         # optional, default True
                "timeout": 5,                               # optional, seconds
            },
            # further sites …
        ],
        "check_interval": 300,       # seconds between Checkmk queries (cache + tab auto-reload)
        "hostname_custom_field": "checkmk_hostname",
        "create_custom_field": True,  # create it on `manage.py migrate` if missing
        "max_services": 500,         # services listed on a device/VM tab
        "max_cluster_members": 100,  # members evaluated on a cluster tab
    },
}

Before restarting, check that the NetBox host can reach each Checkmk site:

curl -s -u '<user>:<secret>' https://cmk.example.com/mysite/check_mk/api/1.0/version

Permissions follow NetBox: users only see the tab, and its data, for objects they are allowed to view.

Behaviour on errors

If a site cannot be queried (unreachable, wrong credentials, …), the tab shows a warning naming the site. Hosts that were not found on any reachable site are then reported as "could not be determined" rather than "not found", and that result is not cached.

Development

pip install ruff pytest requests
ruff check . && ruff format --check . && pytest -q          # unit tests (no NetBox needed)

# After editing netbox_checkmk/locale/de/LC_MESSAGES/django.po (no GNU gettext needed):
python scripts/compile_translations.py

# Integration test: real Checkmk site + NetBox per version, all in Docker
CHECKMK_VERSION=2.5.0p15 NETBOX_VERSIONS="v4.3.7 v4.7.2" scripts/integration_test.sh   # default: 4.3 … 4.7

The integration test creates hosts in a throwaway Checkmk site, forces their states via Livestatus, and then checks the tabs and status content through NetBox's own Django stack: automatic custom field creation, case-insensitive matching, the custom field override, cluster aggregation, tab label badges, the list column, host and service links, the German translation, multi-site fallback with a broken site, caching, and permissions. It uses docker create/cp/exec only (no bind mounts, no published ports), so it also works against a remote Docker daemon (DOCKER_CONTEXT/DOCKER_HOST).

CI runs lint and unit tests on every push. The integration test, package build and GitLab release run on tag pushes (vX.Y.Z, which must match __version__).

Tested with

Plugin version 0.3.0, integration test (scripts/integration_test.sh), 2026-10-12:

Also running on a real installation: NetBox 4.7.1 (classic install, Debian 13) with Checkmk 2.5.0p15. Version 0.1.0 was installed by hand via the classic path above, and later versions were rolled out automatically with the same steps.

License

Copyright 2026 Christian Wirtz. Licensed under the Apache License 2.0. Forks and redistributions must keep the NOTICE file (section 4(d) of the license).

NetBox is a trademark of NetBox Labs, Inc. Checkmk is a trademark of Checkmk GmbH. This project is an unofficial, independent community project and is not affiliated with or endorsed by NetBox Labs or Checkmk GmbH.