netbox-checkmk 0.3.2__py3-none-any.whl

netbox_checkmk/__init__.py

@@ -0,0 +1,41 @@
+from netbox.plugins import PluginConfig
+
+__version__ = "0.3.2"
+
+
+class NetBoxCheckmkConfig(PluginConfig):
+    name = "netbox_checkmk"
+    verbose_name = "Checkmk Status"
+    description = "Shows live Checkmk host and service status on devices, VMs and clusters"
+    version = __version__
+    author = "Christian Wirtz"
+    author_email = "doc@snowheaven.de"
+    base_url = "checkmk"
+    min_version = "4.3.0"
+    default_settings = {
+        # List of Checkmk sites, queried in order; the first site knowing a host wins:
+        # {"name": "main", "url": "https://cmk.example.com/mysite",
+        #  "username": "automation", "secret": "...", "verify_ssl": True, "timeout": 5}
+        "sites": [],
+        # How often (seconds) NetBox fetches fresh state from Checkmk: lookups (also
+        # "host not found") are cached this long, and an open Checkmk tab reloads itself
+        # at this interval.
+        "check_interval": 300,
+        # Custom field (on devices/VMs/clusters) overriding the Checkmk host name.
+        "hostname_custom_field": "checkmk_hostname",
+        # Create that custom field (text, on devices/VMs/clusters) on `manage.py migrate`
+        # if it does not exist yet. An existing field is never modified.
+        "create_custom_field": True,
+        # Max. number of services listed on a device/VM tab (worst state first).
+        "max_services": 500,
+        # Max. number of member devices/VMs evaluated on a cluster tab.
+        "max_cluster_members": 100,
+    }
+
+    def ready(self):
+        super().ready()
+        # Registers the "Checkmk" tab views; must happen before NetBox builds its URLconf.
+        from . import signals, tables, views  # noqa: F401
+
+
+config = NetBoxCheckmkConfig

netbox_checkmk/checkmk.py

