Metadata-Version: 2.4
Name: netbox-checkmk
Version: 0.3.3
Summary: NetBox plugin showing live Checkmk monitoring status on devices, VMs and clusters
Author-email: Christian Wirtz <doc@snowheaven.de>
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitlab.com/checkmk1/netbox_checkmk_plugin
Project-URL: Source, https://gitlab.com/checkmk1/netbox_checkmk_plugin
Project-URL: Changelog, https://gitlab.com/checkmk1/netbox_checkmk_plugin/-/blob/main/CHANGELOG.md
Keywords: netbox,netbox-plugin,checkmk,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: English
Classifier: Natural Language :: German
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests
Dynamic: license-file

# 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.

![Checkmk tab of a device](https://gitlab.com/checkmk1/netbox_checkmk_plugin/-/raw/main/docs/screenshots/device-tab.png)

- **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.

![Checkmk tab of a cluster](https://gitlab.com/checkmk1/netbox_checkmk_plugin/-/raw/main/docs/screenshots/cluster-tab.png)

![Checkmk column in the device list](https://gitlab.com/checkmk1/netbox_checkmk_plugin/-/raw/main/docs/screenshots/device-list.png)

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).

## Dependencies

| Package | Why | Notes |
| --- | --- | --- |
| [`requests`](https://pypi.org/project/requests/) | HTTP calls to the Checkmk REST API | Already part of every NetBox installation, so nothing extra gets installed |

That's all. The plugin has no database models, no static files and no JavaScript of its own: the
asynchronous loading uses the htmx library that NetBox already ships.

## 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:

```sh
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:

```sh
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`](https://pypi.org/project/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`):

```sh
# 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).

```sh
# 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`:

```text
netbox-checkmk
```

`Dockerfile-Plugins`:

```dockerfile
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`:

```yaml
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

```python
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:

```sh
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

```sh
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:

| Checkmk | NetBox `v4.3.7` | `v4.4.10` | `v4.5.10` | `v4.6.10` | `v4.7.2` |
| --- | --- | --- | --- | --- | --- |
| `2.5.0p15` (check-mk-ultimate) | passed | passed | passed | passed | passed |
| `3.0.0-2026.10.12` (check-mk-ultimate daily) | passed | passed | passed | passed | passed |

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](https://gitlab.com/checkmk1/netbox_checkmk_plugin/-/blob/main/LICENSE). Forks and
redistributions must keep the [NOTICE](https://gitlab.com/checkmk1/netbox_checkmk_plugin/-/blob/main/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.*
