diff --git a/CHANGELOG.md b/CHANGELOG.md index 6898c5a..f7e7ce6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ All notable changes to this driver. The format follows ## [Unreleased] ### Added +- Time sync through OpenMediaVault's own settings (NetOrk/netork#2370). napalm-linux brings + napalm-device-types' `PosixTimeSyncMixin` (4.35.0), whose write -- a chrony drop-in with + the other sources commented out, `timedatectl set-timezone` -- OMV would take back the + next time it deploys `conf.system.time`. `get_time_sync()` reads the servers and the zone + of the web UI (`System.getTimeSettings`; no servers while NTP is switched off) and the + host's own word on whether the clock is synchronised and by which client. + `configure_time_sync()` writes both through `System.setTimeSettings` (switching NTP on + for servers) and deploys only the modules that made dirty, plus `chrony` and `timezone` + if they already were (`Config.applyChanges`); changes pending in the web UI for other + modules stay pending. A value OMV already has is not written again, and nothing is + written to the host's files. - Personal accounts on OpenMediaVault follow what the person changes (NetOrk/netork#2013): `add_local_account(..., replaces=[...])` takes the old keys out of OMV's own key store (through `UserMgmt.setUser`, applying only what that made dirty) and @@ -20,7 +31,7 @@ All notable changes to this driver. The format follows sudo. The account stays open and in `_ssh`. ### Changed -- Needs napalm-device-types 4.29.0 and napalm-linux 0.17.0. +- Needs napalm-device-types 4.35.0 and napalm-linux 0.17.0. ### Added - Scheduled jobs (NetOrk/netork#1933, #18), on top of napalm-linux's reading and writers. diff --git a/README.md b/README.md index 01d1512..1e33c08 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,17 @@ with driver("192.0.2.10", "admin", "secret", optional_args={"sudo_password": "se | `manage_scheduled_job` | an OMV job: `Cron.set` with only `enable` changed, or `Cron.execute` followed through `Exec.getOutput` (stopped after 300 s); a power-management job is not run; anything else as napalm-linux, never a generated file | | `put_scheduled_job` | an OMV job through `Cron.set`, in the web UI like any other, its comment `napalm-scheduled-job: `; a multi-line command is fine | | `delete_scheduled_job` | an application's OMV job through `Cron.delete`; an application's Linux job as napalm-linux | +| `get_time_sync` | the servers and the zone of OMV's web UI (`System.getTimeSettings`; no servers while NTP is off); synchronised and the client from napalm-linux's reading of the host | +| `configure_time_sync` | servers (NTP switched on) and zone through `System.setTimeSettings`, then `Config.applyChanges` for the modules that made dirty (`chrony`, `timezone`); a value OMV already has is not written again | | everything of napalm-linux | packages, updates, services, users, processes, Docker, … | Every scheduled-job write through RPC deploys the `cron` module alone (`Config.applyChanges`): changes left pending in the web UI for other modules stay pending. +Time sync never writes the host's files the way napalm-linux does (a chrony drop-in, +`timedatectl set-timezone`): OpenMediaVault generates `chrony.conf` and the zone from +`conf.system.time` and would write over them. + "Upgrade everything" is a full upgrade (`FULL_UPGRADE = True`): a plain `apt-get upgrade` holds back OpenMediaVault's own packages and the kernel. diff --git a/napalm_openmediavault/_time_sync.py b/napalm_openmediavault/_time_sync.py new file mode 100644 index 0000000..7d6340c --- /dev/null +++ b/napalm_openmediavault/_time_sync.py @@ -0,0 +1,127 @@ +"""Time sync on OpenMediaVault: its servers and zone through its own database (NetOrk/netork#2370). + +napalm-linux brings napalm-device-types' ``PosixTimeSyncMixin``: it reads chrony's +files and ``timedatectl``, and writes a drop-in under ``/etc/chrony/sources.d`` +(commenting out every other source) and ``timedatectl set-timezone``. OMV generates +``/etc/chrony/chrony.conf`` and the zone from ``conf.system.time`` (``ntp.enable``, +``ntp.timeservers``, ``timezone``) through Salt, so such a write would be taken back +the next time OMV deploys its time settings -- and the web UI would go on showing +its own servers. + +So the servers and the zone are the web UI's: read with ``System.getTimeSettings``, +written with ``System.setTimeSettings`` -- NTP switched on, the servers as OMV keeps +them, one comma-separated string -- and deployed with ``Config.applyChanges`` for +the modules that change made dirty, plus ``chrony`` and ``timezone`` if they already +were; changes left pending in the web UI for other modules stay pending. With NTP +switched off OMV stops chronyd, and the servers it still lists count for nothing: +none are read. A value OMV already has is not written again. Whether the clock is +synchronised, and by which client, is still the host's own reading. +""" + +from __future__ import annotations + +import re +from typing import TYPE_CHECKING, Any + +from napalm_device_types import PosixTimeSyncMixin + +if TYPE_CHECKING: + from napalm_device_types import TimeSyncDict + from napalm_device_types.models import FixStepOutcomeDict + +#: The fields of ``getTimeSettings`` that ``setTimeSettings`` takes back (not ``date``). +_SET_FIELDS = ("timezone", "ntpenable", "ntptimeservers", "ntpclients") +#: The modules OMV regenerates from ``conf.system.time``. +_TIME_MODULES = frozenset({"chrony", "timezone"}) +_SERVER_SEPARATOR = re.compile(r"[,\s]+") +_APPLY_TIMEOUT = 600 + + +def omv_servers(settings: dict[str, Any]) -> list[str]: + """The servers OMV keeps time with: none while NTP is switched off.""" + if not _enabled(settings.get("ntpenable")): + return [] + return [s for s in _SERVER_SEPARATOR.split(str(settings.get("ntptimeservers") or "")) if s] + + +def _enabled(value: object) -> bool: + if isinstance(value, str): + return value.strip().lower() in {"1", "true", "yes", "on"} + return bool(value) + + +class OmvTimeSyncMixin(PosixTimeSyncMixin): + """The POSIX time sync, with the servers and the zone of OMV's web UI (module docstring).""" + + if TYPE_CHECKING: + + def _omv_rpc( + self, + service: str, + method: str, + params: dict[str, Any] | None = None, + timeout: float = 60, + ) -> Any: ... + + def _omv_dirty_modules(self) -> list[str]: ... + + def _omv_time_settings(self) -> dict[str, Any]: + """``System.getTimeSettings``. + + :raises RuntimeError: when OMV refuses, or answers with something else. + """ + settings = self._omv_rpc("System", "getTimeSettings") + if not isinstance(settings, dict): + raise RuntimeError(f"System.getTimeSettings answered {settings!r}") + return settings + + def get_time_sync(self) -> TimeSyncDict: + """OMV's servers and zone, the host's word on whether the clock is synchronised. + + :raises RuntimeError: when ``System.getTimeSettings`` failed. + :raises ValueError: when the host's reading came back cut short. + """ + settings = self._omv_time_settings() + host = super().get_time_sync() + return { + "ntp_servers": omv_servers(settings), + "timezone": str(settings.get("timezone") or "") or None, + "synchronized": host["synchronized"], + "daemon": host["daemon"], + } + + def _write_ntp_servers(self, servers: list[str]) -> FixStepOutcomeDict: + settings = self._omv_time_settings() + if [s.lower() for s in omv_servers(settings)] == [s.lower() for s in servers]: + return {"ok": True, "output": "OpenMediaVault already keeps time with these servers"} + applied = self._omv_save_time(settings, ntpenable=True, ntptimeservers=",".join(servers)) + return {"ok": True, "output": f"set OpenMediaVault's time servers; applied {applied}"} + + def _write_time_zone(self, zone: str) -> FixStepOutcomeDict: + settings = self._omv_time_settings() + if settings.get("timezone") == zone: + return {"ok": True, "output": f"OpenMediaVault is already in {zone}"} + applied = self._omv_save_time(settings, timezone=zone) + return { + "ok": True, + "output": f"set OpenMediaVault's time zone to {zone}; applied {applied}", + } + + def _omv_save_time(self, settings: dict[str, Any], **changes: Any) -> str: + """``setTimeSettings`` with *changes* over *settings*, then apply what that made + dirty, and the time modules already dirty; what was applied. + + :raises RuntimeError: when OMV refuses. + """ + params = {field: settings[field] for field in _SET_FIELDS if field in settings} + params.update(changes) + before = set(self._omv_dirty_modules()) + self._omv_rpc("System", "setTimeSettings", params) + after = set(self._omv_dirty_modules()) + modules = sorted((after - before) | (after & _TIME_MODULES)) + if modules: + # Salt restarts chronyd and sets the zone: give it time. + self._omv_rpc( + "Config", "applyChanges", {"modules": modules, "force": False}, _APPLY_TIMEOUT + ) + return ", ".join(modules) or "nothing" diff --git a/napalm_openmediavault/openmediavault.py b/napalm_openmediavault/openmediavault.py index 0479e8b..bcbaacb 100644 --- a/napalm_openmediavault/openmediavault.py +++ b/napalm_openmediavault/openmediavault.py @@ -39,6 +39,7 @@ from napalm_linux.linux import LinuxDriver from napalm_openmediavault._local_accounts import OmvLocalAccountsMixin from napalm_openmediavault._scheduled_jobs import OmvScheduledJobsMixin +from napalm_openmediavault._time_sync import OmvTimeSyncMixin logger = logging.getLogger(__name__) @@ -161,7 +162,7 @@ def _pool_of(disk: str, members: dict[str, str]) -> str: class OpenMediaVaultDriver( - OmvLocalAccountsMixin, OmvScheduledJobsMixin, StorageDriver, LinuxDriver + OmvLocalAccountsMixin, OmvScheduledJobsMixin, OmvTimeSyncMixin, StorageDriver, LinuxDriver ): """NAPALM driver for OpenMediaVault NAS systems. @@ -171,7 +172,8 @@ class OpenMediaVaultDriver( Inherits all Linux OS functionality from LinuxDriver (packages, services, users, processes, scheduled jobs, Docker) -- OMV really is Debian, so apt applies -- and adds OMV-specific storage management on top. The scheduled - jobs of OMV's web UI go through its RPC (``_scheduled_jobs``). + jobs of OMV's web UI go through its RPC (``_scheduled_jobs``), and so do its + time servers and zone (``_time_sync``). NAS services are ``get_storage_services()``; the systemd service list stays ``get_services()``. Two names for two different things. diff --git a/pyproject.toml b/pyproject.toml index d31a6f3..77cb0af 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,7 +27,7 @@ classifiers = [ ] dependencies = [ "napalm>=4.0", - "napalm-device-types>=4.29.0", + "napalm-device-types>=4.35.0", "napalm-linux>=0.17.0", ] diff --git a/tests/test_time_sync.py b/tests/test_time_sync.py new file mode 100644 index 0000000..c397e63 --- /dev/null +++ b/tests/test_time_sync.py @@ -0,0 +1,337 @@ +"""OpenMediaVault keeps its time servers and zone in its own database (NetOrk/netork#2370). + +OMV generates ``/etc/chrony/chrony.conf`` and the zone from ``conf.system.time`` +(``ntp.enable``, ``ntp.timeservers``, ``timezone``) through Salt. napalm-linux's +POSIX write -- a drop-in under ``sources.d`` with every other source commented out, +``timedatectl set-timezone`` -- would be taken back the next time OMV deploys its +time settings, and the web UI would keep showing its own servers. So the servers +and the zone are read from and written to ``System.getTimeSettings`` / +``setTimeSettings``, then ``Config.applyChanges`` deploys the modules that change +made dirty (``chrony``, ``timezone``) -- and nothing someone left pending in the +web UI for other modules. Whether the clock is synchronised, and by which client, +is still the host's reading. + +The answers are shaped like OMV 7's ``System.getTimeSettings`` (``date`` aside, the +fields of ``conf.system.time``; the servers one comma-separated string). +""" + +from __future__ import annotations + +import json +import shlex + +import pytest +from napalm_device_types import CommandResult, UnknownTimezone + +from napalm_openmediavault.openmediavault import OpenMediaVaultDriver + +#: The host's own reading, as PosixTimeSyncMixin's command prints it on OMV 7: chronyd +#: runs, with the chrony.conf OMV generated, and a selected source. +READING = """\ +@@ts timedatectl +Timezone=Europe/Berlin +NTP=yes +NTPSynchronized=yes +@@ts zone +Europe/Berlin +@@ts active +chrony chrony active +chronyd chrony active +systemd-timesyncd systemd-timesyncd inactive +@@ts timesync +@@ts chronyc +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +^* 192.0.2.1 2 6 377 40 -45us[ -63us] +/- 10ms +@@ts chrony 0 main /etc/chrony/chrony.conf +# This file is auto-generated by openmediavault (https://www.openmediavault.org) +# WARNING: Do not edit this file, your changes will get lost. +pool pool.ntp.org iburst +driftfile /var/lib/chrony/chrony.drift +makestep 1.0 3 +rtcsync + +@@ts end +""" + +#: ``System.getTimeSettings`` on OMV 7, as ``omv-rpc`` prints it. +SETTINGS = { + "date": {"local": "Tue Nov 11 10:00:00 2026", "ISO8601": "2026-11-11T10:00:00+01:00"}, + "timezone": "Europe/Berlin", + "ntpenable": True, + "ntptimeservers": "pool.ntp.org", + "ntpclients": "192.0.2.0/24", +} + +#: What OMV marks dirty when ``conf.system.time`` changes. +_TIME_MODULES = {"ntptimeservers": "chrony", "ntpenable": "chrony", "timezone": "timezone"} + + +class Omv: + """The NAS: omv-rpc and the dirty-modules file as ``_sudo_status`` sees them, and the + host's reading as ``run_command`` does.""" + + def __init__(self, *, settings=None, dirty=("apt", "rsyslog"), fail=""): + self.settings = dict(SETTINGS if settings is None else settings) + self.dirty = list(dirty) + self.fail = fail + self.calls: list[tuple[str, str, object]] = [] + self.commands: list[tuple[str, bool]] = [] + + def sudo_status(self, command: str, read_timeout: float = 100) -> tuple[str, int | None]: + if command.startswith("cat /var/lib/openmediavault/dirtymodules.json"): + return json.dumps(self.dirty), 0 + argv = shlex.split(command) + assert argv[:3] == ["omv-rpc", "-u", "admin"], command + service, method = argv[3], argv[4] + params = json.loads(argv[5]) if len(argv) > 5 else None + self.calls.append((service, method, params)) + if f"{service}.{method}" == self.fail: + return '{"response":null,"error":{"message":"boom"}}', 1 + if (service, method) == ("System", "getTimeSettings"): + return json.dumps(self.settings), 0 + if (service, method) == ("System", "setTimeSettings"): + assert isinstance(params, dict) + for field, value in params.items(): + if self.settings.get(field) != value and _TIME_MODULES.get(field): + if _TIME_MODULES[field] not in self.dirty: + self.dirty.append(_TIME_MODULES[field]) + self.settings.update(params) + return json.dumps(params), 0 + if (service, method) == ("Config", "applyChanges"): + assert isinstance(params, dict) + self.dirty = [m for m in self.dirty if m not in params["modules"]] + return "null", 0 + raise AssertionError(command) + + def run_command(self, command, *, privileged=False, timeout=60, stdin=None): # type: ignore[no-untyped-def] + self.commands.append((command, privileged)) + assert "@@ts" in command, command + return CommandResult(READING, "", 0) + + def call(self, method: str) -> list[object]: + return [params for s, m, params in self.calls if f"{s}.{m}" == method] + + +def _driver(omv: Omv) -> OpenMediaVaultDriver: + driver = OpenMediaVaultDriver("nas", "admin", "p") + driver._sudo_status = omv.sudo_status # type: ignore[method-assign] + driver.run_command = omv.run_command # type: ignore[method-assign] + return driver + + +# -- reading --------------------------------------------------------------------------------- + + +def test_servers_and_zone_are_omvs_the_clock_is_the_hosts(): + omv = Omv(settings={**SETTINGS, "ntptimeservers": "ntp1.example.org,192.0.2.1"}) + + assert _driver(omv).get_time_sync() == { + "ntp_servers": ["ntp1.example.org", "192.0.2.1"], + "timezone": "Europe/Berlin", + "synchronized": True, + "daemon": "chrony", + } + + +def test_the_reading_changes_nothing(): + omv = Omv() + + _driver(omv).get_time_sync() + + assert [m for _s, m, _p in omv.calls] == ["getTimeSettings"] + assert not any(privileged for _c, privileged in omv.commands) + + +def test_servers_separated_by_spaces_as_well(): + omv = Omv(settings={**SETTINGS, "ntptimeservers": " ntp1.example.org, ntp2.example.org "}) + + assert _driver(omv).get_time_sync()["ntp_servers"] == ["ntp1.example.org", "ntp2.example.org"] + + +@pytest.mark.parametrize("off", [False, "0", "false", None]) +def test_ntp_switched_off_is_no_servers(off): + """OMV stops chronyd with NTP off: the servers it still lists keep nothing.""" + omv = Omv(settings={**SETTINGS, "ntpenable": off}) + + assert _driver(omv).get_time_sync()["ntp_servers"] == [] + + +def test_ntp_on_as_the_database_spells_it(): + omv = Omv(settings={**SETTINGS, "ntpenable": "1"}) + + assert _driver(omv).get_time_sync()["ntp_servers"] == ["pool.ntp.org"] + + +def test_an_answer_that_is_no_object_raises(): + omv = Omv() + driver = _driver(omv) + driver._sudo_status = lambda command, read_timeout=100: ("null", 0) # type: ignore[method-assign] + + with pytest.raises(RuntimeError, match="getTimeSettings"): + driver.get_time_sync() + + +def test_no_zone_stored_is_none(): + omv = Omv(settings={**SETTINGS, "timezone": ""}) + + assert _driver(omv).get_time_sync()["timezone"] is None + + +def test_unreadable_settings_raise(): + omv = Omv(fail="System.getTimeSettings") + + with pytest.raises(RuntimeError, match="getTimeSettings"): + _driver(omv).get_time_sync() + + +# -- writing --------------------------------------------------------------------------------- + + +def test_servers_go_through_omvs_settings(): + omv = Omv() + + result = _driver(omv).configure_time_sync(ntp_servers=["ntp1.example.org", "192.0.2.1"]) + + assert result["success"], result["output"] + assert omv.call("System.setTimeSettings") == [ + { + "timezone": "Europe/Berlin", + "ntpenable": True, + "ntptimeservers": "ntp1.example.org,192.0.2.1", + "ntpclients": "192.0.2.0/24", + } + ] + assert [s["step"] for s in result["steps"]] == ["ntp_servers", "verify"] + + +def test_servers_switch_ntp_on(): + omv = Omv(settings={**SETTINGS, "ntpenable": False}) + + _driver(omv).configure_time_sync(ntp_servers=["ntp1.example.org"]) + + (params,) = omv.call("System.setTimeSettings") + assert isinstance(params, dict) + assert params["ntpenable"] is True + + +def test_only_what_the_change_made_dirty_is_applied(): + omv = Omv() + + _driver(omv).configure_time_sync(ntp_servers=["ntp1.example.org"]) + + assert omv.call("Config.applyChanges") == [{"modules": ["chrony"], "force": False}] + assert omv.dirty == ["apt", "rsyslog"] + + +def test_zone_goes_through_omvs_settings(): + omv = Omv() + + result = _driver(omv).configure_time_sync(timezone="America/New_York") + + assert result["success"], result["output"] + (params,) = omv.call("System.setTimeSettings") + assert isinstance(params, dict) + assert params["timezone"] == "America/New_York" + assert params["ntptimeservers"] == "pool.ntp.org" + assert omv.call("Config.applyChanges") == [{"modules": ["timezone"], "force": False}] + + +def test_a_time_module_already_dirty_is_applied_as_well(): + omv = Omv(dirty=("apt", "timezone")) + + _driver(omv).configure_time_sync(ntp_servers=["ntp1.example.org"]) + + (apply,) = omv.call("Config.applyChanges") + assert isinstance(apply, dict) + assert apply["modules"] == ["chrony", "timezone"] + + +def test_nothing_on_the_host_itself_is_written(): + """No drop-in, no commented-out line, no ``timedatectl``: OMV would take them back.""" + omv = Omv() + + _driver(omv).configure_time_sync(ntp_servers=["ntp1.example.org"], timezone="Europe/Paris") + + assert not any(privileged for _c, privileged in omv.commands) + + +def test_the_same_values_again_change_nothing(): + omv = Omv() + + result = _driver(omv).configure_time_sync( + ntp_servers=["POOL.ntp.org"], timezone="Europe/Berlin" + ) + + assert result["success"], result["output"] + assert omv.call("System.setTimeSettings") == [] + assert omv.call("Config.applyChanges") == [] + + +def test_written_twice_is_written_once(): + omv = Omv() + driver = _driver(omv) + + driver.configure_time_sync(ntp_servers=["ntp1.example.org"], timezone="Europe/Paris") + driver.configure_time_sync(ntp_servers=["ntp1.example.org"], timezone="Europe/Paris") + + assert len(omv.call("System.setTimeSettings")) == 2 # servers, zone: the first time only + assert len(omv.call("Config.applyChanges")) == 2 + + +def test_both_in_one_run(): + omv = Omv() + + result = _driver(omv).configure_time_sync( + ntp_servers=["ntp1.example.org"], timezone="Europe/Paris" + ) + + assert result["success"], result["output"] + assert [s["step"] for s in result["steps"]] == ["ntp_servers", "timezone", "verify"] + assert omv.settings["ntptimeservers"] == "ntp1.example.org" + assert omv.settings["timezone"] == "Europe/Paris" + + +def test_a_refused_setting_fails_the_step_and_applies_nothing(): + omv = Omv(fail="System.setTimeSettings") + + result = _driver(omv).configure_time_sync(ntp_servers=["ntp1.example.org"]) + + assert not result["success"] + assert result["steps"][-1]["step"] == "ntp_servers" + assert "setTimeSettings" in result["steps"][-1]["output"] + assert omv.call("Config.applyChanges") == [] + + +def test_a_failed_apply_fails_the_step(): + omv = Omv(fail="Config.applyChanges") + + result = _driver(omv).configure_time_sync(timezone="Europe/Paris") + + assert not result["success"] + assert result["steps"][-1]["step"] == "timezone" + + +@pytest.mark.parametrize( + ("kwargs", "error"), + [ + ({"ntp_servers": ["bad server"]}, ValueError), + ({"ntp_servers": []}, ValueError), + ({"timezone": "CET-1CEST,M3.5.0,M10.5.0/3"}, UnknownTimezone), + ({}, ValueError), + ], +) +def test_the_contracts_refusals_run_nothing(kwargs, error): + omv = Omv() + + with pytest.raises(error): + _driver(omv).configure_time_sync(**kwargs) + + assert omv.calls == [] + assert omv.commands == [] + + +def test_offered_as_a_capability_for_both_values(): + assert callable(getattr(OpenMediaVaultDriver, "get_time_sync", None)) + assert callable(getattr(OpenMediaVaultDriver, "configure_time_sync", None)) + assert OpenMediaVaultDriver.time_sync_writes == frozenset({"ntp_servers", "timezone"})