diff --git a/CHANGELOG.md b/CHANGELOG.md index 824fd6b..21c21a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,33 @@ 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 diff --git a/README.md b/README.md index 45181c5..ae3d2ce 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index d6555f6..cce669d 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -65,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` @@ -222,6 +224,15 @@ 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 @@ -308,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, @@ -479,6 +497,19 @@ __all__ = [ "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", diff --git a/napalm_device_types/_chrony.py b/napalm_device_types/_chrony.py new file mode 100644 index 0000000..7de1e5c --- /dev/null +++ b/napalm_device_types/_chrony.py @@ -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)}" + ) diff --git a/napalm_device_types/_time_sync_reading.py b/napalm_device_types/_time_sync_reading.py new file mode 100644 index 0000000..7f81acd --- /dev/null +++ b/napalm_device_types/_time_sync_reading.py @@ -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 ...``): + +* ``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 `` `` line per time sync service; +* ``timesync`` -- ``timedatectl show-timesync``: systemd-timesyncd's servers; +* ``chronyc`` -- ``chronyc -n sources``: whether chronyd has selected a source; +* ``chrony `` -- chrony's main configuration (line 0, kind + ``main``), then each file an ``include``, ``confdir`` or ``sourcedir`` on that + line of it reads; +* ``ntpd ``, ``openntpd `` -- 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 " + +#: `` ``: 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)) diff --git a/napalm_device_types/posix_tz.py b/napalm_device_types/posix_tz.py new file mode 100644 index 0000000..43cc37f --- /dev/null +++ b/napalm_device_types/posix_tz.py @@ -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{_ABBR})(?P{_OFFSET})" + rf"(?:(?P{_ABBR})(?P{_OFFSET})?" + r"(?:,(?P[^,]+),(?P[^,]+))?)?" +) +_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", +] diff --git a/napalm_device_types/time_sync.py b/napalm_device_types/time_sync.py new file mode 100644 index 0000000..a37a3ad --- /dev/null +++ b/napalm_device_types/time_sync.py @@ -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"] diff --git a/napalm_device_types/time_sync_posix.py b/napalm_device_types/time_sync_posix.py new file mode 100644 index 0000000..f89539c --- /dev/null +++ b/napalm_device_types/time_sync_posix.py @@ -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", +] diff --git a/pyproject.toml b/pyproject.toml index 02a6ee3..0f7fa07 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "napalm-device-types" -version = "4.34.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] diff --git a/tests/test_posix_tz.py b/tests/test_posix_tz.py new file mode 100644 index 0000000..bfff076 --- /dev/null +++ b/tests/test_posix_tz.py @@ -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 == [] diff --git a/tests/test_time_sync.py b/tests/test_time_sync.py new file mode 100644 index 0000000..ffeabed --- /dev/null +++ b/tests/test_time_sync.py @@ -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] diff --git a/tests/test_time_sync_posix.py b/tests/test_time_sync_posix.py new file mode 100644 index 0000000..5d828e1 --- /dev/null +++ b/tests/test_time_sync_posix.py @@ -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