@@ -0,0 +1,272 @@
+"""Minimal Checkmk REST API client (monitoring status only).
+
+Deliberately free of Django imports so it can be unit-tested standalone.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from urllib.parse import quote, urlencode
+
+import requests
+
+HOST_COLUMNS = (
+    "name",
+    "state",
+    "has_been_checked",
+    "plugin_output",
+    "acknowledged",
+    "scheduled_downtime_depth",
+    "last_check",
+    "num_services_ok",
+    "num_services_warn",
+    "num_services_crit",
+    "num_services_unknown",
+    "num_services_pending",
+)
+
+SERVICE_COLUMNS = (
+    "description",
+    "state",
+    "has_been_checked",
+    "plugin_output",
+    "acknowledged",
+    "scheduled_downtime_depth",
+)
+
+# Chunk size for multi-host queries, keeps single Livestatus queries reasonably small.
+QUERY_CHUNK = 50
+
+_REGEX_SPECIAL = set(".^$*+?()[]{}|\\")
+
+
+def _regex_literal(value: str) -> str:
+    return "".join("\\" + c if c in _REGEX_SPECIAL else c for c in value)
+
+
+class CheckmkError(Exception):
+    """Raised when a Checkmk site cannot be queried."""
+
+
+# Unified severity, used to pick the "worst" state across hosts and services.
+SEVERITY_OK = 0
+SEVERITY_PENDING = 1
+SEVERITY_WARN = 2
+SEVERITY_UNKNOWN = 3
+SEVERITY_CRIT = 4
+
+HOST_STATES = {0: ("UP", SEVERITY_OK), 1: ("DOWN", SEVERITY_CRIT), 2: ("UNREACH", SEVERITY_UNKNOWN)}
+SERVICE_STATES = {
+    0: ("OK", SEVERITY_OK),
+    1: ("WARN", SEVERITY_WARN),
+    2: ("CRIT", SEVERITY_CRIT),
+    3: ("UNKNOWN", SEVERITY_UNKNOWN),
+}
+
+
+@dataclass
+class ServiceStatus:
+    description: str
+    state: int
+    has_been_checked: bool
+    plugin_output: str = ""
+    acknowledged: bool = False
+    in_downtime: bool = False
+
+    @property
+    def label(self) -> str:
+        if not self.has_been_checked:
+            return "PEND"
+        return SERVICE_STATES.get(self.state, ("UNKNOWN", SEVERITY_UNKNOWN))[0]
+
+    @property
+    def severity(self) -> int:
+        if not self.has_been_checked:
+            return SEVERITY_PENDING
+        return SERVICE_STATES.get(self.state, ("UNKNOWN", SEVERITY_UNKNOWN))[1]
+
+    @classmethod
+    def from_api(cls, ext: dict) -> ServiceStatus:
+        return cls(
+            description=ext.get("description", ""),
+            state=int(ext.get("state", 3)),
+            has_been_checked=bool(ext.get("has_been_checked", 1)),
+            plugin_output=ext.get("plugin_output", ""),
+            acknowledged=bool(ext.get("acknowledged", 0)),
+            in_downtime=bool(ext.get("scheduled_downtime_depth", 0)),
+        )
+
+
+@dataclass
+class HostStatus:
+    name: str
+    state: int
+    has_been_checked: bool
+    plugin_output: str = ""
+    acknowledged: bool = False
+    in_downtime: bool = False
+    last_check: int = 0
+    services: dict = field(default_factory=dict)  # label -> count
+
+    @property
+    def label(self) -> str:
+        if not self.has_been_checked:
+            return "PEND"
+        return HOST_STATES.get(self.state, ("UNKNOWN", SEVERITY_UNKNOWN))[0]
+
+    @property
+    def host_severity(self) -> int:
+        if not self.has_been_checked:
+            return SEVERITY_PENDING
+        return HOST_STATES.get(self.state, ("UNKNOWN", SEVERITY_UNKNOWN))[1]
+
+    @property
+    def worst_service_severity(self) -> int:
+        for label, severity in (
+            ("CRIT", SEVERITY_CRIT),
+            ("UNKNOWN", SEVERITY_UNKNOWN),
+            ("WARN", SEVERITY_WARN),
+            ("PEND", SEVERITY_PENDING),
+        ):
+            if self.services.get(label):
+                return severity
+        return SEVERITY_OK
+
+    @property
+    def severity(self) -> int:
+        """Overall severity: worst of host state and service states."""
+        return max(self.host_severity, self.worst_service_severity)
+
+    @classmethod
+    def from_api(cls, ext: dict) -> HostStatus:
+        return cls(
+            name=ext["name"],
+            state=int(ext.get("state", 0)),
+            has_been_checked=bool(ext.get("has_been_checked", 1)),
+            plugin_output=ext.get("plugin_output", ""),
+            acknowledged=bool(ext.get("acknowledged", 0)),
+            in_downtime=bool(ext.get("scheduled_downtime_depth", 0)),
+            last_check=int(ext.get("last_check", 0) or 0),
+            services={
+                "OK": int(ext.get("num_services_ok", 0)),
+                "WARN": int(ext.get("num_services_warn", 0)),
+                "CRIT": int(ext.get("num_services_crit", 0)),
+                "UNKNOWN": int(ext.get("num_services_unknown", 0)),
+                "PEND": int(ext.get("num_services_pending", 0)),
+            },
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "state": self.state,
+            "has_been_checked": self.has_been_checked,
+            "plugin_output": self.plugin_output,
+            "acknowledged": self.acknowledged,
+            "in_downtime": self.in_downtime,
+            "last_check": self.last_check,
+            "services": dict(self.services),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> HostStatus:
+        return cls(**data)
+
+
+class CheckmkSite:
+    """One Checkmk site, addressed by its site URL, e.g. https://cmk.example.com/mysite."""
+
+    def __init__(
+        self,
+        name: str,
+        url: str,
+        username: str,
+        secret: str,
+        verify_ssl: bool = True,
+        timeout: float = 5,
+        session: requests.Session | None = None,
+    ):
+        self.name = name
+        self.url = url.rstrip("/")
+        self.api_url = f"{self.url}/check_mk/api/1.0"
+        self.verify_ssl = verify_ssl
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.session.headers.update(
+            {"Authorization": f"Bearer {username} {secret}", "Accept": "application/json"}
+        )
+
+    @classmethod
+    def from_config(cls, config: dict) -> CheckmkSite:
+        try:
+            return cls(
+                name=config.get("name") or config["url"],
+                url=config["url"],
+                username=config["username"],
+                secret=config["secret"],
+                verify_ssl=config.get("verify_ssl", True),
+                timeout=config.get("timeout", 5),
+            )
+        except KeyError as e:
+            raise CheckmkError(f"Checkmk site config is missing {e}") from e
+
+    def _query(self, path: str, columns: tuple[str, ...], query: dict) -> dict:
+        # POST variant of the monitoring collection endpoints: works on 2.5 and is the
+        # only one left on 3.0 (the GET variant returns 405 there).
+        try:
+            resp = self.session.post(
+                f"{self.api_url}{path}",
+                json={"columns": list(columns), "query": query},
+                verify=self.verify_ssl,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as e:
+            raise CheckmkError(f"{self.name}: {e.__class__.__name__}: {e}") from e
+        if resp.status_code != 200:
+            try:
+                detail = resp.json().get("detail") or resp.json().get("title")
+            except ValueError:
+                detail = resp.text[:200]
+            raise CheckmkError(f"{self.name}: HTTP {resp.status_code}: {detail}")
+        try:
+            return resp.json()
+        except ValueError as e:
+            raise CheckmkError(f"{self.name}: invalid JSON response") from e
+
+    def get_hosts(self, names: list[str]) -> dict[str, HostStatus]:
+        """Look up hosts by name (case-insensitive).
+
+        Returns a dict keyed by the *requested* name (lowercased) for every host found.
+        """
+        found: dict[str, HostStatus] = {}
+        wanted = sorted({n.lower() for n in names if n})
+        for i in range(0, len(wanted), QUERY_CHUNK):
+            chunk = wanted[i : i + QUERY_CHUNK]
+            query = {
+                "op": "or",
+                "expr": [{"op": "~~", "left": "name", "right": f"^{_regex_literal(n)}$"} for n in chunk],
+            }
+            data = self._query("/domain-types/host/collections/all", HOST_COLUMNS, query)
+            for item in data.get("value", []):
+                host = HostStatus.from_api(item.get("extensions", {}))
+                found.setdefault(host.name.lower(), host)
+        return found
+
+    def get_services(self, host_name: str, limit: int = 500) -> list[ServiceStatus]:
+        """All services of a host, worst state first."""
+        query = {"op": "=", "left": "host_name", "right": host_name}
+        data = self._query("/domain-types/service/collections/all", SERVICE_COLUMNS, query)
+        services = [ServiceStatus.from_api(i.get("extensions", {})) for i in data.get("value", [])]
+        services.sort(key=lambda s: (-s.severity, s.description.lower()))
+        return services[:limit]
+
+    def _view_url(self, **params: str) -> str:
+        return f"{self.url}/check_mk/index.py?" + urlencode(
+            {"start_url": "view.py?" + urlencode(params)}, quote_via=quote
+        )
+
+    def host_url(self, host_name: str) -> str:
+        return self._view_url(view_name="host", host=host_name)
+
+    def service_url(self, host_name: str, service: str) -> str:
+        return self._view_url(view_name="service", host=host_name, service=service)

netbox_checkmk/locale/de/LC_MESSAGES/django.po

@@ -0,0 +1,100 @@
+# German translation of the netbox-checkmk NetBox plugin.
+# Compile with: python scripts/compile_translations.py
+msgid ""
+msgstr ""
+"Project-Id-Version: netbox-checkmk\n"
+"Language: de\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+msgid "Checkmk"
+msgstr "Checkmk"
+
+msgid "Checkmk Monitoring"
+msgstr "Checkmk-Monitoring"
+
+msgid "Refresh"
+msgstr "Aktualisieren"
+
+msgid "Reload from Checkmk (bypass cache)"
+msgstr "Neu aus Checkmk laden (Cache umgehen)"
+
+msgid "Loading Checkmk status…"
+msgstr "Checkmk-Status wird geladen …"
+
+msgid "Checkmk query failed"
+msgstr "Checkmk-Abfrage fehlgeschlagen"
+
+msgid "No Checkmk sites configured. Set PLUGINS_CONFIG['netbox_checkmk']['sites']."
+msgstr "Keine Checkmk-Sites konfiguriert. Bitte PLUGINS_CONFIG['netbox_checkmk']['sites'] setzen."
+
+msgid "Overall state"
+msgstr "Gesamtzustand"
+
+msgid "%(found)s of %(total)s members found in Checkmk"
+msgstr "%(found)s von %(total)s Mitgliedern in Checkmk gefunden"
+
+msgid "Cluster host"
+msgstr "Cluster-Host"
+
+msgid "No Checkmk host named \"%(name)s\""
+msgstr "Kein Checkmk-Host namens \"%(name)s\""
+
+msgid "Member"
+msgstr "Mitglied"
+
+msgid "Checkmk host"
+msgstr "Checkmk-Host"
+
+msgid "Host"
+msgstr "Host"
+
+msgid "Services"
+msgstr "Services"
+
+msgid "Site"
+msgstr "Site"
+
+msgid "Not found in Checkmk"
+msgstr "In Checkmk nicht gefunden"
+
+msgid "This cluster has no member devices or virtual machines."
+msgstr "Dieser Cluster enthält keine Geräte oder virtuellen Maschinen."
+
+msgid "Member list truncated (max_cluster_members)."
+msgstr "Mitgliederliste gekürzt (max_cluster_members)."
+
+msgid "ACK"
+msgstr "ACK"
+
+msgid "Downtime"
+msgstr "Wartungszeit"
+
+msgid "Output"
+msgstr "Ausgabe"
+
+msgid "Last check"
+msgstr "Letzter Check"
+
+msgid "State"
+msgstr "Zustand"
+
+msgid "Service"
+msgstr "Service"
+
+msgid "Acknowledged"
+msgstr "Quittiert"
+
+msgid "Scheduled downtime"
+msgstr "Geplante Wartungszeit"
+
+msgid "Host \"%(name)s\" could not be determined."
+msgstr "Host \"%(name)s\" konnte nicht ermittelt werden."
+
+msgid "No Checkmk host named \"%(name)s\" found on any configured site."
+msgstr "Auf keiner konfigurierten Site wurde ein Checkmk-Host namens \"%(name)s\" gefunden."
+
+msgid "This object has no name to look up in Checkmk."
+msgstr "Dieses Objekt hat keinen Namen, nach dem in Checkmk gesucht werden kann."

netbox_checkmk/signals.py

@@ -0,0 +1,34 @@
+"""Creates the host name override custom field on `manage.py migrate` (if enabled)."""
+
+from django.apps import apps
+from django.db.models.signals import post_migrate
+
+from .status import config
+
+
+def create_custom_field(**kwargs):
+    from core.models import ObjectType
+    from dcim.models import Device
+    from extras.choices import CustomFieldTypeChoices
+    from extras.models import CustomField
+    from virtualization.models import Cluster, VirtualMachine
+
+    name = config("hostname_custom_field")
+    if not name or not config("create_custom_field") or CustomField.objects.filter(name=name).exists():
+        return
+    field = CustomField.objects.create(
+        name=name,
+        type=CustomFieldTypeChoices.TYPE_TEXT,
+        label="Checkmk host name",
+        description="Checkmk host name, if it differs from this object's name (netbox-checkmk plugin)",
+        required=False,
+    )
+    field.object_types.set([ObjectType.objects.get_for_model(m) for m in (Device, VirtualMachine, Cluster)])
+    print(f"netbox_checkmk: created custom field '{name}'")
+
+
+# post_migrate is only sent for apps with models; hook onto NetBox's "extras" app, which
+# owns CustomField. It fires after the whole migrate run, so all tables exist by then.
+post_migrate.connect(
+    create_custom_field, sender=apps.get_app_config("extras"), dispatch_uid="netbox_checkmk_custom_field"
+)

netbox_checkmk/status.py

@@ -0,0 +1,123 @@
+"""Hostname resolution, multi-site lookup and caching on top of the Checkmk client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from django.core.cache import cache
+from netbox.plugins import get_plugin_config
+
+from .checkmk import CheckmkError, CheckmkSite, HostStatus, ServiceStatus
+
+PLUGIN_NAME = "netbox_checkmk"
+CACHE_PREFIX = "netbox_checkmk:v1"
+_NOT_FOUND = "__not_found__"
+
+
+def config(key: str):
+    return get_plugin_config(PLUGIN_NAME, key)
+
+
+def get_sites() -> list[CheckmkSite]:
+    return [CheckmkSite.from_config(c) for c in config("sites") or []]
+
+
+def checkmk_hostname(obj) -> str:
+    """Checkmk host name for a NetBox object: custom field override, else the object name."""
+    cf_name = config("hostname_custom_field")
+    if cf_name:
+        override = (getattr(obj, "custom_field_data", None) or {}).get(cf_name)
+        if override:
+            return str(override).strip()
+    return (getattr(obj, "name", None) or "").strip()
+
+
+@dataclass
+class HostResult:
+    hostname: str
+    site: CheckmkSite | None = None
+    status: HostStatus | None = None
+
+    @property
+    def found(self) -> bool:
+        return self.status is not None
+
+    @property
+    def url(self) -> str | None:
+        return self.site.host_url(self.status.name) if self.found else None
+
+
+@dataclass
+class LookupResult:
+    hosts: dict[str, HostResult] = field(default_factory=dict)  # keyed by lowercased hostname
+    errors: list[str] = field(default_factory=list)
+
+    def get(self, hostname: str) -> HostResult:
+        return self.hosts.get(hostname.lower()) or HostResult(hostname=hostname)
+
+
+def _cache_key(kind: str, *parts: str) -> str:
+    # Hex-encode: memcached-style backends reject spaces/control characters in keys.
+    return ":".join([CACHE_PREFIX, kind] + [p.lower().encode("utf-8").hex() for p in parts])
+
+
+def lookup_hosts(hostnames: list[str], refresh: bool = False) -> LookupResult:
+    """Find hosts across all configured sites (first site that knows a host wins).
+
+    Results (including "not found") are cached for ``check_interval`` seconds. If any
+    site errors, hosts that could not be found are reported as unknown and not cached,
+    since they may well live on the failing site.
+    """
+    result = LookupResult()
+    sites = {s.name: s for s in get_sites()}
+    timeout = config("check_interval")
+    pending = []
+    for name in dict.fromkeys(h for h in hostnames if h):
+        key = name.lower()
+        cached = None if refresh else cache.get(_cache_key("host", name))
+        if cached == _NOT_FOUND:
+            result.hosts[key] = HostResult(hostname=name)
+        elif cached and cached["site"] in sites:
+            result.hosts[key] = HostResult(
+                hostname=name, site=sites[cached["site"]], status=HostStatus.from_dict(cached["status"])
+            )
+        else:
+            pending.append(name)
+
+    for site in sites.values():
+        if not pending:
+            break
+        try:
+            found = site.get_hosts(pending)
+        except CheckmkError as e:
+            result.errors.append(str(e))
+            continue
+        still_pending = []
+        for name in pending:
+            status = found.get(name.lower())
+            if status is None:
+                still_pending.append(name)
+                continue
+            result.hosts[name.lower()] = HostResult(hostname=name, site=site, status=status)
+            cache.set(_cache_key("host", name), {"site": site.name, "status": status.to_dict()}, timeout)
+        pending = still_pending
+
+    for name in pending:
+        result.hosts[name.lower()] = HostResult(hostname=name)
+        if not result.errors:
+            cache.set(_cache_key("host", name), _NOT_FOUND, timeout)
+    return result
+
+
+def host_services(host: HostResult, refresh: bool = False):
+    """All services of a found host (cached). Returns (services, error)."""
+    key = _cache_key("svc", host.site.name, host.status.name)
+    cached = None if refresh else cache.get(key)
+    if cached is not None:
+        return [ServiceStatus(**s) for s in cached], None
+    try:
+        services = host.site.get_services(host.status.name, config("max_services"))
+    except CheckmkError as e:
+        return [], str(e)
+    cache.set(key, [s.__dict__ for s in services], config("check_interval"))
+    return services, None

netbox_checkmk/tables.py

@@ -0,0 +1,34 @@
+"""Optional "Checkmk" column for the core device, VM and cluster lists.
+
+Registered via NetBox's documented plugin API (`register_table_column`). Hidden by default;
+users enable it with "Configure Table". Each cell lazy-loads its badges via htmx, so a list
+page never waits for Checkmk.
+"""
+
+import django_tables2 as tables
+from dcim.tables import DeviceTable
+from django.urls import reverse
+from django.utils.html import format_html
+from django.utils.translation import gettext_lazy as _
+from utilities.tables import register_table_column
+from virtualization.tables import ClusterTable, VirtualMachineTable
+
+
+class CheckmkStatusColumn(tables.Column):
+    def __init__(self):
+        super().__init__(verbose_name=_("Checkmk"), accessor=tables.A("pk"), orderable=False, empty_values=())
+
+    def render(self, record):
+        url = reverse(
+            "plugins:netbox_checkmk:tab_badges",
+            kwargs={"model": record._meta.model_name, "pk": record.pk},
+        )
+        return format_html('<span hx-get="{}?list=1" hx-trigger="load"></span>', url)
+
+    def value(self, record):
+        # CSV/export: live state isn't part of the exported data.
+        return ""
+
+
+for _table in (DeviceTable, VirtualMachineTable, ClusterTable):
+    register_table_column(CheckmkStatusColumn(), "checkmk_status", _table)