feat(time-sync): NTP servers and time zone through TimeSyncMixin #36

Merged
christianmanivong merged 1 commits from feature/time-sync-2364 into main 2026-11-11 14:30:43 +00:00
8 changed files with 870 additions and 37 deletions

No files matched your search

+21 -2
View File
@@ -8,6 +8,19 @@ recorded here; their history is the git log.
## [Unreleased]
### Added
- Time sync (napalm-device-types `TimeSyncMixin`, NetOrk/netork#2364): `get_time_sync()`
reads the router's NTP servers and its zone from one `uci -q show system`;
`configure_time_sync()` writes both. The servers replace `system.ntp.server`, enable
the client and turn off the servers of a DHCP lease (`use_dhcp=0`), so the router
takes time from exactly these; `sysntpd` restarts. The zone is written as its name
(`zonename`, in LuCI's spelling) and its POSIX rule (`timezone`, from
napalm-device-types' `posix_tz`), then `/etc/init.d/system reload` and a restart of
logd apply it -- the rule, not the name, is what libc reads (NetOrk/netork#1849). A
value the router already has is not written again and nothing restarts. The zone
reads by its name only where the rule in force is that zone's: a router whose rule
differs from its `zonename`, or that has a rule only, reads as the one zone with that
rule, or as no zone where several share it. `synchronized` is None: BusyBox ntpd keeps
no state to read.
- `get_host_status()` (napalm-device-types `HostStatusMixin`), over an SSH exec channel:
whether the router needs a reboot, how full its filesystems are, and -- with
napalm-device-types 4.32 or newer -- whether apk (OpenWrt 25.12) or opkg (before) was
@@ -32,8 +45,12 @@ recorded here; their history is the git log.
to do on every poll (#8). Needs napalm-device-types with `LldpAgentMixin`.
### Changed
- The floor on napalm-device-types is 4.26.0, the first release with `PosixScheduledJobsMixin`
(it was 4.24.0, for the shared `lldpctl` parser).
- `get_ntp_servers()` and `get_ntp_peers()` read over an SSH exec channel, with the same
reading as `get_time_sync()`, and name no servers while the NTP client is disabled
(`system.ntp.enabled='0'`): sysntpd then starts no ntpd.
- The floor on napalm-device-types is 4.35.0, the first release with `TimeSyncMixin`
(it was 4.26.0 for `PosixScheduledJobsMixin`, and 4.24.0 for the shared `lldpctl`
parser before that).
- Python 3.12 is the floor (`requires-python = ">=3.12"`): netOrk runs every driver
on 3.12, so 3.10 and 3.11 are no longer tested (NAPALM/driver-standard#6).
- The floor on napalm is 5.1: older releases import `pkg_resources`, which a Python
@@ -45,6 +62,8 @@ recorded here; their history is the git log.
`manage_service("lldpd", "enable")` and `manage_service("lldpd", "start")` (#8).
### Fixed
- `get_ntp_servers()` names every server of the `system.ntp.server` list; it kept only
the first, as uci prints a list as `'a' 'b' 'c'` on one line.
- `get_lldp_neighbors()` and `get_lldp_neighbors_detail()` keep an interface name with
a dot whole: the neighbours of a VLAN interface such as `eth0.1` used to come back
under `eth0` with every field empty (#26). A neighbour that names its port by MAC
+18
View File
@@ -69,6 +69,8 @@ device.close()
| `get_scheduled_jobs()` | ✅ | BusyBox crond's `/etc/crontabs/<user>`, time zone from `system.@system[0].zonename`, owner from `opkg search` (napalm-device-types `PosixScheduledJobsMixin`) |
| `manage_scheduled_job(key, action, digest=)` | ✅ | enable, disable, run now (bounded by `timeout` where the router has it; another user's job through `start-stop-daemon -c`) |
| `put_scheduled_job(spec)` / `delete_scheduled_job(key, digest=)` | ✅ | an application's own job: two marked lines in the user's crontab; `@daily` and the other aliases as five fields, `@reboot` refused (BusyBox crond has no special times) |
| `get_ntp_servers` / `get_ntp_peers` | ✅ | `system.ntp.server` in UCI, every server of the list; none while `system.ntp.enabled` is off -- the same list as `get_time_sync()` |
| `get_time_sync()` | ✅ | napalm-device-types `TimeSyncMixin`: the servers as above, the zone from `zonename` where the rule in `timezone` is that zone's (else the one zone with that rule, or none); `synchronized` is not readable (None) |
## Configuration management
@@ -114,6 +116,22 @@ to the interfaces given, enables it at boot and restarts it. A VLAN device such
`br-ap.10` is written as the device under it (`br-ap`): lldpd sends on the L2 device.
Which interfaces is the caller's choice; at least one is required.
## Time sync
`configure_time_sync(ntp_servers=, timezone=)` (napalm-device-types `TimeSyncMixin`)
writes both values into UCI's `system` config and applies them; a value the router
already has is not written again, so nothing restarts.
* The servers replace the `system.ntp.server` list; the client is enabled, the servers
of a DHCP lease are turned off (`use_dhcp=0`) so the router has exactly these, and
`sysntpd` restarts.
* The zone goes into `zonename` (as LuCI keeps it, with spaces for underscores) and its
POSIX rule into `timezone`, the value libc reads -- an IANA name there leaves the
router on UTC (NetOrk/netork#1849). `/etc/init.d/system reload` applies it, and logd
restarts, as it reads the zone when it starts.
Writes run as root: OpenWrt has no sudo, so another login is refused before anything runs.
## Development
```bash
+2
View File
@@ -50,6 +50,7 @@ from napalm_openwrt.packages_mixin import OpenWrtPackageMixin
from napalm_openwrt.routing_mixin import OpenWrtRoutingMixin
from napalm_openwrt.scheduled_jobs_mixin import OpenWrtScheduledJobsMixin
from napalm_openwrt.system_mixin import _RC_MARKER, OpenWrtSystemMixin, _split_status
from napalm_openwrt.time_sync_mixin import OpenWrtTimeSyncMixin
from napalm_openwrt.vlan_mixin import OpenWrtVLANMixin
from napalm_openwrt.wireless_mixin import OpenWrtWirelessMixin
@@ -76,6 +77,7 @@ class OpenWrtDriver(
OpenWrtWirelessMixin,
OpenWrtLLDPMixin,
OpenWrtConfigMixin,
OpenWrtTimeSyncMixin,
OpenWrtSystemMixin,
OpenWrtPackageMixin,
OpenWrtRoutingMixin,
+1 -30
View File
@@ -532,38 +532,9 @@ class OpenWrtSystemMixin:
return {"success": False, "output": output, "error": error}
# ------------------------------------------------------------------
# NTP
# NTP statistics (the servers: time_sync_mixin)
# ------------------------------------------------------------------
def get_ntp_servers(self) -> dict[str, Any]:
"""Return configured NTP servers from ``uci show system``.
UCI example::
system.ntp.server='0.openwrt.pool.ntp.org 1.openwrt.pool.ntp.org'
"""
uci_out = self._send_command("uci show system")
servers: dict[str, Any] = {}
for line in uci_out.splitlines():
# Handles both list and single-value UCI representations
m = re.match(r"system\.ntp\.server(?:\[\d+\])?='([^']*)'", line.strip())
if m:
for srv in m.group(1).split():
srv = srv.strip()
if srv:
servers[srv] = {}
return servers
def get_ntp_peers(self) -> dict[str, Any]:
"""Return NTP peers from ``uci show system``.
OpenWrt's busybox ntpd does not differentiate peers from servers;
the same UCI ``ntp.server`` list is returned.
"""
return self.get_ntp_servers()
def get_ntp_stats(self) -> list[dict[str, Any]]:
"""Return NTP synchronisation statistics.
+302
View File
@@ -0,0 +1,302 @@
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Time sync on OpenWrt: UCI's ``system`` config (napalm-device-types ``TimeSyncMixin``).
OpenWrt keeps both values in ``/etc/config/system`` (NetOrk/netork#2364):
* **The servers** are the ``system.ntp.server`` list, which ``/etc/init.d/sysntpd``
hands to BusyBox ntpd while ``system.ntp.enabled`` is on. A disabled client has no
servers: the list names nothing the clock takes time from. sysntpd also adds the
servers of a DHCP lease unless ``use_dhcp`` is ``0``; a write turns that off, so the
router ends up with exactly the servers given.
* **The zone** is kept twice: ``zonename`` (the IANA name, as LuCI writes it -- with
spaces where the IANA name has underscores) and ``timezone``, the POSIX rule
``/etc/init.d/system`` writes to ``/tmp/TZ`` for libc. The rule is what the clock
runs on: an IANA name written there left an AP on UTC (NetOrk/netork#1849). So the
name is read as the zone only where the rule in force is that zone's; a rule
without a matching name is read as the one zone that has it, or as no zone where
several do (``CET-1CEST,...`` is Berlin, Paris, Madrid, ...).
Reading is one ``uci -q show system`` as the login user. Every write compares
first and sends nothing when the router already has the values -- an application
aligns on every poll -- else sets the options, commits ``system`` and applies them:
``/etc/init.d/sysntpd restart`` for the servers, ``/etc/init.d/system reload`` and a
restart of logd, which reads the zone when it starts, for the zone. Writes run as
root (``run_command(privileged=True)``); OpenWrt has no sudo.
``synchronized`` is None: BusyBox ntpd keeps no state another process can read, and
``ubus call system info`` says nothing about the clock's source.
"""
from __future__ import annotations
import re
import shlex
from collections import defaultdict
from dataclasses import dataclass, field
from functools import lru_cache
from importlib.resources import files
from typing import TYPE_CHECKING, Any, ClassVar
from napalm_device_types import FixStepOutcomeDict
from napalm_device_types.posix_tz import is_iana_zone, parse_posix_tz, posix_tz
from napalm_device_types.time_sync import TIME_SYNC_VALUES, TimeSyncDict, TimeSyncMixin
if TYPE_CHECKING:
from napalm_device_types import CommandResult
READ_COMMAND = "uci -q show system"
#: The rule ``/etc/init.d/system`` uses where the section names none.
DEFAULT_RULE = "UTC"
#: A zone of the database that stands for "not known", not for a place.
_NO_PLACE = frozenset({"Factory"})
#: ``system.<section>.<option>='value' ['value' ...]`` of the two sections that count.
_OPTION = re.compile(r"^system\.(?P<section>@system\[0\]|ntp)\.(?P<option>\w+)=(?P<value>.*)$")
_FALSE = frozenset({"0", "no", "off", "false", "disabled"})
@dataclass
class SystemUci:
"""What ``uci -q show system`` says about the clock."""
has_system: bool = False
has_ntp: bool = False
system: dict[str, list[str]] = field(default_factory=dict)
ntp: dict[str, list[str]] = field(default_factory=dict)
def _one(self, options: dict[str, list[str]], name: str) -> str | None:
values = options.get(name)
return values[0] if values else None
@property
def configured_servers(self) -> list[str]:
"""The list as it stands; an option of servers apart by spaces is split, as sysntpd does."""
return [s for value in self.ntp.get("server", []) for s in value.split()]
@property
def ntp_enabled(self) -> bool:
return (self._one(self.ntp, "enabled") or "1").lower() not in _FALSE
@property
def dhcp_servers(self) -> bool:
return (self._one(self.ntp, "use_dhcp") or "1").lower() not in _FALSE
@property
def servers(self) -> list[str]:
"""The servers the clock takes time from: none while the client is off."""
return self.configured_servers if self.has_ntp and self.ntp_enabled else []
@property
def zonename(self) -> str | None:
"""``zonename`` as an IANA name: LuCI's spaces back to underscores."""
name = self._one(self.system, "zonename")
return name.strip().replace(" ", "_") if name and name.strip() else None
@property
def rule(self) -> str:
return (self._one(self.system, "timezone") or "").strip() or DEFAULT_RULE
@property
def zone(self) -> str | None:
"""The zone the clock runs in, by name; None where no single zone is it."""
if not self.has_system:
return None
name = self.zonename
named = posix_tz(name) if name and is_iana_zone(name) else None
if name and named and same_time(self.rule, named):
return name
return zone_for_rule(self.rule)
def parse_system_uci(output: str) -> SystemUci:
"""``uci show system`` in parts: the first system section and the ``ntp`` one."""
parsed = SystemUci()
for line in output.splitlines():
line = line.strip()
if line.startswith("system.@system[0]="):
parsed.has_system = True
elif line.startswith("system.ntp="):
parsed.has_ntp = True
match = _OPTION.match(line)
if match is None:
continue
try:
values = shlex.split(match["value"])
except ValueError:
continue
options = parsed.system if match["section"] == "@system[0]" else parsed.ntp
options[match["option"]] = values
return parsed
def _time_of(rule: str) -> tuple[Any, ...] | None:
"""The offsets and transitions of *rule*, without the names it gives them."""
parts = parse_posix_tz(rule)
if parts is None:
return None
return (
parts["utc_offset"],
parts["dst_offset"],
tuple(sorted((parts["dst_start"] or {}).items())),
tuple(sorted((parts["dst_end"] or {}).items())),
)
def same_time(rule: str, other: str) -> bool:
"""Whether two rules keep the same time: ``GMT0`` is ``UTC0`` by another name."""
time = _time_of(rule)
return rule == other if time is None else time == _time_of(other)
@lru_cache(maxsize=1)
def _zones_by_rule() -> dict[str, tuple[str, ...]]:
"""Every zone of the database (not its links) by its rule, names and all."""
source = files("tzdata").joinpath("zoneinfo", "tzdata.zi").read_text(encoding="utf-8")
zones: defaultdict[str, list[str]] = defaultdict(list)
for line in source.splitlines():
if not line.startswith("Z "):
continue
zone = line.split()[1]
rule = posix_tz(zone)
if rule is not None and zone not in _NO_PLACE:
zones[_rule_key(rule)].append(zone)
return {rule: tuple(names) for rule, names in zones.items()}
def _rule_key(rule: str) -> str:
parts = parse_posix_tz(rule)
return rule if parts is None else repr(sorted(parts.items()))
def zone_for_rule(rule: str) -> str | None:
"""The one zone whose rule *rule* is; None where none or several are.
Several zones share most rules (``CET-1CEST,M3.5.0,M10.5.0/3`` is Berlin, Paris,
Madrid, ...): which of them a router means is not the driver's to guess. Links
(``Asia/Calcutta``) count as the zone they point at.
"""
if not rule:
return None
zones = _zones_by_rule().get(_rule_key(rule), ())
return zones[0] if len(zones) == 1 else None
def _luci_name(zone: str) -> str:
"""*zone* as LuCI keeps it in ``zonename``, so its zone list shows it chosen."""
return zone.replace("_", " ")
def _uci_command(*words: str) -> str:
return shlex.join(words)
class OpenWrtTimeSyncMixin(TimeSyncMixin):
"""The servers and the zone in UCI's ``system`` config; see the module."""
time_sync_writes: ClassVar[frozenset[str]] = TIME_SYNC_VALUES
if TYPE_CHECKING: # pragma: no cover - the driver's
def run_command(
self,
command: str,
*,
privileged: bool = False,
timeout: float = 60,
stdin: bytes | None = None,
) -> CommandResult: ...
# -- reading ---------------------------------------------------------------------------------
def _ts_read(self) -> SystemUci:
result = self.run_command(READ_COMMAND, timeout=30)
if result.exit_code != 0:
said = result.stderr.strip() or result.stdout.strip() or f"exit {result.exit_code}"
raise RuntimeError(f"{READ_COMMAND}: {said}")
return parse_system_uci(result.stdout)
def get_time_sync(self) -> TimeSyncDict:
"""The router's time servers and zone, from one ``uci -q show system``.
:raises RuntimeError: when uci could not be read.
"""
reading = self._ts_read()
return {
"ntp_servers": reading.servers,
"timezone": reading.zone,
"synchronized": None,
"daemon": None,
}
def get_ntp_servers(self) -> dict[str, dict[str, Any]]:
"""The servers of :meth:`get_time_sync`, as NAPALM's ``{server: {}}``."""
return {server: {} for server in self._ts_read().servers}
def get_ntp_peers(self) -> dict[str, dict[str, Any]]:
"""BusyBox ntpd has no peers apart from its servers: the same list."""
return self.get_ntp_servers()
# -- writing ---------------------------------------------------------------------------------
def _ts_apply(self, commands: list[str], done: str) -> FixStepOutcomeDict:
result = self.run_command(" && ".join(commands), privileged=True, timeout=60)
if result.exit_code != 0:
said = result.stderr.strip() or result.stdout.strip() or f"exit {result.exit_code}"
return {"ok": False, "output": said[-300:]}
return {"ok": True, "output": done}
def _write_ntp_servers(self, servers: list[str]) -> FixStepOutcomeDict:
now = self._ts_read()
if [s.lower() for s in now.servers] == [
s.lower() for s in servers
] and not now.dhcp_servers:
return {"ok": True, "output": "the router already has these servers"}
commands = []
if not now.has_ntp:
commands.append(_uci_command("uci", "set", "system.ntp=timeserver"))
if "server" in now.ntp:
commands.append(_uci_command("uci", "delete", "system.ntp.server"))
commands += [_uci_command("uci", "add_list", f"system.ntp.server={s}") for s in servers]
commands += [
"uci set system.ntp.enabled=1",
"uci set system.ntp.use_dhcp=0",
"uci commit system",
"/etc/init.d/sysntpd enable",
"/etc/init.d/sysntpd restart",
]
return self._ts_apply(commands, f"ntpd takes time from {', '.join(servers)}")
def _write_time_zone(self, zone: str) -> FixStepOutcomeDict:
rule = posix_tz(zone)
if rule is None: # the template lets only zones of the database through
return {"ok": False, "output": f"no POSIX rule for {zone}"}
now = self._ts_read()
if now.has_system and now.zonename == zone and same_time(now.rule, rule):
return {"ok": True, "output": f"the router is already in {zone}"}
commands = [
_uci_command("uci", "set", f"system.@system[0].zonename={_luci_name(zone)}"),
_uci_command("uci", "set", f"system.@system[0].timezone={rule}"),
"uci commit system",
"/etc/init.d/system reload",
"/etc/init.d/log restart",
]
return self._ts_apply(commands, f"time zone set to {zone} ({rule})")
__all__ = [
"OpenWrtTimeSyncMixin",
"SystemUci",
"parse_system_uci",
"same_time",
"zone_for_rule",
]
+1 -1
View File
@@ -21,7 +21,7 @@ classifiers = [
]
dependencies = [
"napalm>=5.1", # older releases import pkg_resources, which a 3.12 venv lacks
"napalm_device_types>=4.27.0",
"napalm_device_types>=4.35.0", # TimeSyncMixin, posix_tz
"netmiko>=4.0.0",
"paramiko>=5.0.0", # CVE-2026-44405
"netaddr>=0.7.19", # IPAddress; below it the package has none (CI lowest job)
+10 -4
View File
@@ -3,7 +3,7 @@
from unittest.mock import MagicMock, patch
import pytest
from napalm_device_types import LLDPCTL_KEYVALUE_COMMAND
from napalm_device_types import LLDPCTL_KEYVALUE_COMMAND, CommandResult
from napalm_openwrt.openwrt import OpenWrtDriver
@@ -949,20 +949,26 @@ class TestGetUsers:
class TestGetNtpServers:
"""Read with get_time_sync's reading (test_time_sync.py), over an exec channel."""
@staticmethod
def _uci(output):
return lambda cmd, **kw: CommandResult(output, "", 0)
def test_returns_dict(self, driver):
driver._send_command = lambda cmd, **kw: UCI_SYSTEM_NTP
driver.run_command = self._uci(UCI_SYSTEM_NTP)
result = driver.get_ntp_servers()
assert isinstance(result, dict)
def test_servers_present(self, driver):
driver._send_command = lambda cmd, **kw: UCI_SYSTEM_NTP
driver.run_command = self._uci(UCI_SYSTEM_NTP)
result = driver.get_ntp_servers()
assert "0.openwrt.pool.ntp.org" in result
assert "1.openwrt.pool.ntp.org" in result
assert "2.openwrt.pool.ntp.org" in result
def test_empty_when_no_ntp(self, driver):
driver._send_command = lambda cmd, **kw: ""
driver.run_command = self._uci("")
assert driver.get_ntp_servers() == {}
+515
View File
@@ -0,0 +1,515 @@
"""Time sync on OpenWrt (napalm-device-types ``TimeSyncMixin``, NetOrk/netork#2364).
OpenWrt keeps both values in UCI's ``system`` config: the servers in the
``system.ntp.server`` list, which sysntpd hands to BusyBox ntpd, and the zone twice --
``zonename`` (the IANA name, as LuCI writes it: with spaces for underscores) and
``timezone``, the POSIX rule libc reads as ``TZ``. The rule is the one that counts
(netOrk#1849: an IANA name in ``timezone`` left the AP on UTC).
The device is a fake ``uci`` behind ``run_command``: it renders ``uci -q show system``
the way uci prints it, and applies the ``uci set``/``delete``/``add_list`` lines a
write sends, so the template's ``verify`` step reads back what was written.
"""
from __future__ import annotations
import shlex
from typing import Any
from unittest.mock import MagicMock, patch
import pytest
from napalm_device_types import CommandResult
from napalm_device_types.posix_tz import UnknownTimezone, posix_tz
from napalm_device_types.time_sync import TIME_SYNC_VALUES
from napalm_openwrt.openwrt import OpenWrtDriver
from napalm_openwrt.time_sync_mixin import parse_system_uci, zone_for_rule
# ``uci show system`` of OpenWrt 23.05 out of the box: zonename 'UTC', the rule GMT0,
# the four pool servers as a list.
STOCK = """\
system.@system[0]=system
system.@system[0].hostname='OpenWrt'
system.@system[0].timezone='GMT0'
system.@system[0].zonename='UTC'
system.@system[0].ttylogin='0'
system.@system[0].log_size='128'
system.@system[0].urandom_seed='0'
system.ntp=timeserver
system.ntp.enabled='1'
system.ntp.enable_server='0'
system.ntp.server='0.openwrt.pool.ntp.org' '1.openwrt.pool.ntp.org' '2.openwrt.pool.ntp.org' '3.openwrt.pool.ntp.org'
"""
# An AP configured through LuCI (the get_system_config fixture of netOrk#164).
LUCI_BERLIN = """\
system.@system[0]=system
system.@system[0].hostname='ap-eze-Garten'
system.@system[0].timezone='CET-1CEST,M3.5.0,M10.5.0/3'
system.@system[0].zonename='Europe/Berlin'
system.@system[0].log_remote='1'
system.@system[0].log_ip='10.10.40.2'
system.ntp=timeserver
system.ntp.server='0.openwrt.pool.ntp.org' '1.openwrt.pool.ntp.org'
"""
# LuCI's zone names have spaces where the IANA names have underscores.
LUCI_NEW_YORK = """\
system.@system[0]=system
system.@system[0].timezone='EST5EDT,M3.2.0,M11.1.0'
system.@system[0].zonename='America/New York'
system.ntp=timeserver
system.ntp.server='10.0.0.1'
"""
# netOrk#1849: the IANA name written as the rule. libc cannot read it; the AP runs on UTC.
NAME_AS_RULE = """\
system.@system[0]=system
system.@system[0].timezone='Europe/Berlin'
system.@system[0].zonename='Europe/Berlin'
system.ntp=timeserver
system.ntp.server='10.0.0.1'
"""
# A server list kept as one option, the servers apart by spaces: sysntpd splits it.
ONE_OPTION = """\
system.@system[0]=system
system.@system[0].timezone='UTC'
system.ntp=timeserver
system.ntp.server='0.openwrt.pool.ntp.org 1.openwrt.pool.ntp.org'
system.ntp.enabled='1'
"""
def _render(sections: list[tuple[str, str, dict[str, list[str] | str]]]) -> str:
"""*sections* as ``uci show system`` prints them."""
lines = []
for name, kind, options in sections:
lines.append(f"system.{name}={kind}")
for option, value in options.items():
values = value if isinstance(value, list) else [value]
lines.append(f"system.{name}.{option}=" + " ".join(_quoted(v) for v in values))
return "\n".join(lines) + "\n"
def _quoted(value: str) -> str:
"""*value* in single quotes, a quote in it as ``'\\''``: how uci prints every value."""
return "'" + value.replace("'", "'\\''") + "'"
def _parse(output: str) -> list[tuple[str, str, dict[str, list[str] | str]]]:
"""``uci show system`` as the fake's state (a list is a list, an option a string)."""
sections: list[tuple[str, str, dict[str, list[str] | str]]] = []
for line in output.splitlines():
key, _, raw = line.partition("=")
parts = key.split(".")
if len(parts) == 2:
sections.append((parts[1], raw, {}))
continue
values = shlex.split(raw)
option: list[str] | str = values if raw.count("'") > 2 else values[0]
next(s for s in sections if s[0] == parts[1])[2][parts[2]] = option
return sections
class _Uci:
"""A router's ``system`` config behind ``run_command``; keeps every command it ran."""
def __init__(self, show: str = STOCK, fail: str = "") -> None:
self.sections = _parse(show)
self.fail = fail
self.ran: list[tuple[str, bool]] = []
def writes(self) -> list[str]:
return [c for c, _ in self.ran if c != "uci -q show system"]
def __call__(
self,
command: str,
*,
privileged: bool = False,
timeout: float = 60,
stdin: bytes | None = None,
) -> CommandResult:
self.ran.append((command, privileged))
if command == "uci -q show system":
return CommandResult(_render(self.sections), "", 0)
for part in command.split(" && "):
if self.fail and self.fail in part:
return CommandResult("", f"{self.fail}: failed", 1)
words = shlex.split(part)
if words[0] == "uci":
self._uci(words[1:])
return CommandResult("", "", 0)
def _section(self, name: str) -> dict[str, list[str] | str]:
return next(s for s in self.sections if s[0] == name)[2]
def _uci(self, args: list[str]) -> None:
verb, rest = args[0], args[1:]
if verb == "commit":
return
key, _, value = rest[0].partition("=")
_, section, *option = key.split(".")
if verb == "set" and not option:
self.sections.append((section, value, {}))
elif verb == "set":
self._section(section)[option[0]] = value
elif verb == "add_list":
options = self._section(section)
kept = options.get(option[0], [])
options[option[0]] = [*([kept] if isinstance(kept, str) else kept), value]
elif verb == "delete":
del self._section(section)[option[0]]
else: # pragma: no cover - a command the driver does not send
raise AssertionError(args)
def _driver(uci: _Uci, username: str = "root") -> OpenWrtDriver:
with patch("napalm_openwrt.openwrt.ConnectHandler"):
drv = OpenWrtDriver(hostname="192.0.2.15", username=username, password="")
drv.device = MagicMock()
drv.run_command = uci # type: ignore[method-assign]
return drv
def _read(show: str) -> dict[str, Any]:
return dict(_driver(_Uci(show)).get_time_sync())
# -- the driver takes part ----------------------------------------------------------------------
def test_the_driver_reads_and_writes_both_values():
drv = _driver(_Uci())
assert callable(getattr(drv, "get_time_sync", None))
assert callable(getattr(drv, "configure_time_sync", None))
assert drv.time_sync_writes == TIME_SYNC_VALUES
# -- reading ------------------------------------------------------------------------------------
def test_a_stock_router_reads_its_pool_servers_and_utc():
# zonename 'UTC' with the rule GMT0: the same time, so the name stands.
assert _read(STOCK) == {
"ntp_servers": [
"0.openwrt.pool.ntp.org",
"1.openwrt.pool.ntp.org",
"2.openwrt.pool.ntp.org",
"3.openwrt.pool.ntp.org",
],
"timezone": "UTC",
"synchronized": None,
"daemon": None,
}
def test_the_read_is_one_uci_show_as_the_login_user():
uci = _Uci()
_driver(uci).get_time_sync()
assert uci.ran == [("uci -q show system", False)]
def test_a_zone_set_through_luci_reads_by_its_name():
reading = _read(LUCI_BERLIN)
assert reading["timezone"] == "Europe/Berlin"
assert reading["ntp_servers"] == ["0.openwrt.pool.ntp.org", "1.openwrt.pool.ntp.org"]
def test_luci_spaces_read_as_the_iana_underscores():
assert _read(LUCI_NEW_YORK)["timezone"] == "America/New_York"
def test_a_name_whose_rule_is_not_in_force_is_not_read_as_the_zone():
# netOrk#1849: the AP runs on UTC; reading Europe/Berlin would hide that.
assert _read(NAME_AS_RULE)["timezone"] is None
def test_a_rule_without_a_name_reads_as_the_one_zone_that_has_it():
show = "system.@system[0]=system\nsystem.@system[0].timezone='IST-5:30'\n"
assert _read(show)["timezone"] == "Asia/Kolkata"
def test_a_rule_many_zones_share_reads_as_no_zone():
# Berlin, Paris, Madrid, ... all have this rule: which one is not the driver's to guess.
show = "system.@system[0]=system\nsystem.@system[0].timezone='CET-1CEST,M3.5.0,M10.5.0/3'\n"
assert _read(show)["timezone"] is None
def test_a_section_without_a_rule_runs_on_utc():
# /etc/init.d/system defaults the rule to UTC.
assert _read("system.@system[0]=system\n")["timezone"] == "Etc/UTC"
def test_no_system_section_reads_no_zone():
assert _read("")["timezone"] is None
@pytest.mark.parametrize(
("rule", "zone"),
[
("UTC", "Etc/UTC"),
("UTC0", "Etc/UTC"),
("<+0545>-5:45", "Asia/Kathmandu"),
("NZST-12NZDT,M9.5.0,M4.1.0/3", "Pacific/Auckland"),
("GMT0", None), # Abidjan, Monrovia, Etc/GMT, ...
("<-00>0", None), # Factory: the zone is not known
("Europe/Berlin", None),
("", None),
],
)
def test_zone_for_rule(rule, zone):
assert zone_for_rule(rule) == zone
def test_a_server_list_kept_as_one_option_is_split_as_sysntpd_does():
assert _read(ONE_OPTION)["ntp_servers"] == [
"0.openwrt.pool.ntp.org",
"1.openwrt.pool.ntp.org",
]
def test_a_disabled_client_has_no_servers():
# sysntpd starts no ntpd: the list names sources the clock does not take time from.
show = STOCK.replace("system.ntp.enabled='1'", "system.ntp.enabled='0'")
assert _read(show)["ntp_servers"] == []
def test_no_ntp_section_has_no_servers():
show = "system.@system[0]=system\nsystem.@system[0].timezone='UTC'\n"
assert _read(show)["ntp_servers"] == []
def test_a_line_uci_would_not_print_is_passed_over():
reading = parse_system_uci(LUCI_BERLIN + "system.@system[0].zonename='Europe/Paris\n")
assert reading.zone == "Europe/Berlin"
def test_a_failed_read_raises():
drv = _driver(_Uci())
drv.run_command = lambda *a, **k: CommandResult("", "uci: Entry not found", 1) # type: ignore[method-assign]
with pytest.raises(RuntimeError, match="Entry not found"):
drv.get_time_sync()
# -- get_ntp_servers agrees ---------------------------------------------------------------------
@pytest.mark.parametrize("show", [STOCK, LUCI_BERLIN, ONE_OPTION, NAME_AS_RULE])
def test_get_ntp_servers_names_the_same_servers(show):
drv = _driver(_Uci(show))
assert list(drv.get_ntp_servers()) == drv.get_time_sync()["ntp_servers"]
def test_get_ntp_servers_reads_every_server_of_a_list():
# It used to keep only the first of 'a' 'b' 'c'.
assert len(_driver(_Uci(STOCK)).get_ntp_servers()) == 4
def test_the_peers_are_the_servers():
drv = _driver(_Uci(STOCK))
assert drv.get_ntp_peers() == drv.get_ntp_servers()
def test_get_ntp_servers_of_a_disabled_client_is_empty():
show = STOCK.replace("system.ntp.enabled='1'", "system.ntp.enabled='0'")
assert _driver(_Uci(show)).get_ntp_servers() == {}
# -- writing the servers ------------------------------------------------------------------------
def test_the_servers_replace_the_list_and_ntpd_restarts():
uci = _Uci(STOCK)
result = _driver(uci).configure_time_sync(ntp_servers=["10.0.0.1", "ntp.example.org"])
assert result["success"] is True, result["output"]
assert [s["step"] for s in result["steps"]] == ["ntp_servers", "verify"]
assert uci._section("ntp")["server"] == ["10.0.0.1", "ntp.example.org"]
(write,) = uci.writes()
assert write.endswith(
"uci commit system && /etc/init.d/sysntpd enable && /etc/init.d/sysntpd restart"
)
assert all(privileged for c, privileged in uci.ran if c in uci.writes())
def test_writing_servers_turns_off_the_ones_dhcp_brings():
# sysntpd adds the servers of a DHCP lease to the list unless use_dhcp is 0.
uci = _Uci(STOCK)
_driver(uci).configure_time_sync(ntp_servers=["10.0.0.1"])
assert uci._section("ntp")["use_dhcp"] == "0"
def test_writing_servers_enables_a_disabled_client():
uci = _Uci(STOCK.replace("system.ntp.enabled='1'", "system.ntp.enabled='0'"))
result = _driver(uci).configure_time_sync(ntp_servers=["10.0.0.1"])
assert result["success"] is True, result["output"]
assert uci._section("ntp")["enabled"] == "1"
assert "/etc/init.d/sysntpd enable" in uci.writes()[0]
def test_a_missing_ntp_section_is_made():
uci = _Uci("system.@system[0]=system\nsystem.@system[0].timezone='UTC'\n")
result = _driver(uci).configure_time_sync(ntp_servers=["10.0.0.1"])
assert result["success"] is True, result["output"]
assert ("ntp", "timeserver") in [(s[0], s[1]) for s in uci.sections]
assert "uci delete system.ntp.server" not in uci.writes()[0]
def test_the_same_servers_again_write_nothing():
# netOrk aligns on every poll: an aligned router must not restart ntpd each time.
uci = _Uci(STOCK)
drv = _driver(uci)
drv.configure_time_sync(ntp_servers=["10.0.0.1", "10.0.0.2"])
uci.ran.clear()
result = drv.configure_time_sync(ntp_servers=["10.0.0.1", "10.0.0.2"])
assert result["success"] is True
assert uci.writes() == []
assert "already" in result["steps"][0]["output"]
def test_the_same_servers_in_another_order_are_written():
uci = _Uci(LUCI_BERLIN)
_driver(uci).configure_time_sync(
ntp_servers=["1.openwrt.pool.ntp.org", "0.openwrt.pool.ntp.org"]
)
assert uci._section("ntp")["server"] == ["1.openwrt.pool.ntp.org", "0.openwrt.pool.ntp.org"]
def test_a_refused_uci_write_restarts_nothing():
uci = _Uci(STOCK, fail="uci commit system")
result = _driver(uci).configure_time_sync(ntp_servers=["10.0.0.1"])
assert result["success"] is False
assert result["steps"][-1]["step"] == "ntp_servers"
assert "failed" in result["output"]
def test_a_login_other_than_root_writes_nothing():
uci = _Uci(STOCK)
drv = _driver(uci, username="admin")
drv.run_command = lambda c, **k: ( # type: ignore[method-assign]
drv._check_privilege(k.get("privileged", False)) or uci(c, **k)
)
result = drv.configure_time_sync(ntp_servers=["10.0.0.1"])
assert result["success"] is False
assert "no sudo" in result["output"]
assert uci.writes() == []
# -- writing the zone ---------------------------------------------------------------------------
def test_the_zone_is_written_as_name_and_rule():
uci = _Uci(STOCK)
result = _driver(uci).configure_time_sync(timezone="Europe/Berlin")
assert result["success"] is True, result["output"]
assert [s["step"] for s in result["steps"]] == ["timezone", "verify"]
system = uci._section("@system[0]")
assert system["zonename"] == "Europe/Berlin"
assert system["timezone"] == "CET-1CEST,M3.5.0,M10.5.0/3"
def test_the_zone_applies_to_the_system_and_to_logd():
# /etc/init.d/system reload writes /tmp/TZ; logd reads the zone when it starts.
uci = _Uci(STOCK)
_driver(uci).configure_time_sync(timezone="Europe/Berlin")
(write,) = uci.writes()
assert write.endswith(
"uci commit system && /etc/init.d/system reload && /etc/init.d/log restart"
)
assert "sysntpd" not in write
def test_a_zone_name_is_written_as_luci_does():
uci = _Uci(STOCK)
result = _driver(uci).configure_time_sync(timezone="America/New_York")
assert result["success"] is True, result["output"]
assert uci._section("@system[0]")["zonename"] == "America/New York"
assert uci._section("@system[0]")["timezone"] == posix_tz("America/New_York")
def test_a_rule_with_quoted_names_is_one_shell_word():
uci = _Uci(STOCK)
_driver(uci).configure_time_sync(timezone="Asia/Kathmandu")
assert uci._section("@system[0]")["timezone"] == "<+0545>-5:45"
def test_the_name_as_rule_of_1849_is_repaired():
uci = _Uci(NAME_AS_RULE)
result = _driver(uci).configure_time_sync(timezone="Europe/Berlin")
assert result["success"] is True, result["output"]
assert uci._section("@system[0]")["timezone"] == "CET-1CEST,M3.5.0,M10.5.0/3"
@pytest.mark.parametrize(
("show", "zone"),
[(LUCI_BERLIN, "Europe/Berlin"), (LUCI_NEW_YORK, "America/New_York"), (STOCK, "UTC")],
)
def test_the_zone_it_has_writes_nothing(show, zone):
# The stock GMT0 is UTC's time under another name: no rewrite on every poll.
uci = _Uci(show)
result = _driver(uci).configure_time_sync(timezone=zone)
assert result["success"] is True, result["output"]
assert uci.writes() == []
def test_a_zone_twice_writes_once():
uci = _Uci(STOCK)
drv = _driver(uci)
drv.configure_time_sync(timezone="Pacific/Auckland")
drv.configure_time_sync(timezone="Pacific/Auckland")
assert len(uci.writes()) == 1
def test_both_values_in_one_run():
uci = _Uci(STOCK)
result = _driver(uci).configure_time_sync(ntp_servers=["10.0.0.1"], timezone="Europe/Berlin")
assert result["success"] is True, result["output"]
assert [s["step"] for s in result["steps"]] == ["ntp_servers", "timezone", "verify"]
def test_a_zone_without_a_rule_is_not_written():
# The template lets only zones of the database through; the step does not rely on it.
uci = _Uci(STOCK)
outcome = _driver(uci)._write_time_zone("Mars/Olympus_Mons")
assert outcome["ok"] is False
assert uci.ran == []
def test_a_posix_rule_as_zone_is_refused_before_anything_runs():
uci = _Uci(STOCK)
with pytest.raises(UnknownTimezone):
_driver(uci).configure_time_sync(timezone="CET-1CEST,M3.5.0,M10.5.0/3")
assert uci.ran == []