Compare commits

...
4 Commits
Author SHA1 Message Date
christianmanivong 6c7f164004 Merge pull request 'feat(time-sync): TimeSyncMixin, PosixTimeSyncMixin and the posix_tz helpers' (#103) from feature/time-sync-2361 into main
driver / types (push) Successful in 59s
driver / standard (push) Successful in 16s
driver / lint (push) Successful in 14s
driver / test (3.12) (push) Successful in 1m12s
driver / test (3.13) (push) Successful in 1m7s
driver / lowest (push) Successful in 38s
driver / build (push) Successful in 26s
driver / security (push) Successful in 54s
driver / publish (push) Successful in 27s
CI / driver (push) Successful in 3m3s
2026-11-11 14:05:02 +00:00
christianmanivong 073087da69 feat(time-sync): TimeSyncMixin, PosixTimeSyncMixin and the posix_tz helpers
driver / standard (pull_request) Successful in 19s
driver / lint (pull_request) Successful in 19s
driver / types (pull_request) Successful in 57s
driver / test (3.13) (pull_request) Successful in 1m4s
driver / test (3.12) (pull_request) Successful in 1m14s
driver / lowest (pull_request) Successful in 38s
driver / build (pull_request) Successful in 26s
driver / security (pull_request) Successful in 1m0s
CI / driver (pull_request) Successful in 2m23s
driver / publish (pull_request) Skipped
netOrk gets one list of NTP servers and a time zone per site and aligns
every device that differs (NetOrk/netork#2360). The contract comes first,
so the drivers can be built against it at the same time (#2361):

TimeSyncMixin declares get_time_sync() -> TimeSyncDict (servers in the
device's order, the zone as an IANA name, synchronised, the client) and
carries configure_time_sync(ntp_servers=None, timezone=None) as a fix
template: None leaves a value alone, the device ends up with exactly the
servers given, and a verify step reads it back. time_sync_writes says
which of the two values a driver writes; anything else, an unknown zone,
a malformed server or an empty list is refused before anything is
written.

PosixTimeSyncMixin implements it over run_command for Linux-like hosts:
one reading as the login user (timedatectl, chrony's configuration and
chronyc, timedatectl show-timesync, ntpd and OpenNTPD), the zone through
timedatectl set-timezone, chrony's servers in a file of their own with
every other source commented out, systemd-timesyncd's in a drop-in that
resets NTP= and empties FallbackNTP=. ntpd and OpenNTPD are read only.

posix_tz moves here from netOrk, so OpenWrt can write the POSIX rule and
a switch the UTC offset and summer-time rule (parse_posix_tz). It reads
the tzdata package, now a dependency.

Release 4.35.0: the drivers that implement it need it on PyPI.
2026-11-11 14:30:36 +01:00
christianmanivong 278a707157 Merge pull request 'feat(running-backups): the backups running on a device right now' (#102) from feature/running-backups-2318 into main
driver / lint (push) Successful in 13s
driver / standard (push) Successful in 14s
driver / types (push) Successful in 59s
driver / test (3.13) (push) Successful in 58s
driver / test (3.12) (push) Successful in 1m13s
driver / lowest (push) Successful in 35s
driver / build (push) Successful in 26s
driver / security (push) Successful in 56s
driver / publish (push) Successful in 26s
CI / driver (push) Successful in 2m36s
2026-11-11 07:22:54 +00:00
christianmanivong 56e5e82a59 feat(running-backups): the backups running on a device right now
driver / lint (pull_request) Successful in 17s
driver / standard (pull_request) Successful in 19s
driver / types (pull_request) Successful in 1m2s
driver / test (3.13) (pull_request) Successful in 1m5s
driver / test (3.12) (pull_request) Successful in 1m15s
driver / lowest (pull_request) Successful in 37s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 59s
CI / driver (pull_request) Successful in 2m24s
driver / publish (pull_request) Skipped
A restart aborts every backup that runs on the device it restarts, and a
guest's restart breaks the backup its hypervisor is taking of it. netOrk
asks right before it restarts a host after patching (NetOrk/netork#2318),
so the reading belongs in the contract first: RunningBackupsMixin declares
get_running_backups(), opt-in like VmStopRequestMixin, so hasattr tells a
caller whether the driver can tell at all.

Release 4.34.0: the drivers that implement it need it on PyPI.
2026-11-10 23:39:17 +01:00
14 changed files with 2173 additions and 2 deletions

No files matched your search

+37
View File
@@ -7,6 +7,43 @@ recorded here; their history is the git log.
## [Unreleased]
## [4.35.0] - 2026-11-11
### Added
- `TimeSyncMixin`: a device's time sources and time zone. `get_time_sync()` (declared only)
returns `TimeSyncDict` -- the configured NTP servers in the device's order, the zone as an
IANA name (None where the device keeps no name), whether the clock is synchronised now,
and the client (`chrony`, `systemd-timesyncd`, `ntpd`, `openntpd`; None for the device's
own). `configure_time_sync(ntp_servers=None, timezone=None)` is a fix template: None
leaves a value alone, the device ends up with exactly the servers given, in order, and a
`verify` step reads it back. An unknown zone, a malformed server, an empty list or a value
outside the driver's `time_sync_writes` is refused before anything is written.
`TIME_SYNC_VALUES` and `check_ntp_servers` are public (NetOrk/netork#2361).
- `PosixTimeSyncMixin` implements it over `run_command`: read in one round trip as the login
user (`timedatectl`, chrony's configuration and `chronyc -n sources`, `timedatectl
show-timesync`, ntpd's and OpenNTPD's configuration); the zone by `timedatectl
set-timezone`; chrony's servers in a file of their own (`sources.d`, else a `confdir` or
an included file) with every other source commented out, then `chronyc reload sources` or
a restart; systemd-timesyncd's in a drop-in that resets `NTP=` and empties `FallbackNTP=`.
ntpd and OpenNTPD are read, not written. `parse_time_sync` is public.
- `napalm_device_types.posix_tz` (from netOrk): `posix_tz`, `is_iana_zone`, `is_posix_tz` and
`UnknownTimezone`, and `parse_posix_tz`, which takes a POSIX rule apart into the UTC
offset and the summer-time transitions a switch wants (`PosixTzDict`,
`DstTransitionDict`).
### Changed
- Needs `tzdata` (2024.1 or later): the zones' rules come from its TZif files.
## [4.34.0] - 2026-11-10
### Added
- `RunningBackupsMixin.get_running_backups()`: the backups running on a device right now --
a hypervisor's backup of its guests (with the guests it is taking now), a backup server's
backup, sync, verify, garbage collection, prune or tape run, a host's own file-level backup.
Declared only; a driver mixes it in when it can tell, and a driver without it cannot tell.
`RunningBackupDict`, `RunningBackupKind` and `RUNNING_BACKUP_KINDS` are public. An
application asks right before it restarts a device (NetOrk/netork#2318).
## [4.33.0] - 2026-11-07
### Added
+24 -1
View File
@@ -124,7 +124,8 @@ application wants made on a device runs as fixed steps the driver implements, wi
the caller supplies: `SnmpAgentMixin.configure_snmp_agent(settings)` (install, configure,
firewall, start), `LldpAgentMixin.configure_lldp_agent(interfaces)` (install, write the
interfaces, enable and restart; the driver writes only the interfaces),
`EnsurePackageMixin.ensure_package(name)`, `PackageProxyMixin.configure_package_proxy(url)` and
`EnsurePackageMixin.ensure_package(name)`, `PackageProxyMixin.configure_package_proxy(url)`,
`TimeSyncMixin.configure_time_sync(ntp_servers, timezone)` and
`ContainerEngineMixin.grant_container_engine_access(user)`. A driver whose device takes the
change in one call overrides the template method. A driver mixes in the fixes its device
can take; none is on a role base. They replace `run_device_action`, which is deprecated.
@@ -345,6 +346,28 @@ application's job as a timer where systemd runs, else in `/etc/cron.d` or the us
crontab. A driver sets the paths its host keeps jobs in. `napalm_device_types.cron` parses
cron expressions, gives their next runs and writes them as `OnCalendar` lines.
`TimeSyncMixin` (`get_time_sync`, `configure_time_sync`) is how a device keeps its clock:
the NTP servers it is configured with, in its order, its time zone as an IANA name, whether
it is synchronised now and which client does it (`TimeSyncDict`). `get_time_sync` is
declared only; `configure_time_sync(ntp_servers=None, timezone=None)` is a fix template --
`None` leaves a value alone, the device ends up with exactly the servers given, in that
order, and a `verify` step reads it back. A zone that is not in the IANA database, a
malformed server, an empty list or a value outside the driver's `time_sync_writes` is
refused before anything is written. A driver states in `time_sync_writes` which of
`ntp_servers` and `timezone` it can write (a BMC that runs on UTC only: `ntp_servers`).
`napalm_device_types.posix_tz` turns an IANA name into the POSIX rule libc wants in `TZ`
(OpenWrt) and that rule into a UTC offset and summer-time transitions (a switch), from the
`tzdata` package. `PosixTimeSyncMixin` implements it over `run_command`: one reading as the
login user (`timedatectl show`, the active client: chrony's configuration and `chronyc -n
sources`, `timedatectl show-timesync`, `ntp.conf`, OpenNTPD's `ntpd.conf`); the zone by
`timedatectl set-timezone`; chrony's servers in a file of their own --
`/etc/chrony/sources.d/netork.sources` where chrony reads that directory, else a `confdir`
or an included `/etc/chrony.d/netork.conf` -- with every other `server`, `pool`, `peer` and
foreign `sourcedir` line commented out behind `#napalm-time-sync: `, then `chronyc reload
sources` or a restart; systemd-timesyncd's in `/etc/systemd/timesyncd.conf.d/netork.conf`
(`NTP=` reset, `FallbackNTP=` emptied), then a restart. ntpd and OpenNTPD are read, not
written.
### Access channels: why there is no container model here
`CommandChannelMixin` declares a driver's public channel to its host:
+42
View File
@@ -56,6 +56,7 @@ instead of being restated on every role that happens to need it:
* :class:`~napalm_device_types.nat_vpn.NatVpnMixin`
* :class:`~napalm_device_types.packages.PackageManagementMixin`
* :class:`~napalm_device_types.ping_sweep.PingSweepMixin`
* :class:`~napalm_device_types.running_backups.RunningBackupsMixin`
* :class:`~napalm_device_types.service_clusters.ServiceClustersMixin`
* :class:`~napalm_device_types.service_packages.ServicePackagesMixin`
* :class:`~napalm_device_types.ssh_server_auth.SshServerAuthMixin`
@@ -64,6 +65,8 @@ instead of being restated on every role that happens to need it:
* :class:`~napalm_device_types.scheduled_jobs_posix.PosixScheduledJobsMixin`
* :class:`~napalm_device_types.services.ServiceControlMixin`
* :class:`~napalm_device_types.systemd.SystemdServicesMixin`
* :class:`~napalm_device_types.time_sync.TimeSyncMixin`
* :class:`~napalm_device_types.time_sync_posix.PosixTimeSyncMixin`
* :class:`~napalm_device_types.updates.UpdateMixin`
* :class:`~napalm_device_types.virtual_ips.VirtualIpsMixin`
* :class:`~napalm_device_types.vm_stop_request.VmStopRequestMixin`
@@ -221,9 +224,24 @@ from napalm_device_types.package_updates import (
from napalm_device_types.packages import PackageManagementMixin
from napalm_device_types.phone import PhoneDriver
from napalm_device_types.ping_sweep import PingSweepMixin, driver_supports_ping
from napalm_device_types.posix_tz import (
DstTransitionDict,
PosixTzDict,
UnknownTimezone,
is_iana_zone,
is_posix_tz,
parse_posix_tz,
posix_tz,
)
from napalm_device_types.provisioning import VMProvisionIncomplete
from napalm_device_types.residential_gateway import ResidentialGatewayDriver
from napalm_device_types.roles import primary_role_of, role_keys_of, roles_of
from napalm_device_types.running_backups import (
RUNNING_BACKUP_KINDS,
RunningBackupDict,
RunningBackupKind,
RunningBackupsMixin,
)
from napalm_device_types.scheduled_jobs import (
ScheduledJobChanged,
ScheduledJobDict,
@@ -301,6 +319,13 @@ from napalm_device_types.systemd import (
parse_systemd_services,
)
from napalm_device_types.terminal import strip_terminal_codes
from napalm_device_types.time_sync import (
TIME_SYNC_VALUES,
TimeSyncDict,
TimeSyncMixin,
check_ntp_servers,
)
from napalm_device_types.time_sync_posix import PosixTimeSyncMixin, parse_time_sync
from napalm_device_types.updates import UpdateMixin
from napalm_device_types.virtual_ips import (
VIRTUAL_IPS_COMMAND,
@@ -468,6 +493,23 @@ __all__ = [
"VIRTUAL_IPS_COMMAND",
"VirtualIpsMixin",
"VmStopRequestMixin",
"RUNNING_BACKUP_KINDS",
"RunningBackupDict",
"RunningBackupKind",
"RunningBackupsMixin",
"TIME_SYNC_VALUES",
"TimeSyncDict",
"TimeSyncMixin",
"check_ntp_servers",
"PosixTimeSyncMixin",
"parse_time_sync",
"DstTransitionDict",
"PosixTzDict",
"UnknownTimezone",
"is_iana_zone",
"is_posix_tz",
"parse_posix_tz",
"posix_tz",
"VMProvisionIncomplete",
"SERVICE_CLUSTERS_COMMAND",
"ServiceClustersMixin",
+157
View File
@@ -0,0 +1,157 @@
"""How chrony is given exactly the time sources a caller names.
The sources go to one file of their own (:func:`plan_chrony` picks it):
1. the sources file in a ``sourcedir`` the main configuration reads (Debian's
``/etc/chrony/sources.d``): ``chronyc reload sources`` takes it without a restart;
2. else ``netork.conf`` -- the include file's name -- in the first ``confdir``;
3. else the include file, where an ``include`` pattern already takes it (SUSE's
``/etc/chrony.d/*.conf``);
4. else the include file, with an ``include`` line appended to the main configuration
(RHEL's ``/etc/chrony.conf``).
Every other source stops counting: a ``server``, ``pool`` or ``peer`` line in any
other file chrony reads is commented out behind :data:`COMMENT_MARK`, and so is a
``sourcedir`` line other than the one the sources file is in -- the DHCP client's
``/run/chrony-dhcp``, whose files are rewritten on every lease and so are left alone.
chronyd reads its main configuration only when it starts: a change there means a
restart.
"""
from __future__ import annotations
import posixpath
import re
import shlex
from dataclasses import dataclass, field
from fnmatch import fnmatchcase
from napalm_device_types._time_sync_reading import SOURCE_LINE, ConfigFile
#: What a source line taken out of chrony's configuration starts with.
COMMENT_MARK = "#napalm-time-sync: "
#: The comment above an ``include`` line appended to the main configuration.
INCLUDE_COMMENT = "# napalm-time-sync: the time sources"
_DIRECTORY_LINE = re.compile(r"\s*(sourcedir|confdir|include)\s+(.+?)\s*$")
@dataclass
class ChronyPlan:
"""What :func:`plan_chrony` decided."""
target: str # the file the sources go to
content: str
comment_out: dict[str, list[int]] = field(default_factory=dict) # path: line numbers
include_in: str | None = None # the main configuration an include of target is appended to
reload: bool = False # True: ``chronyc reload sources`` takes the change
def source_line(server: str) -> str:
"""The line a server is written as: a pool's name as a ``pool``, anything else a ``server``."""
directive = "pool" if ".pool." in f".{server.lower()}." else "server"
return f"{directive} {server} iburst"
def _directives(main: ConfigFile) -> list[tuple[int, str, list[str]]]:
found = []
for number, line in enumerate(main.lines, start=1):
match = _DIRECTORY_LINE.match(line)
if match:
found.append((number, match[1], match[2].split()))
return found
def _arguments(directives: list[tuple[int, str, list[str]]], kind: str) -> list[str]:
return [arg for _, k, args in directives if k == kind for arg in args]
def _target(main: ConfigFile, sources_file: str, include_file: str) -> tuple[str, str | None, bool]:
"""The file the sources go to, the main configuration to include it from, and
whether it is a sources file."""
directives = _directives(main)
if posixpath.dirname(sources_file) in _arguments(directives, "sourcedir"):
return sources_file, None, True
confdirs = _arguments(directives, "confdir")
if confdirs:
return posixpath.join(confdirs[0], posixpath.basename(include_file)), None, False
if any(fnmatchcase(include_file, p) for p in _arguments(directives, "include")):
return include_file, None, False
return include_file, main.path, False
def _dropped_sourcedirs(main: ConfigFile, kept: str | None) -> set[int]:
"""The ``sourcedir`` lines of *main* that do not name the directory *kept*."""
return {
number
for number, kind, args in _directives(main)
if kind == "sourcedir" and (kept is None or kept not in args)
}
def _lines_to_comment(f: ConfigFile, dropped: set[int]) -> list[int]:
return [
number
for number, line in enumerate(f.lines, start=1)
if SOURCE_LINE.match(line) or (f.kind == "main" and number in dropped)
]
def plan_chrony(
files: list[ConfigFile], servers: list[str], *, sources_file: str, include_file: str
) -> ChronyPlan:
"""Where *servers* go and what else is commented out.
:raises RuntimeError: when the reading found no chrony configuration.
"""
main = next((f for f in files if f.kind == "main"), None)
if main is None:
raise RuntimeError("chrony runs, but no chrony configuration was found to write to")
target, include_in, is_sources = _target(main, sources_file, include_file)
dropped = _dropped_sourcedirs(main, posixpath.dirname(target) if is_sources else None)
comment_out = _comment_out(files, target, dropped)
return ChronyPlan(
target=target,
content="".join(f"{source_line(s)}\n" for s in servers),
comment_out=comment_out,
include_in=include_in,
reload=is_sources and include_in is None and _only_sources_files(files, comment_out),
)
def _only_sources_files(files: list[ConfigFile], changed: dict[str, list[int]]) -> bool:
"""Whether every file that changes is one ``chronyc reload sources`` reads again."""
return all(f.kind == "sourcedir" for f in files if f.path in changed)
def _comment_out(files: list[ConfigFile], target: str, dropped: set[int]) -> dict[str, list[int]]:
"""Per file, the lines that take a source; a dropped ``sourcedir``'s files are not read."""
found: dict[str, list[int]] = {}
for f in files:
if f.path == target or (f.kind == "sourcedir" and f.at in dropped):
continue
numbers = _lines_to_comment(f, dropped)
if numbers:
found[f.path] = numbers
return found
def comment_out_command(path: str, numbers: list[int]) -> str:
"""``sed`` that comments out those lines of *path* that still hold a source or a sourcedir."""
edits = " ".join(
"-e "
+ shlex.quote(
f"{n}{{/^[[:space:]]*(server|pool|peer|sourcedir)[[:space:]]/s/^/{COMMENT_MARK}/;}}"
)
for n in numbers
)
return f"sed -i -E {edits} {shlex.quote(path)}"
def include_command(main: str, target: str) -> str:
"""Append an ``include`` of *target* to *main*, on a line of its own."""
lines = " ".join(shlex.quote(line) for line in (INCLUDE_COMMENT, f"include {target}"))
return (
f'{{ [ -z "$(tail -c 1 -- {shlex.quote(main)})" ] || echo; '
f"printf '%s\\n' {lines}; }} >> {shlex.quote(main)}"
)
+301
View File
@@ -0,0 +1,301 @@
"""The reading behind :class:`~napalm_device_types.time_sync_posix.PosixTimeSyncMixin`.
One command, as the login user, prints framed sections (``@@ts <name> ...``):
* ``timedatectl`` -- ``timedatectl show``: the zone, and whether the kernel clock is
synchronised;
* ``zone`` -- ``/etc/timezone`` or the target of ``/etc/localtime``, for a host
without timedatectl;
* ``active`` -- one ``<unit> <daemon> <state>`` line per time sync service;
* ``timesync`` -- ``timedatectl show-timesync``: systemd-timesyncd's servers;
* ``chronyc`` -- ``chronyc -n sources``: whether chronyd has selected a source;
* ``chrony <line> <kind> <path>`` -- chrony's main configuration (line 0, kind
``main``), then each file an ``include``, ``confdir`` or ``sourcedir`` on that
line of it reads;
* ``ntpd <path>``, ``openntpd <path>`` -- their configuration;
* ``end`` -- the reading is complete.
"""
from __future__ import annotations
import re
import shlex
from dataclasses import dataclass, field
from napalm_device_types.time_sync import TimeSyncDict
_MARK = "@@ts "
#: ``<unit> <daemon>``: the services that keep a host's clock; the first active one counts.
TIME_SYNC_UNITS: tuple[tuple[str, str], ...] = (
("chrony", "chrony"),
("chronyd", "chrony"),
("systemd-timesyncd", "systemd-timesyncd"),
("ntpsec", "ntpd"),
("ntp", "ntpd"),
("ntpd", "ntpd"),
("openntpd", "openntpd"),
)
#: A source line of chrony's or ntpd's configuration: the directive and what follows.
SOURCE_LINE = re.compile(r"\s*(server|pool|peer)\s+(.*)")
_OPENNTPD_SOURCE = re.compile(r"\s*(servers?)\s+(\S+)")
_ZONE_NAME = re.compile(r"[A-Za-z0-9_+-]+(?:/[A-Za-z0-9_+-]+)*")
#: ntpd's reference clocks are addresses in 127.127.0.0/16, not servers.
_REFCLOCK = "127.127."
# The files a chrony configuration reads, each after a marker with the line that names it.
_CHRONY_FOLLOW = """\
awk '$1=="include"||$1=="confdir"||$1=="sourcedir"{for(i=2;i<=NF;i++)print NR, $1, $i}' "$c" |
while read -r n k p; do
case $k in include) set -- $p ;; confdir) set -- "$p"/*.conf ;; *) set -- "$p"/*.sources ;; esac
for f in "$@"; do
[ -f "$f" ] && { printf '@@ts chrony %s %s %s\\n' "$n" "$k" "$f"; cat -- "$f"; echo; }
done
done"""
@dataclass(frozen=True)
class ReadPaths:
"""Where a host keeps what the reading reads."""
units: tuple[tuple[str, str], ...]
chrony_configs: tuple[str, ...]
ntpd_configs: tuple[str, ...]
openntpd_configs: tuple[str, ...]
time_zone_sh: str
@dataclass
class ConfigFile:
"""One configuration file as the reading printed it."""
path: str
kind: str # "main", "include", "confdir", "sourcedir"; "ntpd", "openntpd"
at: int # the line of the main configuration that names it; 0 for that file itself
lines: list[str] = field(default_factory=list)
@dataclass
class Reading:
"""Everything one reading said."""
timedatectl: dict[str, str] = field(default_factory=dict)
zone_files: list[str] = field(default_factory=list)
active: list[tuple[str, str]] = field(default_factory=list) # (unit, daemon), active ones
timesync: dict[str, str] = field(default_factory=dict)
chronyc: str = ""
chrony: list[ConfigFile] = field(default_factory=list)
ntpd: ConfigFile | None = None
openntpd: ConfigFile | None = None
@property
def daemon(self) -> str | None:
return self.active[0][1] if self.active else None
@property
def unit(self) -> str | None:
return self.active[0][0] if self.active else None
def _first_file(kind: str, paths: tuple[str, ...]) -> str:
candidates = " ".join(shlex.quote(p) for p in paths)
return (
f'for c in {candidates}; do [ -f "$c" ] && '
f'{{ printf \'@@ts {kind} %s\\n\' "$c"; cat -- "$c"; echo; break; }}; done'
)
def reading_command(paths: ReadPaths) -> str:
"""The command that prints the reading; ``sh`` runs it, whatever the login shell."""
active = "\n".join(
f"printf '%s %s %s\\n' {shlex.quote(unit)} {shlex.quote(daemon)} "
f'"$(systemctl is-active {shlex.quote(unit + ".service")} 2>/dev/null)"'
for unit, daemon in paths.units
)
chrony = " ".join(shlex.quote(p) for p in paths.chrony_configs)
script = "\n".join(
[
"echo '@@ts timedatectl'",
"timedatectl show 2>/dev/null",
"echo '@@ts zone'",
f"{{ {paths.time_zone_sh}; }}",
"echo '@@ts active'",
active,
"echo '@@ts timesync'",
"timedatectl show-timesync 2>/dev/null",
"echo '@@ts chronyc'",
"chronyc -n sources 2>/dev/null",
f'for c in {chrony}; do [ -f "$c" ] || continue',
'printf \'@@ts chrony 0 main %s\\n\' "$c"; cat -- "$c"; echo',
_CHRONY_FOLLOW,
"break; done",
_first_file("ntpd", paths.ntpd_configs),
_first_file("openntpd", paths.openntpd_configs),
"echo '@@ts end'",
]
)
return f"sh -c {shlex.quote(script)}"
def parse_key_values(text: str) -> dict[str, str]:
"""``Key=value`` lines (``timedatectl show``, ``show-timesync``)."""
values: dict[str, str] = {}
for line in text.splitlines():
key, sep, value = line.partition("=")
if sep and key.strip():
values[key.strip()] = value.strip()
return values
def _sections(text: str) -> list[tuple[list[str], list[str]]]:
sections: list[tuple[list[str], list[str]]] = []
for line in text.splitlines():
if line.startswith(_MARK):
sections.append((line[len(_MARK) :].split(maxsplit=3), []))
elif sections:
sections[-1][1].append(line)
return sections
def _active(lines: list[str]) -> list[tuple[str, str]]:
rows = [line.split() for line in lines]
return [(r[0], r[1]) for r in rows if len(r) == 3 and r[2] == "active"]
def _take(reading: Reading, header: list[str], lines: list[str]) -> None:
name, text = header[0], "\n".join(lines)
if name == "chrony" and len(header) == 4:
reading.chrony.append(ConfigFile(header[3], header[2], int(header[1]), lines))
elif name in ("ntpd", "openntpd") and len(header) == 2:
setattr(reading, name, ConfigFile(header[1], name, 0, lines))
else:
simple = {
"timedatectl": ("timedatectl", parse_key_values(text)),
"zone": ("zone_files", lines),
"active": ("active", _active(lines)),
"timesync": ("timesync", parse_key_values(text)),
"chronyc": ("chronyc", text),
}
if name in simple:
setattr(reading, *simple[name])
def parse_reading(text: str) -> Reading:
"""The reading's sections. :raises ValueError: for a reading cut short."""
sections = _sections(text)
if not sections or sections[-1][0] != ["end"]:
raise ValueError("the time sync reading was cut short")
reading = Reading()
for header, lines in sections:
_take(reading, header, lines)
return reading
def _source_name(rest: str) -> str | None:
"""The server in what follows ``server``/``pool``/``peer``: ntpd puts ``-4`` first."""
return next((word for word in rest.split() if not word.startswith("-")), None)
def chrony_servers(files: list[ConfigFile]) -> list[str]:
"""chrony's sources in the order it reads them: each file in place of the line naming it."""
main = next((f for f in files if f.kind == "main"), None)
if main is None:
return []
found: list[str] = []
for number, line in enumerate(main.lines, start=1):
found.extend(_sources([line]))
for included in (f for f in files if f.at == number and f.kind != "main"):
found.extend(_sources(included.lines))
return found
def _sources(lines: list[str]) -> list[str]:
names = []
for line in lines:
match = SOURCE_LINE.match(line)
if match and (name := _source_name(match[2])):
names.append(name)
return names
def ntpd_servers(lines: list[str]) -> list[str]:
"""ntpd's servers, pools and peers; reference clocks are not servers."""
return [name for name in _sources(lines) if not name.startswith(_REFCLOCK)]
def openntpd_servers(lines: list[str]) -> list[str]:
"""OpenNTPD's ``server`` and ``servers``; ``constraint`` and ``sensor`` are no sources."""
return [m[2] for line in lines if (m := _OPENNTPD_SOURCE.match(line))]
def timesyncd_servers(values: dict[str, str]) -> list[str]:
"""systemd-timesyncd's servers in the order it tries them; the fallback only alone."""
found: list[str] = []
for key in ("RuntimeNTPServers", "SystemNTPServers", "LinkNTPServers"):
for server in values.get(key, "").split():
if server not in found:
found.append(server)
return found or values.get("FallbackNTPServers", "").split()
def chrony_synchronized(sources: str) -> bool | None:
"""Whether chronyd has selected a source (``^*``); None for no answer from chronyc."""
rows = [line for line in sources.splitlines() if line[:1] in ("^", "=", "#")]
if not rows:
return None
return any(line[1:2] == "*" for line in rows)
def _zone_name(value: str) -> str | None:
value = value.strip()
if "zoneinfo/" in value:
value = value.split("zoneinfo/", 1)[1]
for prefix in ("posix/", "right/"):
value = value.removeprefix(prefix)
return value if _ZONE_NAME.fullmatch(value) else None
def _time_zone(reading: Reading) -> str | None:
named = reading.timedatectl.get("Timezone", "")
if named and named != "n/a":
return _zone_name(named)
return next((z for line in reading.zone_files if (z := _zone_name(line))), None)
def _servers(reading: Reading) -> list[str]:
if reading.daemon == "chrony":
return chrony_servers(reading.chrony)
if reading.daemon == "systemd-timesyncd":
return timesyncd_servers(reading.timesync)
if reading.daemon == "ntpd" and reading.ntpd is not None:
return ntpd_servers(reading.ntpd.lines)
if reading.daemon == "openntpd" and reading.openntpd is not None:
return openntpd_servers(reading.openntpd.lines)
return []
def _synchronized(reading: Reading) -> bool | None:
if reading.daemon == "chrony":
chrony = chrony_synchronized(reading.chronyc)
if chrony is not None:
return chrony
return {"yes": True, "no": False}.get(reading.timedatectl.get("NTPSynchronized", ""))
def time_sync_of(reading: Reading) -> TimeSyncDict:
"""What a reading says, as ``get_time_sync`` returns it."""
return {
"ntp_servers": _servers(reading),
"timezone": _time_zone(reading),
"synchronized": _synchronized(reading),
"daemon": reading.daemon,
}
def parse_time_sync(text: str) -> TimeSyncDict:
"""The reading's output as ``get_time_sync`` returns it.
:raises ValueError: for a reading cut short.
"""
return time_sync_of(parse_reading(text))
+176
View File
@@ -0,0 +1,176 @@
"""A time zone as a device takes it: an IANA name, a POSIX TZ rule, or the rule's parts.
An application names a zone the IANA way (``Europe/Berlin``). Not every device
can: OpenWrt hands ``system.timezone`` to libc as ``TZ``, which wants the rule
itself (``CET-1CEST,M3.5.0,M10.5.0/3``), and a switch wants a UTC offset and the
summer-time rule. A driver translates with these helpers.
The rule is the footer of the zone's TZif file (version 2 and later): the line
after the last transition that says how the zone goes on. OpenWrt's LuCI table is
built from the same footers. The files come from the ``tzdata`` package, a
declared dependency, so every driver reads the same database whatever its host
ships.
"""
from __future__ import annotations
import re
from functools import lru_cache
from importlib.resources import files
from typing import TypedDict
#: An IANA name: letters, digits, ``_+-`` in ``/``-separated parts. No dots, so
#: nothing reaches outside the database.
_ZONE_NAME = re.compile(r"[A-Za-z0-9_+-]+(?:/[A-Za-z0-9_+-]+)*")
_ABBR = r"(?:[A-Za-z]{3,}|<[A-Za-z0-9+-]{3,}>)"
_OFFSET = r"[+-]?\d{1,2}(?::\d{1,2}){0,2}"
_DATE = r"(?:J\d{1,3}|\d{1,3}|M\d{1,2}\.\d\.\d)(?:/[+-]?\d{1,3}(?::\d{1,2}){0,2})?"
#: ``std offset [dst [offset] [,start,end]]`` (POSIX.1, 8.3), and a bare ``UTC`` or
#: ``GMT``, which OpenWrt itself writes by default.
_POSIX_TZ = re.compile(
rf"(?:UTC|GMT)|{_ABBR}{_OFFSET}(?:{_ABBR}(?:{_OFFSET})?(?:,{_DATE},{_DATE})?)?"
)
_PARTS = re.compile(
rf"(?P<std>{_ABBR})(?P<offset>{_OFFSET})"
rf"(?:(?P<dst>{_ABBR})(?P<dst_offset>{_OFFSET})?"
r"(?:,(?P<start>[^,]+),(?P<end>[^,]+))?)?"
)
_TRANSITION = re.compile(r"M(\d{1,2})\.([1-5])\.([0-6])(?:/([+-]?\d{1,3}(?::\d{1,2}){0,2}))?")
#: When a rule names no time of day for a transition: 02:00 local time.
_DEFAULT_TRANSITION_TIME = 7200
class DstTransitionDict(TypedDict):
"""When summer time starts or ends: a weekday of a week of a month, and a time."""
month: int # 1-12
week: int # 1-5; 5 is the month's last such weekday
weekday: int # 0 = Sunday ... 6 = Saturday
time: int # seconds after local midnight, in the time then in force; may be < 0 or > 24h
class PosixTzDict(TypedDict):
"""A POSIX TZ rule in parts (:func:`parse_posix_tz`)."""
std_name: str # "CET"; a quoted name without its <> ("-03")
utc_offset: int # seconds east of UTC in standard time: CET 3600, EST -18000
dst_name: str | None # "CEST"; None for a zone without summer time
dst_offset: int | None # seconds east of UTC in summer time; None without it
dst_start: DstTransitionDict | None # None without summer time or without a rule for it
dst_end: DstTransitionDict | None
class UnknownTimezone(ValueError):
"""A zone that is not in the zone database (nor, where one is taken, a POSIX TZ rule)."""
def __init__(self, zone: str) -> None:
super().__init__(zone)
self.zone = zone
def __str__(self) -> str:
return (
f"unknown time zone {self.zone!r}: not a name of the IANA time zone database"
" such as Europe/Berlin"
)
def is_posix_tz(value: str) -> bool:
"""Whether *value* reads as a POSIX TZ string -- the form libc takes in ``TZ``."""
return bool(_POSIX_TZ.fullmatch(value))
@lru_cache(maxsize=512)
def _footer(zone: str) -> str | None:
"""The POSIX rule at the end of *zone*'s TZif file; None for no such zone."""
if not _ZONE_NAME.fullmatch(zone):
return None
tzfile = files("tzdata").joinpath("zoneinfo", *zone.split("/"))
if not tzfile.is_file():
return None
data = tzfile.read_bytes()
if not data.startswith(b"TZif") or data[4:5] not in (b"2", b"3", b"4") or data[-1:] != b"\n":
return None
footer = data[:-1].rsplit(b"\n", 1)[-1].decode("ascii", "replace")
return footer if is_posix_tz(footer) else None
def is_iana_zone(zone: str) -> bool:
"""Whether *zone* names a zone of the database (``Europe/Berlin``, ``UTC``)."""
return _footer(zone) is not None
def posix_tz(zone: str) -> str | None:
"""The POSIX TZ string for *zone*: an IANA name's rule, a POSIX string as it is.
None when *zone* is neither -- a device given it would run on UTC.
"""
return _footer(zone) or (zone if is_posix_tz(zone) else None)
def _seconds(value: str) -> int:
"""``[+-]hh[:mm[:ss]]`` in seconds."""
sign = -1 if value.startswith("-") else 1
parts = [int(p) for p in value.lstrip("+-").split(":")]
hours, minutes, seconds = (parts + [0, 0])[:3]
return sign * (hours * 3600 + minutes * 60 + seconds)
def _transition(value: str) -> DstTransitionDict | None:
match = _TRANSITION.fullmatch(value)
if match is None:
return None
month, week, weekday, time = match.groups()
return {
"month": int(month),
"week": int(week),
"weekday": int(weekday),
"time": _DEFAULT_TRANSITION_TIME if time is None else _seconds(time),
}
def parse_posix_tz(rule: str) -> PosixTzDict | None:
"""*rule* in parts; None for what is not a rule, or one with Julian-day transitions.
POSIX counts offsets west of UTC (``CET-1``); the parts count them east, as a
device's "UTC+01:00" does. Summer time without an offset of its own is one hour
ahead of standard time.
"""
if rule in ("UTC", "GMT"):
rule += "0"
match = _PARTS.fullmatch(rule)
if match is None or not is_posix_tz(rule):
return None
utc_offset = -_seconds(match["offset"])
parts: PosixTzDict = {
"std_name": match["std"].strip("<>"),
"utc_offset": utc_offset,
"dst_name": None,
"dst_offset": None,
"dst_start": None,
"dst_end": None,
}
if match["dst"] is None:
return parts
parts["dst_name"] = match["dst"].strip("<>")
parts["dst_offset"] = (
utc_offset + 3600 if match["dst_offset"] is None else -_seconds(match["dst_offset"])
)
if match["start"] is not None:
start, end = _transition(match["start"]), _transition(match["end"])
if start is None or end is None:
return None
parts["dst_start"], parts["dst_end"] = start, end
return parts
__all__ = [
"DstTransitionDict",
"PosixTzDict",
"UnknownTimezone",
"is_iana_zone",
"is_posix_tz",
"parse_posix_tz",
"posix_tz",
]
+69
View File
@@ -0,0 +1,69 @@
"""The backups running on a device right now.
A restart aborts every backup that runs on the device it restarts: a
hypervisor's backup of its guests, a backup server's backup, sync, verify or
garbage collection, a host's own file-level backup (restic, borg and the like).
A guest's restart breaks the backup its hypervisor is taking of it. So an
application that restarts a device asks first, right before the restart.
Declared under ``if TYPE_CHECKING``: a driver mixes this in when it can tell;
``hasattr`` tells a caller whether it did. No role base carries it, and a driver
without it cannot tell -- which is not the same as "nothing runs".
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Literal, TypedDict, get_args
#: What a running backup does: the backup itself, or one of a backup server's
#: jobs (``napalm_device_types.backups.BackupJobKind``).
RunningBackupKind = Literal["backup", "sync", "verify", "gc", "prune", "tape"]
RUNNING_BACKUP_KINDS: tuple[str, ...] = get_args(RunningBackupKind)
class RunningBackupDict(TypedDict):
"""One backup running on the device (``get_running_backups``)."""
kind: RunningBackupKind
job: str | None # the job it runs for, as the platform names it; None: started by hand
task: str | None # this run's id on the platform: a task id, a unit, a process id
guests: list[str] # the guests (get_vms' ids) it is backing up now; [] for the host's own
since: int | None # unix seconds it started; None when the platform does not say
class RunningBackupsMixin:
if TYPE_CHECKING:
def get_running_backups(self) -> list[RunningBackupDict]:
"""
Returns the backups running on the device now; ``[]`` when none is.
Every entry runs on this device: restarting the device aborts it.
A hypervisor names in ``guests`` the guests a backup is taking right
now -- a guest that is locked for its backup counts, with or without
a task the platform still shows -- so the application can tell a
guest's own restart not to break it.
Example::
[
{
"kind": "backup",
"job": "backup-3f2a9c1e-77d1",
"task": "UPID:pve1:0001F2A3:00C4B1D2:6731A0C0:vzdump::root@pam:",
"guests": ["101"],
"since": 1793660400,
},
{
"kind": "gc",
"job": "store1",
"task": "UPID:localhost:000004D2:...:garbage_collection:store1:root@pam:",
"guests": [],
"since": 1793664000,
},
]
:raises Exception: when the device could not be read; never an
empty list for a failed read.
"""
...
+176
View File
@@ -0,0 +1,176 @@
"""A device's time sources and time zone: read them, and set them to what the caller says.
An application keeps one list of NTP servers and a time zone per site, and aligns a
device that differs. :class:`TimeSyncMixin` is the contract for that:
* ``get_time_sync()`` -- declared only, so ``callable(getattr(driver,
"get_time_sync", None))`` is the truthful answer to "can this driver tell";
* ``configure_time_sync(ntp_servers=None, timezone=None)`` -- a fix template
(:mod:`napalm_device_types.fixes`): ``None`` leaves that value as it is, and the
device ends up with exactly the servers given, in their order. A driver
implements the steps; one whose device takes the change in a single call
overrides the method;
* ``time_sync_writes`` -- which of the two values the driver can write. A BMC that
runs on UTC only writes ``{"ntp_servers"}``; the application never asks it for a
zone.
A driver that inherits the mixin but cannot run it sets ``get_time_sync`` (and
``configure_time_sync``) to ``None``.
A zone is an IANA name on the wire. A device that wants a POSIX rule or an offset
with a summer-time rule gets it from :mod:`napalm_device_types.posix_tz`.
"""
from __future__ import annotations
import ipaddress
import re
from collections.abc import Sequence
from typing import TYPE_CHECKING, ClassVar, TypedDict
from napalm_device_types.fixes import FixStep, run_fix_steps
from napalm_device_types.models import FixResultDict, FixStepOutcomeDict
from napalm_device_types.posix_tz import UnknownTimezone, is_iana_zone
#: The values a driver can write; ``time_sync_writes`` is a subset.
TIME_SYNC_VALUES: frozenset[str] = frozenset({"ntp_servers", "timezone"})
_HOST_NAME = re.compile(
r"(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*\.?"
)
class TimeSyncDict(TypedDict):
"""How a device keeps its clock (``get_time_sync``)."""
ntp_servers: list[str] # configured time sources, in the device's order; [] = none configured
timezone: str | None # IANA name ("Europe/Berlin"); None = not readable or no named zone
synchronized: bool | None # the clock is synchronised to a source right now; None = unknown
daemon: str | None # "chrony", "systemd-timesyncd", "ntpd", "openntpd", ...; None = own client
def _is_server(name: str) -> bool:
try:
ipaddress.ip_address(name)
except ValueError:
return bool(_HOST_NAME.fullmatch(name))
return True
def check_ntp_servers(servers: Sequence[str]) -> list[str]:
"""*servers* as a driver writes them: stripped, in their order, each once.
:raises ValueError: for no server at all, or one that is not a host name or
an IP address -- before anything reaches a configuration file.
:raises TypeError: for a single string instead of a list of them.
"""
if isinstance(servers, str):
raise TypeError("ntp_servers is a list of servers, not one string")
kept: list[str] = []
for server in (str(s).strip() for s in servers):
if not server:
continue
if not _is_server(server):
raise ValueError(f"{server!r} is not a host name or address of an NTP server")
if server.lower() not in (k.lower() for k in kept):
kept.append(server)
if not kept:
raise ValueError("name at least one NTP server; None leaves the servers as they are")
return kept
class TimeSyncMixin:
"""Read and set a device's time sources and time zone; see the module."""
#: Which of the two values this driver can write: a subset of {"ntp_servers", "timezone"}.
#: A BMC that only runs on UTC writes {"ntp_servers"}; an application never asks it for a
#: zone. Declared only: a driver that names nothing writes nothing.
time_sync_writes: ClassVar[frozenset[str]]
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
def get_time_sync(self) -> TimeSyncDict:
"""How the device keeps its clock now.
``ntp_servers`` are the sources its configuration names, in its order
(a pool by its name, not the addresses it resolved to). ``timezone``
is an IANA name, or None where the device keeps an offset and a rule
instead of a name. ``daemon`` names the client that keeps the clock on
a host that has a choice; None for a device's own.
Example::
{
"ntp_servers": ["ntp1.example.org", "10.0.0.1"],
"timezone": "Europe/Berlin",
"synchronized": True,
"daemon": "chrony",
}
:raises Exception: when the device could not be read.
"""
...
# The steps a driver implements:
def _write_ntp_servers(self, servers: list[str]) -> FixStepOutcomeDict:
"""Leave the device with exactly *servers*, in this order: sources it
had configured elsewhere stop counting (commented out, replaced)."""
...
def _write_time_zone(self, zone: str) -> FixStepOutcomeDict:
"""Set the device's zone to *zone*, an IANA name of the database."""
...
def configure_time_sync(
self, ntp_servers: Sequence[str] | None = None, timezone: str | None = None
) -> FixResultDict:
"""Give the device exactly *ntp_servers*, in order, and *timezone*; None leaves one alone.
The steps: ``ntp_servers``, ``timezone``, then ``verify``, which reads the
device again.
:raises UnknownTimezone: for a *timezone* that is not an IANA name of the
database, before anything is written.
:raises ValueError: for a value this driver does not write
(:attr:`time_sync_writes`), for no server or a malformed one, or for
nothing asked -- before anything is written.
"""
servers = None if ntp_servers is None else check_ntp_servers(ntp_servers)
if timezone is not None and not is_iana_zone(timezone):
raise UnknownTimezone(timezone)
asked = {name for name, v in (("ntp_servers", servers), ("timezone", timezone)) if v}
if not asked:
raise ValueError("nothing to configure: name ntp_servers, timezone or both")
refused = asked - getattr(self, "time_sync_writes", frozenset())
if refused:
raise ValueError(f"this driver does not write {', '.join(sorted(refused))}")
steps: list[FixStep] = []
if servers is not None:
steps.append(("ntp_servers", lambda: self._write_ntp_servers(servers)))
if timezone is not None:
steps.append(("timezone", lambda: self._write_time_zone(timezone)))
steps.append(("verify", lambda: self._verify_time_sync(servers, timezone)))
return run_fix_steps(steps)
def _verify_time_sync(self, servers: list[str] | None, zone: str | None) -> FixStepOutcomeDict:
"""Read the device again: does it now have what was written?
Servers compare without case. A zone is compared where the device reads
one back by name.
"""
now = self.get_time_sync()
wrong: list[str] = []
if servers is not None and [s.lower() for s in now["ntp_servers"]] != [
s.lower() for s in servers
]:
wrong.append(f"the device has the servers {', '.join(now['ntp_servers']) or 'none'}")
if zone is not None and now["timezone"] is not None and now["timezone"] != zone:
wrong.append(f"the device is in the time zone {now['timezone']}")
if wrong:
return {"ok": False, "output": "; ".join(wrong)}
return {"ok": True, "output": "the device reads back what was written"}
__all__ = ["TIME_SYNC_VALUES", "TimeSyncDict", "TimeSyncMixin", "check_ntp_servers"]
+203
View File
@@ -0,0 +1,203 @@
"""Time sync on a POSIX host, over the command channel: chrony, systemd-timesyncd, timedatectl.
:class:`PosixTimeSyncMixin` implements
:class:`~napalm_device_types.time_sync.TimeSyncMixin` for a driver that has
:meth:`~napalm_device_types.channel.CommandChannelMixin.run_command`. The defaults
are Debian's paths; a driver sets its host's.
**Reading** is one round trip as the login user
(:mod:`napalm_device_types._time_sync_reading`): ``timedatectl show`` for the zone
(``/etc/timezone`` or ``/etc/localtime``'s target without it), which time sync
service is active, and that client's configuration -- chrony's files as chronyd
reads them, ``timedatectl show-timesync`` for systemd-timesyncd, ``ntp.conf``,
OpenNTPD's ``ntpd.conf``. Synchronised is chronyd's own word where it runs (a
selected source in ``chronyc -n sources``), else the kernel's (``NTPSynchronized``).
**Writing** runs as root through ``run_command(privileged=True)``; root never reads
stdin -- a file is staged by the login user and installed by root.
* The zone: ``timedatectl set-timezone``.
* chrony: the servers go to a file of their own and every other source is commented
out (:mod:`napalm_device_types._chrony`), then ``chronyc reload sources``, or a
restart of chronyd where its main configuration changed or it cannot reload.
* systemd-timesyncd: :attr:`~PosixTimeSyncMixin.TIMESYNCD_DROPIN` resets ``NTP=``,
sets the servers and empties ``FallbackNTP=``, then the service restarts. Servers a
network link brings (DHCP through systemd-networkd) are not timesyncd's to drop;
they stay, and the ``verify`` step names them.
* ntpd, OpenNTPD, or no client: the servers are read, not written -- the step fails
and says so.
"""
from __future__ import annotations
import shlex
from collections.abc import Sequence
from typing import TYPE_CHECKING, ClassVar
from napalm_device_types._chrony import (
COMMENT_MARK,
comment_out_command,
include_command,
plan_chrony,
)
from napalm_device_types._scheduled_reading import TIME_ZONE_SH
from napalm_device_types._time_sync_reading import (
TIME_SYNC_UNITS,
Reading,
ReadPaths,
chrony_synchronized,
parse_key_values,
parse_reading,
parse_time_sync,
reading_command,
time_sync_of,
timesyncd_servers,
)
from napalm_device_types.models import FixStepOutcomeDict
from napalm_device_types.time_sync import TIME_SYNC_VALUES, TimeSyncDict, TimeSyncMixin
if TYPE_CHECKING:
from napalm_device_types.channel import CommandResult
_STAGE = 't=$(mktemp) && chmod 644 "$t" && cat > "$t" && printf %s "$t"'
_WRITERS = "chrony and systemd-timesyncd"
#: The head of the systemd-timesyncd drop-in.
TIMESYNCD_HEADER = (
"# The time sources, exactly these: written by napalm-device-types'\n"
"# PosixTimeSyncMixin and replaced on every change.\n"
)
def _said(result: CommandResult) -> str:
return "\n".join(p for p in (result.stdout.strip(), result.stderr.strip()) if p)
def timesyncd_dropin(servers: Sequence[str]) -> str:
"""The drop-in that leaves systemd-timesyncd with exactly *servers*."""
return f"{TIMESYNCD_HEADER}[Time]\nNTP=\nNTP={' '.join(servers)}\nFallbackNTP=\n"
class PosixTimeSyncMixin(TimeSyncMixin):
"""Time sync of a host reached through ``run_command``; the paths are the driver's."""
time_sync_writes: ClassVar[frozenset[str]] = TIME_SYNC_VALUES
#: ``(unit, daemon)``: the services that keep the clock; the first active one counts.
TIME_SYNC_UNITS: ClassVar[tuple[tuple[str, str], ...]] = TIME_SYNC_UNITS
#: chrony's main configuration: the first that exists.
CHRONY_CONFIGS: ClassVar[tuple[str, ...]] = ("/etc/chrony/chrony.conf", "/etc/chrony.conf")
#: The servers' file where the main configuration has a ``sourcedir`` of its directory.
CHRONY_SOURCES_FILE: ClassVar[str] = "/etc/chrony/sources.d/netork.sources"
#: The servers' file otherwise (its name also in a ``confdir``); included if need be.
CHRONY_INCLUDE_FILE: ClassVar[str] = "/etc/chrony.d/netork.conf"
TIMESYNCD_DROPIN: ClassVar[str] = "/etc/systemd/timesyncd.conf.d/netork.conf"
NTPD_CONFIGS: ClassVar[tuple[str, ...]] = ("/etc/ntpsec/ntp.conf", "/etc/ntp.conf")
OPENNTPD_CONFIGS: ClassVar[tuple[str, ...]] = ("/etc/openntpd/ntpd.conf", "/etc/ntpd.conf")
#: ``sh`` that prints the zone without timedatectl: a name, or a path ending in it.
TIME_ZONE_SH: ClassVar[str] = TIME_ZONE_SH
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
def run_command(
self,
command: str,
*,
privileged: bool = False,
timeout: float = 60,
stdin: bytes | None = None,
) -> CommandResult: ...
# -- reading ---------------------------------------------------------------------------------
def _ts_read(self) -> Reading:
paths = ReadPaths(
units=self.TIME_SYNC_UNITS,
chrony_configs=self.CHRONY_CONFIGS,
ntpd_configs=self.NTPD_CONFIGS,
openntpd_configs=self.OPENNTPD_CONFIGS,
time_zone_sh=self.TIME_ZONE_SH,
)
return parse_reading(self.run_command(reading_command(paths), timeout=60).stdout)
def get_time_sync(self) -> TimeSyncDict:
"""The host's time sources, zone and client, in one round trip as the login user.
:raises ValueError: when the reading came back cut short.
"""
return time_sync_of(self._ts_read())
# -- writing ---------------------------------------------------------------------------------
def _ts_root(self, command: str) -> CommandResult:
return self.run_command(command, privileged=True, timeout=60)
def _ts_checked(self, command: str) -> str:
result = self._ts_root(command)
if result.exit_code != 0:
raise RuntimeError(f"{command}: {_said(result) or f'exit {result.exit_code}'}")
return _said(result)
def _ts_install(self, path: str, content: str) -> None:
"""*content* to *path* as root, staged by the login user: root reads no stdin."""
staged = self.run_command(_STAGE, timeout=30, stdin=content.encode())
tmp = (staged.stdout.strip().splitlines() or [""])[-1]
if staged.exit_code != 0 or not tmp.startswith("/"):
raise RuntimeError(f"cannot stage {path}: {_said(staged)}")
try:
self._ts_checked(shlex.join(["install", "-D", "-m", "644", "--", tmp, path]))
finally:
self.run_command(shlex.join(["rm", "-f", "--", tmp]), timeout=30)
def _write_time_zone(self, zone: str) -> FixStepOutcomeDict:
result = self._ts_root(shlex.join(["timedatectl", "set-timezone", zone]))
if result.exit_code != 0:
return {"ok": False, "output": _said(result) or f"exit {result.exit_code}"}
return {"ok": True, "output": f"time zone set to {zone}"}
def _write_ntp_servers(self, servers: list[str]) -> FixStepOutcomeDict:
reading = self._ts_read()
if reading.daemon == "chrony":
return self._ts_chrony(reading, servers)
if reading.daemon == "systemd-timesyncd":
return self._ts_timesyncd(servers)
runs = f"this host runs {reading.daemon}" if reading.daemon else "none runs here"
return {"ok": False, "output": f"time sources are written for {_WRITERS}; {runs}"}
def _ts_timesyncd(self, servers: list[str]) -> FixStepOutcomeDict:
self._ts_install(self.TIMESYNCD_DROPIN, timesyncd_dropin(servers))
self._ts_checked("systemctl restart systemd-timesyncd.service")
return {"ok": True, "output": f"wrote {self.TIMESYNCD_DROPIN}; restarted systemd-timesyncd"}
def _ts_chrony(self, reading: Reading, servers: list[str]) -> FixStepOutcomeDict:
plan = plan_chrony(
reading.chrony,
servers,
sources_file=self.CHRONY_SOURCES_FILE,
include_file=self.CHRONY_INCLUDE_FILE,
)
said = [f"wrote {plan.target}"]
self._ts_install(plan.target, plan.content)
for path, numbers in plan.comment_out.items():
self._ts_checked(comment_out_command(path, numbers))
said.append(f"commented out {path}:{','.join(map(str, numbers))}")
if plan.include_in is not None:
self._ts_checked(include_command(plan.include_in, plan.target))
said.append(f"included it from {plan.include_in}")
if not (plan.reload and self._ts_root("chronyc reload sources").exit_code == 0):
self._ts_checked(shlex.join(["systemctl", "restart", f"{reading.unit}.service"]))
said.append(f"restarted {reading.unit}")
else:
said.append("reloaded the sources")
return {"ok": True, "output": "; ".join(said)}
__all__ = [
"COMMENT_MARK",
"PosixTimeSyncMixin",
"chrony_synchronized",
"parse_key_values",
"parse_time_sync",
"timesyncd_dropin",
"timesyncd_servers",
]
+2 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "napalm-device-types"
version = "4.33.0"
version = "4.35.0"
description = "Abstract device-type base classes for NAPALM drivers"
readme = "README.md"
requires-python = ">=3.12"
@@ -40,6 +40,7 @@ dependencies = [
"napalm>=5.1", # older releases import pkg_resources, which a 3.12 venv lacks
"requests>=2.25.0",
"typing-extensions>=4.0",
"tzdata>=2024.1", # posix_tz reads the zones' TZif files from it
]
[project.urls]
+161
View File
@@ -0,0 +1,161 @@
"""A time zone as a device takes it: an IANA name, a POSIX TZ rule, or its parts.
The wire carries IANA names (``Europe/Berlin``). OpenWrt hands ``TZ`` to libc and
wants the rule itself (``CET-1CEST,M3.5.0,M10.5.0/3``); a switch wants a UTC
offset and the summer-time rule. The rule is the footer of the zone's TZif file
from the ``tzdata`` package (moved here from netOrk's ``core/posix_tz.py`` for
NetOrk/netork#2361).
"""
from __future__ import annotations
from importlib.resources import files
import pytest
from napalm_device_types import (
PosixTzDict,
UnknownTimezone,
is_iana_zone,
is_posix_tz,
parse_posix_tz,
posix_tz,
)
BERLIN = "CET-1CEST,M3.5.0,M10.5.0/3"
def _zones() -> list[str]:
return files("tzdata").joinpath("zones").read_text().split()
@pytest.mark.parametrize(
("zone", "rule"),
[
("Europe/Berlin", BERLIN),
("America/New_York", "EST5EDT,M3.2.0,M11.1.0"),
("America/Sao_Paulo", "<-03>3"),
("Australia/Lord_Howe", "<+1030>-10:30<+11>-11,M10.1.0,M4.1.0"),
("Asia/Kolkata", "IST-5:30"),
("UTC", "UTC0"),
],
)
def test_an_iana_name_becomes_its_posix_rule(zone, rule):
assert posix_tz(zone) == rule
assert is_iana_zone(zone)
@pytest.mark.parametrize("rule", [BERLIN, "<+03>-3", "EST5EDT,M3.2.0/2,M11.1.0/2", "UTC0"])
def test_a_posix_string_is_taken_as_it_is(rule):
assert posix_tz(rule) == rule
assert not is_iana_zone(rule)
@pytest.mark.parametrize(
"value",
["Mars/Olympus_Mons", "Europe", "../../etc/passwd", "/etc/localtime", "Europe/../UTC", ""],
)
def test_neither_a_zone_nor_a_rule_has_none(value):
assert posix_tz(value) is None
assert not is_iana_zone(value)
@pytest.mark.parametrize("value", ["UTC", "GMT0", BERLIN, "<-03>3", "IST-5:30"])
def test_posix_strings(value):
assert is_posix_tz(value)
@pytest.mark.parametrize("value", ["Europe/Berlin", "America/Argentina/Buenos_Aires", "", "CET-"])
def test_not_posix_strings(value):
assert not is_posix_tz(value)
def test_every_zone_of_the_database_has_a_rule_the_check_accepts():
# A caller tells an IANA name from a rule with is_posix_tz; it must never
# take the database's own rule for a name.
zones = _zones()
missing = [z for z in zones if not is_posix_tz(posix_tz(z) or "")]
assert len(zones) > 500
assert missing == []
def test_the_refusal_names_the_zone_in_plain_english():
exc = UnknownTimezone("Mars/Olympus_Mons")
assert isinstance(exc, ValueError)
assert exc.zone == "Mars/Olympus_Mons"
assert "Mars/Olympus_Mons" in str(exc)
assert "Europe/Berlin" in str(exc)
class TestTheRuleInParts:
"""What a switch takes: the standard offset and, where there is one, the summer-time rule."""
def test_berlin(self):
assert parse_posix_tz(BERLIN) == PosixTzDict(
std_name="CET",
utc_offset=3600,
dst_name="CEST",
dst_offset=7200,
dst_start={"month": 3, "week": 5, "weekday": 0, "time": 7200},
dst_end={"month": 10, "week": 5, "weekday": 0, "time": 10800},
)
def test_utc_has_no_summer_time(self):
assert parse_posix_tz("UTC0") == {
"std_name": "UTC",
"utc_offset": 0,
"dst_name": None,
"dst_offset": None,
"dst_start": None,
"dst_end": None,
}
@pytest.mark.parametrize("bare", ["UTC", "GMT"])
def test_the_bare_names_openwrt_writes(self, bare):
parts = parse_posix_tz(bare)
assert parts is not None
assert (parts["std_name"], parts["utc_offset"], parts["dst_name"]) == (bare, 0, None)
def test_sao_paulo_has_given_up_summer_time(self):
parts = parse_posix_tz(posix_tz("America/Sao_Paulo") or "")
assert parts is not None
assert (parts["std_name"], parts["utc_offset"], parts["dst_offset"]) == (
"-03",
-10800,
None,
)
def test_lord_howe_moves_by_half_an_hour(self):
parts = parse_posix_tz(posix_tz("Australia/Lord_Howe") or "")
assert parts is not None
assert (parts["utc_offset"], parts["dst_offset"]) == (37800, 39600)
assert parts["dst_start"] == {"month": 10, "week": 1, "weekday": 0, "time": 7200}
assert parts["dst_end"] == {"month": 4, "week": 1, "weekday": 0, "time": 7200}
def test_new_york_is_west_of_utc_and_gains_an_hour_by_default(self):
parts = parse_posix_tz("EST5EDT,M3.2.0,M11.1.0")
assert parts is not None
assert (parts["utc_offset"], parts["dst_offset"]) == (-18000, -14400)
def test_a_transition_time_may_lie_outside_the_day(self):
# Greenland's rule: a day's -1:00 and 0:00 (RFC 8536 3.3.1 allows -167..167 hours).
parts = parse_posix_tz("<-02>2<-01>,M3.5.0/-1,M10.5.0/0")
assert parts is not None
assert parts["dst_start"] == {"month": 3, "week": 5, "weekday": 0, "time": -3600}
assert parts["dst_end"] == {"month": 10, "week": 5, "weekday": 0, "time": 0}
def test_offsets_with_minutes_and_seconds(self):
parts = parse_posix_tz("<+1245>-12:45<+1345>,M9.5.0/2:45,M4.1.0/3:45")
assert parts is not None
assert (parts["utc_offset"], parts["dst_offset"]) == (45900, 49500)
assert parts["dst_start"] == {"month": 9, "week": 5, "weekday": 0, "time": 9900}
@pytest.mark.parametrize("rule", ["Europe/Berlin", "", "CET-", "CET-1CEST,J60,J300"])
def test_what_it_cannot_take_apart_is_none(self, rule):
# Julian-day rules are POSIX, but no zone of the database uses them.
assert parse_posix_tz(rule) is None
def test_every_zone_of_the_database_comes_apart(self):
broken = [z for z in _zones() if parse_posix_tz(posix_tz(z) or "") is None]
assert broken == []
+51
View File
@@ -0,0 +1,51 @@
"""get_running_backups: the backups running on a device right now.
An application that restarts a device asks first, right before the restart: a
restart aborts a backup that runs on the device -- a hypervisor's vzdump, a
backup server's backup, sync, verify or garbage collection, a host's own restic
or borg run -- and a guest's restart breaks the backup its hypervisor is taking
of it (NetOrk/netork#2318). A driver mixes it in when it can tell; no role
demands it, and a driver without it cannot tell.
"""
from __future__ import annotations
import inspect
from typing import get_type_hints
from napalm_device_types import (
RUNNING_BACKUP_KINDS,
BackupServerDriver,
DeviceTypeDriver,
HypervisorDriver,
OSDriver,
RunningBackupDict,
RunningBackupsMixin,
)
def test_no_role_demands_it():
for role in (BackupServerDriver, HypervisorDriver, OSDriver, DeviceTypeDriver):
assert not issubclass(role, RunningBackupsMixin)
def test_declared_not_implemented():
"""hasattr is the caller's probe: only a driver that can tell answers True."""
assert not hasattr(RunningBackupsMixin, "get_running_backups")
def test_declaration_documents_the_contract():
source = inspect.getsource(RunningBackupsMixin)
assert "def get_running_backups(self) -> list[RunningBackupDict]" in source
assert "empty list for a failed read" in source
def test_the_kinds_cover_a_backup_servers_jobs_and_the_backup_itself():
assert set(RUNNING_BACKUP_KINDS) == {"backup", "sync", "verify", "gc", "prune", "tape"}
def test_the_shape():
hints = get_type_hints(RunningBackupDict)
assert set(hints) == {"kind", "job", "task", "guests", "since"}
assert hints["guests"] == list[str]
assert hints["since"] == int | None
+231
View File
@@ -0,0 +1,231 @@
"""TimeSyncMixin: a device's time sources and time zone, read and set (NetOrk/netork#2361).
The application keeps one list of NTP servers and a zone per site, and aligns a
device that differs. ``get_time_sync`` is declared only, so ``callable(getattr(
driver, "get_time_sync", None))`` is the truthful answer; ``configure_time_sync``
is a template of steps like every fix, and an API driver overrides it whole.
"""
from __future__ import annotations
import inspect
from typing import ClassVar, get_type_hints
import pytest
from napalm_device_types import (
TIME_SYNC_VALUES,
AccessPointDriver,
DeviceTypeDriver,
FirewallDriver,
OSDriver,
SwitchDriver,
TimeSyncDict,
TimeSyncMixin,
UnknownTimezone,
check_ntp_servers,
)
def test_the_shape():
hints = get_type_hints(TimeSyncDict)
assert hints == {
"ntp_servers": list[str],
"timezone": str | None,
"synchronized": bool | None,
"daemon": str | None,
}
def test_the_two_values_a_driver_may_write():
assert frozenset({"ntp_servers", "timezone"}) == TIME_SYNC_VALUES
def test_no_role_demands_it():
for role in (AccessPointDriver, FirewallDriver, OSDriver, SwitchDriver, DeviceTypeDriver):
assert not issubclass(role, TimeSyncMixin)
def test_the_reading_is_declared_not_implemented():
assert not hasattr(TimeSyncMixin, "get_time_sync")
source = inspect.getsource(TimeSyncMixin)
assert "def get_time_sync(self) -> TimeSyncDict" in source
assert "time_sync_writes: ClassVar[frozenset[str]]" in source
def test_the_template_takes_both_values_or_none_of_them():
signature = inspect.signature(TimeSyncMixin.configure_time_sync)
assert list(signature.parameters) == ["self", "ntp_servers", "timezone"]
assert signature.parameters["ntp_servers"].default is None
assert signature.parameters["timezone"].default is None
class _Device(TimeSyncMixin):
"""A device that keeps its values in memory and reads back what it was given."""
time_sync_writes: ClassVar[frozenset[str]] = frozenset({"ntp_servers", "timezone"})
def __init__(self, *, keeps_zone_name: bool = True, fail: str = "") -> None:
self.state: TimeSyncDict = {
"ntp_servers": ["0.pool.ntp.org"],
"timezone": "UTC",
"synchronized": True,
"daemon": None,
}
self.keeps_zone_name = keeps_zone_name
self.fail = fail
self.calls: list[tuple[str, object]] = []
def get_time_sync(self) -> TimeSyncDict:
state = dict(self.state)
if not self.keeps_zone_name:
state["timezone"] = None
return state # type: ignore[return-value]
def _write_ntp_servers(self, servers):
self.calls.append(("ntp_servers", servers))
if self.fail == "ntp_servers":
return {"ok": False, "output": "refused"}
self.state["ntp_servers"] = list(servers)
return {"ok": True, "output": "written"}
def _write_time_zone(self, zone):
self.calls.append(("timezone", zone))
self.state["timezone"] = zone
return {"ok": True, "output": f"zone {zone}"}
class TestConfigureTimeSync:
def test_both_values_then_a_check(self):
device = _Device()
result = device.configure_time_sync(["ntp1.example.org", "10.0.0.1"], "Europe/Berlin")
assert result["success"] is True
assert [s["step"] for s in result["steps"]] == ["ntp_servers", "timezone", "verify"]
assert device.calls == [
("ntp_servers", ["ntp1.example.org", "10.0.0.1"]),
("timezone", "Europe/Berlin"),
]
def test_none_leaves_a_value_alone(self):
device = _Device()
result = device.configure_time_sync(timezone="Europe/Berlin")
assert result["success"] is True
assert device.calls == [("timezone", "Europe/Berlin")]
assert device.state["ntp_servers"] == ["0.pool.ntp.org"]
def test_servers_alone(self):
device = _Device()
assert device.configure_time_sync(["ntp1.example.org"])["success"] is True
assert device.calls == [("ntp_servers", ["ntp1.example.org"])]
def test_an_unknown_zone_is_refused_before_anything_is_written(self):
device = _Device()
with pytest.raises(UnknownTimezone, match="Mars/Olympus_Mons"):
device.configure_time_sync(["ntp1.example.org"], "Mars/Olympus_Mons")
assert device.calls == []
def test_a_posix_rule_is_not_a_zone_on_the_wire(self):
with pytest.raises(UnknownTimezone):
_Device().configure_time_sync(timezone="CET-1CEST,M3.5.0,M10.5.0/3")
def test_a_value_the_driver_cannot_write_is_refused_before_anything_is_written(self):
class Bmc(_Device):
time_sync_writes = frozenset({"ntp_servers"})
device = Bmc()
with pytest.raises(ValueError, match="timezone"):
device.configure_time_sync(["ntp1.example.org"], "Europe/Berlin")
assert device.calls == []
def test_a_driver_that_names_nothing_it_writes_writes_nothing(self):
class Silent(TimeSyncMixin):
"""Mixes the contract in and never says what it writes."""
with pytest.raises(ValueError, match="ntp_servers"):
Silent().configure_time_sync(["ntp1.example.org"])
def test_nothing_asked_is_a_mistake(self):
with pytest.raises(ValueError, match="nothing"):
_Device().configure_time_sync()
def test_a_failed_step_stops_the_rest(self):
device = _Device(fail="ntp_servers")
result = device.configure_time_sync(["ntp1.example.org"], "Europe/Berlin")
assert result["success"] is False
assert [s["step"] for s in result["steps"]] == ["ntp_servers"]
assert device.calls == [("ntp_servers", ["ntp1.example.org"])]
def test_the_check_reads_back_what_was_written(self):
class Stubborn(_Device):
def _write_ntp_servers(self, servers):
self.calls.append(("ntp_servers", servers))
return {"ok": True, "output": "written"} # and nothing changed
result = Stubborn().configure_time_sync(["ntp1.example.org"])
assert result["success"] is False
verify = result["steps"][-1]
assert verify["step"] == "verify"
assert "0.pool.ntp.org" in verify["output"]
def test_the_check_names_the_zone_the_device_kept(self):
class Elsewhere(_Device):
def _write_time_zone(self, zone):
return {"ok": True, "output": "set"} # and the device stayed on UTC
result = Elsewhere().configure_time_sync(timezone="Europe/Berlin")
assert result["success"] is False
assert result["steps"][-1]["output"] == "the device is in the time zone UTC"
def test_servers_compare_without_case(self):
class Lower(_Device):
def get_time_sync(self):
state = super().get_time_sync()
state["ntp_servers"] = [s.lower() for s in state["ntp_servers"]]
return state
assert Lower().configure_time_sync(["NTP1.Example.org"])["success"] is True
def test_a_device_without_a_zone_name_is_not_checked_for_one(self):
# A switch keeps an offset and a summer-time rule, not a name: it reads None.
result = _Device(keeps_zone_name=False).configure_time_sync(timezone="Europe/Berlin")
assert result["success"] is True
class TestCheckNtpServers:
def test_in_order_stripped_each_once(self):
assert check_ntp_servers([" ntp1.example.org", "10.0.0.1", "NTP1.example.org", "::1"]) == [
"ntp1.example.org",
"10.0.0.1",
"::1",
]
def test_none_at_all_is_refused(self):
# A device without a source drifts; leaving the value alone is None, not [].
with pytest.raises(ValueError, match="at least one"):
check_ntp_servers([])
with pytest.raises(ValueError, match="at least one"):
check_ntp_servers([" "])
@pytest.mark.parametrize(
"bad",
[
"ntp1.example.org iburst",
"-ntp.example.org",
"ntp1.example.org\nserver evil",
"ntp;reboot",
"$(id)",
"a" * 254,
],
)
def test_only_a_host_name_or_an_address(self, bad):
with pytest.raises(ValueError, match="not a host name or address"):
check_ntp_servers([bad])
def test_a_string_is_not_a_list_of_servers(self):
with pytest.raises(TypeError):
check_ntp_servers("ntp1.example.org") # type: ignore[arg-type]
+543
View File
@@ -0,0 +1,543 @@
"""Time sync on a POSIX host, over the command channel: chrony, systemd-timesyncd, timedatectl.
The reading is run by a real ``sh`` over a directory tree that stands in for the
host, with ``timedatectl``, ``systemctl`` and ``chronyc`` replaced by scripts that
keep a log -- so the shell itself is tested, not a hand-written copy of its output.
``sed`` and ``install`` are the real ones, so the files the writes leave are what a
host would get (NetOrk/netork#2361).
"""
from __future__ import annotations
import os
import subprocess
from pathlib import Path
import pytest
from napalm_device_types import PosixTimeSyncMixin, UnknownTimezone, parse_time_sync
from napalm_device_types.channel import CommandResult
from napalm_device_types.time_sync_posix import (
chrony_synchronized,
parse_key_values,
timesyncd_servers,
)
# What the tools print, as recorded.
TIMEDATECTL = """\
Timezone=Europe/Berlin
LocalRTC=no
CanNTP=yes
NTP=yes
NTPSynchronized=yes
TimeUSec=Wed 2026-11-11 14:23:16 CET
RTCTimeUSec=Wed 2026-11-11 13:23:16 CET
"""
#: Ubuntu 24.04 without any server configured: only the compiled-in fallback.
TIMESYNC_FALLBACK = """\
FallbackNTPServers=ntp.ubuntu.com
ServerName=ntp.ubuntu.com
ServerAddress=91.189.91.157
RootDistanceMaxUSec=5s
PollIntervalMinUSec=32s
PollIntervalMaxUSec=34min 8s
PollIntervalUSec=34min 8s
NTPMessage={ Leap=0, Version=4, Mode=4, Stratum=2, Precision=-24, RootDelay=42.190ms, RootDispersion=1.190ms, Reference=84A36001, Ignored=no, PacketCount=119, Jitter=7.481ms }
Frequency=455471
"""
TIMESYNC_CONFIGURED = """\
LinkNTPServers=192.168.1.1
SystemNTPServers=ntp1.example.org ntp2.example.org
FallbackNTPServers=0.debian.pool.ntp.org 1.debian.pool.ntp.org
ServerName=ntp1.example.org
"""
CHRONYC_SYNCED = """\
MS Name/IP address Stratum Poll Reach LastRx Last sample
===============================================================================
^- 162.159.200.123 3 6 377 41 +814us[ +814us] +/- 14ms
^* 192.168.1.1 2 6 377 40 -45us[ -63us] +/- 10ms
"""
CHRONYC_UNSYNCED = """\
MS Name/IP address Stratum Poll Reach LastRx Last sample
===============================================================================
^? 162.159.200.123 0 6 0 - +0ns[ +0ns] +/- 0ns
"""
#: Debian 12's chrony.conf, comments shortened, its directories under the test's root.
DEBIAN_CHRONY_CONF = """\
# Welcome to the chrony configuration file. See chrony.conf(5) for more
# information about usable directives.
# Include configuration files found in /etc/chrony/conf.d.
confdir {root}/etc/chrony/conf.d
# Use Debian vendor zone.
pool 2.debian.pool.ntp.org iburst
# Use time sources from DHCP.
sourcedir {root}/run/chrony-dhcp
# Use NTP sources found in /etc/chrony/sources.d.
sourcedir {root}/etc/chrony/sources.d
keyfile /etc/chrony/chrony.keys
driftfile /var/lib/chrony/chrony.drift
rtcsync
makestep 1 3
leapsectz right/UTC
"""
TIMEDATECTL_TOOL = """#!/bin/sh
echo "timedatectl $*" >> "$LOG"
case "$1" in
show) cat "$FIX/timedatectl" ;;
show-timesync) [ -f "$FIX/timesync" ] && cat "$FIX/timesync" ;;
set-timezone)
[ "$2" = "$REFUSE_ZONE" ] && { echo "Failed to set time zone: Invalid or not installed time zone '$2'" >&2; exit 1; }
sed -i "s#^Timezone=.*#Timezone=$2#" "$FIX/timedatectl" ;;
esac
"""
SYSTEMCTL_TOOL = """#!/bin/sh
echo "systemctl $*" >> "$LOG"
case "$1" in
is-active)
u=${2%.service}
case " $ACTIVE " in *" $u "*) echo active ;; *) echo inactive; exit 3 ;; esac ;;
restart)
[ -n "$FAIL_RESTART" ] && { echo "Job for $2 failed." >&2; exit 1; }
if [ "$2" = systemd-timesyncd.service ]; then
servers=$(sed -n 's/^NTP=\\(..*\\)$/\\1/p' "$DROPIN")
printf 'SystemNTPServers=%s\\n' "$servers" > "$FIX/timesync"
fi ;;
esac
"""
CHRONYC_TOOL = """#!/bin/sh
echo "chronyc $*" >> "$LOG"
case "$*" in
"-n sources") [ -f "$FIX/chronyc" ] && cat "$FIX/chronyc" ;;
"reload sources") exit "${RELOAD_EXIT:-0}" ;;
esac
"""
class Host(PosixTimeSyncMixin):
"""A host in a directory; every command is run by sh, root or not."""
def __init__(self, root: Path, *, active: str = "chrony") -> None:
self.root = root
etc = root / "etc"
self.CHRONY_CONFIGS = (str(etc / "chrony/chrony.conf"), str(etc / "chrony.conf")) # type: ignore[misc]
self.CHRONY_SOURCES_FILE = str(etc / "chrony/sources.d/netork.sources") # type: ignore[misc]
self.CHRONY_INCLUDE_FILE = str(etc / "chrony.d/netork.conf") # type: ignore[misc]
self.TIMESYNCD_DROPIN = str(etc / "systemd/timesyncd.conf.d/netork.conf") # type: ignore[misc]
self.NTPD_CONFIGS = (str(etc / "ntpsec/ntp.conf"), str(etc / "ntp.conf")) # type: ignore[misc]
self.OPENNTPD_CONFIGS = (str(etc / "openntpd/ntpd.conf"),) # type: ignore[misc]
self.TIME_ZONE_SH = ( # type: ignore[misc]
f"cat {etc}/timezone 2>/dev/null || readlink {etc}/localtime 2>/dev/null"
)
self.env = {
"PATH": f"{root / 'bin'}:{os.environ['PATH']}",
"LOG": str(root / "log"),
"FIX": str(root / "fix"),
"ACTIVE": active,
"DROPIN": self.TIMESYNCD_DROPIN,
}
self.commands: list[tuple[str, bool]] = []
def run_command(self, command, *, privileged=False, timeout=60, stdin=None): # type: ignore[no-untyped-def]
self.commands.append((command, privileged))
done = subprocess.run(
["sh", "-c", command],
input=stdin,
capture_output=True,
env={**os.environ, **self.env},
timeout=30,
)
return CommandResult(done.stdout.decode(), done.stderr.decode(), done.returncode)
def log(self) -> list[str]:
log = self.root / "log"
return log.read_text().splitlines() if log.exists() else []
def privileged(self) -> list[str]:
return [c for c, p in self.commands if p]
def _tool(root: Path, name: str, body: str) -> None:
path = root / "bin" / name
path.write_text(body)
path.chmod(0o755)
def _write(path: Path, text: str) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text)
@pytest.fixture
def root(tmp_path: Path) -> Path:
for d in ("bin", "fix", "etc"):
(tmp_path / d).mkdir()
(tmp_path / "fix/timedatectl").write_text(TIMEDATECTL)
for name, body in (
("timedatectl", TIMEDATECTL_TOOL),
("systemctl", SYSTEMCTL_TOOL),
("chronyc", CHRONYC_TOOL),
):
_tool(tmp_path, name, body)
return tmp_path
@pytest.fixture
def debian(root: Path) -> Path:
"""chrony as Debian 12 ships it, with a source in each place it reads."""
_write(root / "etc/chrony/chrony.conf", DEBIAN_CHRONY_CONF.format(root=root))
_write(root / "etc/chrony/conf.d/local.conf", "server ntp-conf.example.org iburst\n")
_write(root / "run/chrony-dhcp/eth0.sources", "server 192.168.1.1 iburst\n")
_write(root / "etc/chrony/sources.d/other.sources", "server ntp-other.example.org\n")
(root / "fix/chronyc").write_text(CHRONYC_SYNCED)
return root
def _no_timedatectl(root: Path) -> None:
"""A host without systemd: the command is not there (the build host's must not answer)."""
_tool(root, "timedatectl", '#!/bin/sh\necho "sh: timedatectl: not found" >&2\nexit 127\n')
def _text(path: Path) -> str:
return path.read_text()
class TestParsing:
def test_key_values(self):
values = parse_key_values(TIMEDATECTL)
assert values["Timezone"] == "Europe/Berlin"
assert values["NTPSynchronized"] == "yes"
def test_timesyncd_uses_the_fallback_only_when_nothing_else_is_known(self):
assert timesyncd_servers(parse_key_values(TIMESYNC_FALLBACK)) == ["ntp.ubuntu.com"]
# runtime, then system, then link: the order timesyncd tries them in.
assert timesyncd_servers(parse_key_values(TIMESYNC_CONFIGURED)) == [
"ntp1.example.org",
"ntp2.example.org",
"192.168.1.1",
]
assert timesyncd_servers({}) == []
def test_chrony_is_synchronised_while_it_has_selected_a_source(self):
assert chrony_synchronized(CHRONYC_SYNCED) is True
assert chrony_synchronized(CHRONYC_UNSYNCED) is False
assert chrony_synchronized("") is None
def test_chrony_without_a_main_configuration_has_no_sources(self):
assert parse_time_sync("@@ts active\nchrony chrony active\n@@ts end\n")["ntp_servers"] == []
def test_a_reading_cut_short_raises(self):
with pytest.raises(ValueError, match="cut short"):
parse_time_sync("@@ts timedatectl\nTimezone=UTC\n")
class TestReading:
def test_chrony_names_its_sources_in_the_order_it_reads_them(self, debian: Path):
host = Host(debian)
assert host.get_time_sync() == {
"ntp_servers": [
"ntp-conf.example.org",
"2.debian.pool.ntp.org",
"192.168.1.1",
"ntp-other.example.org",
],
"timezone": "Europe/Berlin",
"synchronized": True,
"daemon": "chrony",
}
def test_the_reading_is_one_round_trip_without_root(self, debian: Path):
host = Host(debian)
host.get_time_sync()
assert [p for _, p in host.commands] == [False]
def test_chrony_says_whether_it_is_synchronised_not_the_kernel(self, debian: Path):
(debian / "fix/chronyc").write_text(CHRONYC_UNSYNCED)
assert Host(debian).get_time_sync()["synchronized"] is False
def test_without_an_answer_from_chronyc_the_kernel_says(self, debian: Path):
(debian / "fix/chronyc").unlink()
assert Host(debian).get_time_sync()["synchronized"] is True
def test_commented_and_other_directives_are_no_sources(self, root: Path):
_write(
root / "etc/chrony.conf",
"#pool 2.rhel.pool.ntp.org iburst\n! server old.example.org\n"
" server ntp1.example.org iburst\nrefclock PPS /dev/pps0\npeer peer.example.org\n",
)
reading = Host(root, active="chronyd").get_time_sync()
assert reading["ntp_servers"] == ["ntp1.example.org", "peer.example.org"]
assert reading["daemon"] == "chrony"
def test_an_include_pattern_is_followed(self, root: Path):
_write(root / "etc/chrony.conf", f"include {root}/etc/chrony.d/*.conf\nmakestep 1 3\n")
_write(root / "etc/chrony.d/pool.conf", "pool suse.pool.ntp.org iburst\n")
assert Host(root).get_time_sync()["ntp_servers"] == ["suse.pool.ntp.org"]
def test_timesyncd(self, root: Path):
(root / "fix/timesync").write_text(TIMESYNC_CONFIGURED)
reading = Host(root, active="systemd-timesyncd").get_time_sync()
assert reading["daemon"] == "systemd-timesyncd"
assert reading["ntp_servers"] == ["ntp1.example.org", "ntp2.example.org", "192.168.1.1"]
assert reading["synchronized"] is True
def test_ntpd(self, root: Path):
_write(
root / "etc/ntpsec/ntp.conf",
"driftfile /var/lib/ntpsec/ntp.drift\npool 0.debian.pool.ntp.org iburst\n"
"server 127.127.1.0\nserver ntp1.example.org iburst\nrestrict default kod\n",
)
reading = Host(root, active="ntpsec").get_time_sync()
assert reading["daemon"] == "ntpd"
assert reading["ntp_servers"] == ["0.debian.pool.ntp.org", "ntp1.example.org"]
def test_openntpd(self, root: Path):
_write(
root / "etc/openntpd/ntpd.conf",
'servers pool.ntp.org\nserver ntp1.example.org\nconstraints from "https://www.google.com"\n',
)
reading = Host(root, active="openntpd").get_time_sync()
assert reading["daemon"] == "openntpd"
assert reading["ntp_servers"] == ["pool.ntp.org", "ntp1.example.org"]
def test_no_client_runs(self, root: Path):
(root / "fix/timedatectl").write_text(
TIMEDATECTL.replace("NTPSynchronized=yes", "NTPSynchronized=no")
)
assert Host(root, active="").get_time_sync() == {
"ntp_servers": [],
"timezone": "Europe/Berlin",
"synchronized": False,
"daemon": None,
}
def test_without_timedatectl_the_zone_comes_from_the_files(self, root: Path):
_no_timedatectl(root)
(root / "etc/localtime").symlink_to("/usr/share/zoneinfo/America/Sao_Paulo")
reading = Host(root, active="").get_time_sync()
assert reading["timezone"] == "America/Sao_Paulo"
assert reading["synchronized"] is None
def test_etc_timezone_wins_over_the_link(self, root: Path):
_no_timedatectl(root)
(root / "etc/timezone").write_text("Australia/Lord_Howe\n")
assert Host(root, active="").get_time_sync()["timezone"] == "Australia/Lord_Howe"
def test_a_copied_localtime_has_no_name(self, root: Path):
_no_timedatectl(root)
assert Host(root, active="").get_time_sync()["timezone"] is None
class TestChronyServers:
def test_exactly_these_servers(self, debian: Path):
host = Host(debian)
result = host.configure_time_sync(["ntp1.example.org", "10.0.0.1", "2.de.pool.ntp.org"])
assert result["success"] is True, result["output"]
assert _text(debian / "etc/chrony/sources.d/netork.sources") == (
"server ntp1.example.org iburst\nserver 10.0.0.1 iburst\npool 2.de.pool.ntp.org iburst\n"
)
conf = _text(debian / "etc/chrony/chrony.conf")
assert "\n#napalm-time-sync: pool 2.debian.pool.ntp.org iburst\n" in conf
assert f"\n#napalm-time-sync: sourcedir {debian}/run/chrony-dhcp\n" in conf
assert f"\nsourcedir {debian}/etc/chrony/sources.d\n" in conf
assert f"\nconfdir {debian}/etc/chrony/conf.d\n" in conf
assert _text(debian / "etc/chrony/conf.d/local.conf") == (
"#napalm-time-sync: server ntp-conf.example.org iburst\n"
)
assert _text(debian / "etc/chrony/sources.d/other.sources") == (
"#napalm-time-sync: server ntp-other.example.org\n"
)
# DHCP's own file is left alone: it is not read any more.
assert _text(debian / "run/chrony-dhcp/eth0.sources") == "server 192.168.1.1 iburst\n"
# The main configuration changed: chronyd reads it only when it starts.
assert "systemctl restart chrony.service" in host.log()
assert host.get_time_sync()["ntp_servers"] == [
"ntp1.example.org",
"10.0.0.1",
"2.de.pool.ntp.org",
]
def test_a_second_run_only_reloads_the_sources(self, debian: Path):
Host(debian).configure_time_sync(["ntp1.example.org"])
conf = _text(debian / "etc/chrony/chrony.conf")
(debian / "log").unlink()
host = Host(debian)
result = host.configure_time_sync(["ntp2.example.org", "ntp1.example.org"])
assert result["success"] is True, result["output"]
assert _text(debian / "etc/chrony/chrony.conf") == conf
assert "chronyc reload sources" in host.log()
assert not any(line.startswith("systemctl restart") for line in host.log())
assert _text(debian / "etc/chrony/sources.d/netork.sources") == (
"server ntp2.example.org iburst\nserver ntp1.example.org iburst\n"
)
def test_a_chronyd_that_cannot_reload_sources_is_restarted(self, debian: Path):
Host(debian).configure_time_sync(["ntp1.example.org"])
host = Host(debian)
host.env["RELOAD_EXIT"] = "1"
assert host.configure_time_sync(["ntp2.example.org"])["success"] is True
log = host.log()
reload = log.index("chronyc reload sources")
assert log[reload + 1] == "systemctl restart chrony.service"
def test_writes_are_root_s_and_root_reads_no_stdin(self, debian: Path):
host = Host(debian)
host.configure_time_sync(["ntp1.example.org"])
staged = [c for c, p in host.commands if not p and "mktemp" in c]
assert len(staged) == 1
assert host.privileged()
assert all("mktemp" not in c for c in host.privileged())
def test_rhel_without_a_directory_gets_an_include(self, root: Path):
_write(
root / "etc/chrony.conf",
"pool 2.rhel.pool.ntp.org iburst\ndriftfile /var/lib/chrony/drift\n",
)
host = Host(root, active="chronyd")
result = host.configure_time_sync(["ntp1.example.org"])
assert result["success"] is True, result["output"]
include = root / "etc/chrony.d/netork.conf"
assert _text(include) == "server ntp1.example.org iburst\n"
assert _text(root / "etc/chrony.conf") == (
"#napalm-time-sync: pool 2.rhel.pool.ntp.org iburst\n"
"driftfile /var/lib/chrony/drift\n"
f"# napalm-time-sync: the time sources\ninclude {include}\n"
)
assert "systemctl restart chronyd.service" in host.log()
def test_an_include_that_already_takes_the_file_is_used(self, root: Path):
_write(root / "etc/chrony.conf", f"include {root}/etc/chrony.d/*.conf\n")
_write(root / "etc/chrony.d/pool.conf", "pool suse.pool.ntp.org iburst\n")
host = Host(root)
assert host.configure_time_sync(["ntp1.example.org"])["success"] is True
assert _text(root / "etc/chrony.conf") == f"include {root}/etc/chrony.d/*.conf\n"
assert (
_text(root / "etc/chrony.d/pool.conf")
== "#napalm-time-sync: pool suse.pool.ntp.org iburst\n"
)
assert _text(root / "etc/chrony.d/netork.conf") == "server ntp1.example.org iburst\n"
def test_a_confdir_takes_the_file_where_sources_d_is_not_read(self, root: Path):
_write(
root / "etc/chrony/chrony.conf",
f"confdir {root}/etc/chrony/conf.d\npool a.pool.ntp.org\n",
)
host = Host(root)
assert host.configure_time_sync(["ntp1.example.org"])["success"] is True
assert _text(root / "etc/chrony/conf.d/netork.conf") == "server ntp1.example.org iburst\n"
assert not (root / "etc/chrony/sources.d/netork.sources").exists()
def test_a_failed_restart_fails_the_step(self, debian: Path):
host = Host(debian)
host.env["FAIL_RESTART"] = "1"
result = host.configure_time_sync(["ntp1.example.org"])
assert result["success"] is False
assert "Job for chrony.service failed." in result["steps"][0]["output"]
def test_a_file_that_cannot_be_staged_is_not_installed(self, debian: Path):
_tool(debian, "mktemp", "#!/bin/sh\necho 'mktemp: failed' >&2\nexit 1\n")
host = Host(debian)
result = host.configure_time_sync(["ntp1.example.org"])
assert result["success"] is False
assert "cannot stage" in result["steps"][0]["output"]
assert host.privileged() == []
def test_no_configuration_is_a_failed_step(self, root: Path):
result = Host(root).configure_time_sync(["ntp1.example.org"])
assert result["success"] is False
assert "chrony" in result["steps"][0]["output"]
class TestTimesyncdServers:
def test_a_drop_in_with_exactly_these_servers(self, root: Path):
(root / "fix/timesync").write_text(TIMESYNC_FALLBACK)
host = Host(root, active="systemd-timesyncd")
result = host.configure_time_sync(["ntp1.example.org", "10.0.0.1"])
assert result["success"] is True, result["output"]
assert _text(root / "etc/systemd/timesyncd.conf.d/netork.conf").endswith(
"[Time]\nNTP=\nNTP=ntp1.example.org 10.0.0.1\nFallbackNTP=\n"
)
assert "systemctl restart systemd-timesyncd.service" in host.log()
assert host.get_time_sync()["ntp_servers"] == ["ntp1.example.org", "10.0.0.1"]
def test_servers_from_dhcp_stay_and_the_check_says_so(self, root: Path):
(root / "fix/timesync").write_text(TIMESYNC_CONFIGURED)
tool = (root / "bin/systemctl").read_text()
(root / "bin/systemctl").write_text(
tool.replace(
"printf 'SystemNTPServers", "printf 'LinkNTPServers=192.168.1.1\\nSystemNTPServers"
)
)
result = Host(root, active="systemd-timesyncd").configure_time_sync(["ntp1.example.org"])
assert result["success"] is False
assert result["steps"][-1]["step"] == "verify"
assert "192.168.1.1" in result["steps"][-1]["output"]
class TestOtherClients:
@pytest.mark.parametrize("active", ["ntpsec", "openntpd", ""])
def test_only_chrony_and_timesyncd_are_written(self, root: Path, active: str):
host = Host(root, active=active)
result = host.configure_time_sync(["ntp1.example.org"])
assert result["success"] is False
assert "chrony and systemd-timesyncd" in result["steps"][0]["output"]
assert host.privileged() == []
class TestTimeZone:
def test_timedatectl_sets_it(self, root: Path):
host = Host(root, active="")
result = host.configure_time_sync(timezone="America/Sao_Paulo")
assert result["success"] is True, result["output"]
assert host.privileged() == ["timedatectl set-timezone America/Sao_Paulo"]
assert host.get_time_sync()["timezone"] == "America/Sao_Paulo"
def test_a_zone_the_host_does_not_know_fails_the_step(self, root: Path):
host = Host(root, active="")
host.env["REFUSE_ZONE"] = "Europe/Kyiv"
result = host.configure_time_sync(timezone="Europe/Kyiv")
assert result["success"] is False
assert "Invalid or not installed time zone" in result["steps"][0]["output"]
def test_an_unknown_zone_is_refused_before_anything_is_written(self, debian: Path):
host = Host(debian)
with pytest.raises(UnknownTimezone):
host.configure_time_sync(["ntp1.example.org"], "Mars/Olympus_Mons")
assert host.commands == []
def test_both_at_once(self, debian: Path):
host = Host(debian)
result = host.configure_time_sync(["ntp1.example.org"], "UTC")
assert result["success"] is True, result["output"]
assert [s["step"] for s in result["steps"]] == ["ntp_servers", "timezone", "verify"]
reading = host.get_time_sync()
assert (reading["ntp_servers"], reading["timezone"]) == (["ntp1.example.org"], "UTC")
def test_it_writes_both_values():
assert frozenset({"ntp_servers", "timezone"}) == PosixTimeSyncMixin.time_sync_writes