feat(fixes): ZabbixAgentMixin, a native Zabbix agent for a host without a container engine (NetOrk/netork#2571)
driver / lint (pull_request) Successful in 16s
driver / standard (pull_request) Successful in 18s
driver / types (pull_request) Successful in 49s
driver / test (3.13) (pull_request) Successful in 1m6s
driver / lowest (pull_request) Successful in 34s
driver / test (3.12) (pull_request) Successful in 1m11s
driver / build (pull_request) Successful in 24s
driver / security (pull_request) Successful in 55s
CI / driver (pull_request) Successful in 2m20s
driver / publish (pull_request) Skipped

configure_zabbix_agent(settings) loads the package index where the driver can,
installs ZABBIX_AGENT_PACKAGE from the host's own packages and, where those have
none and settings["release"] names the server's release line, from Zabbix's
repository (the driver's _add_zabbix_repository); then the driver writes the
configuration and opens the firewall, and the service is enabled and restarted.
Settings that do not hold raise ValueError before anything changes.

zabbix_agent.py holds what is the same on every host, without I/O: the settings
check, the agent's configuration with Server, ServerActive, ListenPort and
Hostname set and the rest kept, and the root command that adds Zabbix's
repository for Debian, Ubuntu, Raspberry Pi OS and the RHEL family, in the
layout before and since 7.2. LldpAgentMixin and ZabbixAgentMixin share the
start step (enable_and_restart).
This commit is contained in:
christianmanivong committed 2026-11-17 04:50:42 +01:00
1 parent 7c0e4fffc5
commit 5217c6e333
8 files changed
+730 -8

No files matched your search

+12
View File
@@ -144,6 +144,7 @@ from napalm_device_types.fixes import (
LldpAgentMixin,
PackageProxyMixin,
SnmpAgentMixin,
ZabbixAgentMixin,
run_fix_steps,
)
from napalm_device_types.health_metrics import HealthMetricsMixin
@@ -343,6 +344,12 @@ from napalm_device_types.virtual_ips import (
)
from napalm_device_types.vm_migration import MigrationPreflightDict
from napalm_device_types.vm_stop_request import VmStopRequestMixin
from napalm_device_types.zabbix_agent import (
ZabbixAgentSettingsDict,
check_zabbix_agent_settings,
zabbix_agent_config,
zabbix_repository_command,
)
__all__ = [
"BACKUP_JOB_KINDS",
@@ -392,6 +399,11 @@ __all__ = [
"SnmpAgentMixin",
"SnmpAgentSettingsDict",
"run_fix_steps",
"ZabbixAgentMixin",
"ZabbixAgentSettingsDict",
"check_zabbix_agent_settings",
"zabbix_agent_config",
"zabbix_repository_command",
"SnmpHealthProfile",
"SnmpInterfacesSpec",
"SnmpMemorySpec",
+126 -7
View File
@@ -16,6 +16,7 @@ They replace ``run_device_action`` (docs/STRUCTURE.md):
``fix_apt_proxy`` :meth:`PackageProxyMixin.configure_package_proxy`
``fix_docker_permissions`` ``ContainerEngineMixin.grant_container_engine_access``
``install_lldpd`` and co. :meth:`EnsurePackageMixin.ensure_package`
(new) :meth:`ZabbixAgentMixin.configure_zabbix_agent`
========================== ===================================================
"""
@@ -31,6 +32,7 @@ from napalm_device_types.models import (
PackageDict,
SnmpAgentSettingsDict,
)
from napalm_device_types.zabbix_agent import ZabbixAgentSettingsDict, check_zabbix_agent_settings
#: One step of a fix: its name and the call that does it.
FixStep = tuple[str, Callable[[], FixStepOutcomeDict]]
@@ -58,6 +60,23 @@ def run_fix_steps(steps: Sequence[FixStep]) -> FixResultDict:
}
def enable_and_restart(
manage_service: Callable[[str, str], dict[str, Any]], service: str
) -> FixStepOutcomeDict:
"""Enable *service* at boot, then restart it so it reads its configuration; not
restarted when it cannot be enabled."""
for action in ("enable", "restart"):
result = manage_service(service, action)
if not result.get("success"):
output = str(result.get("output", "")).strip()
return {"ok": False, "output": f"{action} {service}: {output}".rstrip(": ")}
return {"ok": True, "output": f"{service} enabled and restarted"}
def _joined(*parts: object) -> str:
return "\n".join(str(p).strip() for p in parts if p and str(p).strip())
class SnmpAgentMixin:
"""Run an SNMP agent on the device that answers the caller.
@@ -171,13 +190,7 @@ class LldpAgentMixin:
return {"ok": bool(result["success"]), "output": str(result.get("output", ""))}
def _start_lldp_agent(self) -> FixStepOutcomeDict:
service = self.LLDP_AGENT_SERVICE
for action in ("enable", "restart"):
result = self.manage_service(service, action)
if not result.get("success"):
output = str(result.get("output", "")).strip()
return {"ok": False, "output": f"{action} {service}: {output}".rstrip(": ")}
return {"ok": True, "output": f"{service} enabled and restarted"}
return enable_and_restart(self.manage_service, self.LLDP_AGENT_SERVICE)
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
@@ -193,6 +206,110 @@ class LldpAgentMixin:
...
class ZabbixAgentMixin:
"""Run a native Zabbix agent that answers the caller's server.
For a host without a container engine, where the agent cannot run as a
container. The steps: load the package index where the driver can
(``refresh_available_updates``), install the agent from the host's own packages -- and
where those have none, from Zabbix's repository for ``settings["release"]``
(:func:`~napalm_device_types.zabbix_agent.zabbix_repository_command`) --, write
its configuration (:func:`~napalm_device_types.zabbix_agent.zabbix_agent_config`),
let the allowed sources through the host's firewall, enable and restart it.
Installing and starting are generic, over ``ensure_package`` and
``manage_service`` with ``ZABBIX_AGENT_PACKAGE`` and ``ZABBIX_AGENT_SERVICE``.
Whether Zabbix reaches it is the caller's to ask Zabbix.
The settings are checked before anything changes; ``ValueError`` names the one
that does not hold. A driver that cannot add a repository sets
``_add_zabbix_repository`` to ``None``: its hosts then take the distribution's
package or none.
"""
#: The package that brings the agent, as ``ensure_package`` takes it.
ZABBIX_AGENT_PACKAGE: ClassVar[str] = "zabbix-agent"
#: The agent's service, as ``manage_service`` takes it.
ZABBIX_AGENT_SERVICE: ClassVar[str] = "zabbix-agent"
def configure_zabbix_agent(self, settings: ZabbixAgentSettingsDict) -> FixResultDict:
"""Install, configure, open, enable and restart the agent with *settings*.
:raises ValueError: for settings the agent's configuration cannot take,
before anything changes.
"""
check_zabbix_agent_settings(settings)
return run_fix_steps(
[
("install", lambda: self._install_zabbix_agent(settings)),
("configure", lambda: self._write_zabbix_agent_config(settings)),
("firewall", lambda: self._allow_zabbix_agent_sources(settings)),
("start", self._start_zabbix_agent),
]
)
def _install_zabbix_agent(self, settings: ZabbixAgentSettingsDict) -> FixStepOutcomeDict:
index = self._load_package_index()
first = self.ensure_package(self.ZABBIX_AGENT_PACKAGE)
if first["success"]:
return {"ok": True, "output": _joined(index, first.get("output"))}
release = settings.get("release")
add = getattr(self, "_add_zabbix_repository", None)
if not release or not callable(add):
return {"ok": False, "output": _joined(index, first.get("output"))}
added = add(release)
if not added["ok"]:
return {"ok": False, "output": _joined(index, added.get("output"))}
second = self.ensure_package(self.ZABBIX_AGENT_PACKAGE)
return {
"ok": bool(second["success"]),
"output": _joined(index, added.get("output"), second.get("output")),
}
def _load_package_index(self) -> str:
"""Load the package index where the driver can (OpenWrt keeps it in RAM, gone
after a restart); what went wrong, or "". The install tries either way."""
refresh = getattr(self, "refresh_available_updates", None)
if not callable(refresh):
return ""
loaded = refresh()
if loaded.get("success"):
return ""
return f"package index not loaded: {str(loaded.get('output', '')).strip()}"
def _start_zabbix_agent(self) -> FixStepOutcomeDict:
return enable_and_restart(self.manage_service, self.ZABBIX_AGENT_SERVICE)
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
def ensure_package(self, name: str) -> FixResultDict: ...
def manage_service(self, name: str, action: str) -> dict[str, Any]: ...
def refresh_available_updates(self) -> dict[str, Any]: ...
# The steps a driver implements:
def _add_zabbix_repository(self, release: str) -> FixStepOutcomeDict:
"""Add Zabbix's repository for *release* and refresh the package index
(``zabbix_repository_command`` builds the command for most hosts)."""
...
def _write_zabbix_agent_config(
self, settings: ZabbixAgentSettingsDict
) -> FixStepOutcomeDict:
"""Write *settings* into the agent's configuration file, keeping the rest of
it (``zabbix_agent_config``), and whatever else the device needs before the
agent may start."""
...
def _allow_zabbix_agent_sources(
self, settings: ZabbixAgentSettingsDict
) -> FixStepOutcomeDict:
"""Let ``settings["allowed_sources"]`` reach tcp/``listen_port``; ``ok`` with
nothing to do where the host has no firewall of its own, or for []."""
...
class PackageProxyMixin:
"""Point the device's package manager at a caching proxy."""
@@ -215,5 +332,7 @@ __all__ = [
"LldpAgentMixin",
"PackageProxyMixin",
"SnmpAgentMixin",
"ZabbixAgentMixin",
"enable_and_restart",
"run_fix_steps",
]
+210
View File
@@ -0,0 +1,210 @@
"""A native Zabbix agent: its configuration and Zabbix's package repository.
What :class:`~napalm_device_types.fixes.ZabbixAgentMixin` needs that is the same on
every host, without I/O: which settings an agent may be given
(:func:`check_zabbix_agent_settings`), the agent's configuration file with them
(:func:`zabbix_agent_config`), and the command that adds Zabbix's repository where
the host's own packages have no agent (:func:`zabbix_repository_command`). A driver
reads and writes the file and runs the command.
**Which lines.** ``Server`` (who may ask, for passive checks), ``ServerActive``
(where active checks go), ``ListenPort`` and, when the caller names one,
``Hostname`` -- the host's technical name in Zabbix, which an active agent sends.
Every other line stays as it was; a key the file does not set is added at its end.
**The repository.** Zabbix publishes a ``zabbix-release`` package per release line
and distribution that adds its repository and key. Since 7.2 it lives under
``<release>/release/<distribution>/``; up to 7.0 under ``<release>/<distribution>/``,
with the rpm in an ``x86_64`` directory. The release line is the server's: an agent
may be older than its server, not newer.
"""
from __future__ import annotations
import re
import shlex
from typing import NotRequired, TypedDict
class ZabbixAgentSettingsDict(TypedDict):
"""What the caller wants a native Zabbix agent to be (``ZabbixAgentMixin``)."""
server: str # Server: the addresses that may ask (passive checks), comma-separated
server_active: str # ServerActive: where active checks go, comma-separated; "" for none
listen_port: int # ListenPort
# addresses or CIDRs let through to the port; [] changes no firewall
allowed_sources: list[str]
# Hostname: the host's technical name in Zabbix; absent keeps the agent's
hostname: NotRequired[str]
# the server's release line ("7.4"): Zabbix's repository to fall back to where the
# host's own packages have no agent; absent: no fallback
release: NotRequired[str]
#: Addresses, comma-separated, as ``Server`` and ``ServerActive`` take them: names,
#: IPv4, ``[IPv6]`` and ports. Nothing a config line or a shell word breaks out of.
_ADDRESSES = re.compile(r"^[A-Za-z0-9.:\[\]-]+(,[A-Za-z0-9.:\[\]-]+)*$")
#: What Zabbix allows in a technical host name.
_HOSTNAME = re.compile(r"^[A-Za-z0-9._ -]+$")
#: A release line, as Zabbix's repository names it.
_RELEASE = re.compile(r"^(\d+)\.(\d+)$")
_KEYS = ("Server", "ServerActive", "ListenPort", "Hostname")
_LINE = re.compile(r"^(\s*)(" + "|".join(_KEYS) + r")\s*=\s*(.*?)\s*$")
REPOSITORY = "https://repo.zabbix.com/zabbix"
#: The distributions Zabbix publishes packages for, by ``/etc/os-release``'s ``ID``:
#: the name in the repository's path, and whether they take a deb.
_DISTRIBUTIONS: dict[str, tuple[str, bool]] = {
"ubuntu": ("ubuntu", True),
"debian": ("debian", True),
"raspbian": ("raspbian", True),
"rhel": ("rhel", False),
"centos": ("rhel", False),
"ol": ("oracle", False),
"almalinux": ("alma", False),
"rocky": ("rocky", False),
}
def check_zabbix_agent_settings(settings: ZabbixAgentSettingsDict) -> None:
"""Refuse what an agent's configuration or a shell line cannot take.
:raises ValueError: naming the setting.
"""
_check_addresses("Server", str(settings.get("server", "")), required=True)
_check_addresses("ServerActive", str(settings.get("server_active", "")), required=False)
hostname = settings.get("hostname")
if hostname is not None and not _HOSTNAME.match(hostname):
raise ValueError(f"not a Zabbix host name: {hostname!r}")
port = settings.get("listen_port")
if not isinstance(port, int) or isinstance(port, bool) or not 1 <= port <= 65535:
raise ValueError(f"not a port: {port!r}")
release = settings.get("release")
if release is not None and not _RELEASE.match(release):
raise ValueError(f"not a Zabbix release line (major.minor): {release!r}")
def _check_addresses(key: str, value: str, *, required: bool) -> None:
if (value or required) and not _ADDRESSES.match(value):
raise ValueError(f"not addresses an agent's {key} takes: {value!r}")
def _wanted(settings: ZabbixAgentSettingsDict) -> dict[str, str]:
wanted = {
"Server": settings["server"],
"ServerActive": settings.get("server_active", ""),
"ListenPort": str(settings["listen_port"]),
}
if settings.get("hostname"):
wanted["Hostname"] = str(settings["hostname"])
return wanted
def zabbix_agent_config(text: str, settings: ZabbixAgentSettingsDict) -> tuple[str, list[str]]:
"""*text*, an agent's configuration file, with *settings*; and what changed, one
``"Key: old → new"`` each.
An empty ``server_active`` comments ``ServerActive`` out: the agent then runs
passive checks only.
"""
wanted = _wanted(settings)
lines: list[str] = []
changes: list[str] = []
seen: set[str] = set()
for line in text.splitlines(keepends=True):
match = _LINE.match(line.rstrip("\r\n"))
if not match or match.group(2) not in wanted:
lines.append(line)
continue
seen.add(match.group(2))
lines.append(_set_line(line, match, wanted, changes))
_add_missing(
lines, [key for key in _KEYS if wanted.get(key) and key not in seen], wanted, changes
)
return "".join(lines), changes
def _add_missing(
lines: list[str], keys: list[str], wanted: dict[str, str], changes: list[str]
) -> None:
"""*keys*, which the file does not set, at its end."""
if keys and lines and not lines[-1].endswith("\n"):
lines[-1] += "\n"
for key in keys:
lines.append(f"{key}={wanted[key]}\n")
changes.append(f"{key}: (not set) → {wanted[key]}")
def _set_line(line: str, match: re.Match[str], wanted: dict[str, str], changes: list[str]) -> str:
"""*line*, which sets a key the caller wants, as the caller wants it."""
indent, key, old = match.groups()
end = "\n" if line.endswith("\n") else ""
new = wanted[key]
if not new:
changes.append(f"{key}: {old} → (not set)")
return f"{indent}# {key}={old}{end}"
if old == new:
return line
changes.append(f"{key}: {old} → {new}")
return f"{indent}{key}={new}{end}"
def _os_release(text: str) -> dict[str, str]:
fields = {}
for line in text.splitlines():
key, sep, value = line.partition("=")
if sep:
fields[key.strip()] = value.strip().strip("'\"")
return fields
def _distribution(fields: dict[str, str]) -> tuple[str, bool]:
for candidate in [fields.get("ID", ""), *fields.get("ID_LIKE", "").split()]:
if candidate in _DISTRIBUTIONS:
return _DISTRIBUTIONS[candidate]
raise ValueError(f"Zabbix publishes no repository for {fields.get('ID') or 'this system'}")
def zabbix_repository_command(os_release: str, release: str) -> str:
"""The root command that adds Zabbix's *release* repository to the host whose
``/etc/os-release`` is *os_release*, and refreshes the package index.
:raises ValueError: for a release line that is not ``major.minor``, or a
distribution Zabbix publishes nothing for.
"""
match = _RELEASE.match(release)
if not match:
raise ValueError(f"not a Zabbix release line (major.minor): {release!r}")
fields = _os_release(os_release)
name, deb = _distribution(fields)
version = fields.get("VERSION_ID", "")
new_layout = (int(match.group(1)), int(match.group(2))) >= (7, 2)
base = f"{REPOSITORY}/{release}/" + ("release/" if new_layout else "") + name
if deb:
# Raspberry Pi OS's packages are named after the Debian release they follow.
label = "debian" if name == "raspbian" else name
filename = f"zabbix-release_latest_{release}+{label}{version}_all.deb"
url = f"{base}/pool/main/z/zabbix-release/{filename}"
package = shlex.quote(url)
return (
"t=$(mktemp -d) && "
f'{{ curl -fsSL -o "$t/zabbix-release.deb" {package} '
f'|| wget -qO "$t/zabbix-release.deb" {package}; }} && '
'dpkg -i "$t/zabbix-release.deb" && apt-get update; '
# The download's directory goes either way; the status is the install's.
's=$?; rm -rf "$t"; [ "$s" -eq 0 ]'
)
major = version.split(".")[0]
arch = "noarch" if new_layout else "x86_64"
url = f"{base}/{major}/{arch}/zabbix-release-latest-{release}.el{major}.noarch.rpm"
return f"dnf -y install {shlex.quote(url)}"
__all__ = [
"REPOSITORY",
"ZabbixAgentSettingsDict",
"check_zabbix_agent_settings",
"zabbix_agent_config",
"zabbix_repository_command",
]