feat(time-sync): TimeSyncMixin, PosixTimeSyncMixin and the posix_tz helpers #103

Merged
christianmanivong merged 1 commits from feature/time-sync-2361 into main 2026-11-11 14:05:02 +00:00
Owner

Summary

  • TimeSyncMixin (napalm_device_types/time_sync.py), the contract of NetOrk/netork#2360: get_time_sync() -> TimeSyncDict (declared only: ntp_servers, timezone, synchronized, daemon), configure_time_sync(ntp_servers=None, timezone=None) -> FixResultDict as a fix template (steps ntp_servers, timezone, verify; None leaves a value alone; exactly these servers, in order), and time_sync_writes. An unknown zone, a malformed server, an empty list or a value outside time_sync_writes is refused before anything is written. TIME_SYNC_VALUES and check_ntp_servers are public.
  • PosixTimeSyncMixin over run_command: one reading as the login user (timedatectl show, the active client: chrony's configuration + chronyc -n sources, timedatectl show-timesync, ntpd, OpenNTPD); the zone by timedatectl set-timezone; chrony's servers in /etc/chrony/sources.d/netork.sources (else a confdir or an included /etc/chrony.d/netork.conf) with every other server/pool/peer line and foreign sourcedir 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) and a restart. ntpd and OpenNTPD are read, not written. Writes stage files as the login user; root reads no stdin.
  • napalm_device_types.posix_tz, moved from netOrk's core/posix_tz.py: posix_tz, is_iana_zone, is_posix_tz, UnknownTimezone (plain English), and parse_posix_tz -> PosixTzDict (UTC offset, summer-time offset and transitions) for switches. New dependency tzdata>=2024.1.
  • Release 4.35.0 in the same PR: napalm-linux and the other drivers of the epic implement it and need it on PyPI.

Related Issue

NetOrk/netork#2361 (part of NetOrk/netork#2360, time sync)

Testing

  • pytest (1596 passed, coverage 97 %), ruff format --check, ruff check, mypy, napalm-standard check and ratchet locally.
  • The new tests at the lowest dependency versions (uv --resolution lowest-direct, tzdata 2024.1): 106 passed.
  • The POSIX reading and writes are tested by a real sh over a directory tree with fake timedatectl, systemctl and chronyc (Debian, RHEL and SUSE chrony layouts, systemd-timesyncd, ntpd, OpenNTPD, no client).
  • napalm-linux, napalm-openmediavault and napalm-qnap-qts test suites pass against this branch.
## Summary - `TimeSyncMixin` (`napalm_device_types/time_sync.py`), the contract of NetOrk/netork#2360: `get_time_sync() -> TimeSyncDict` (declared only: `ntp_servers`, `timezone`, `synchronized`, `daemon`), `configure_time_sync(ntp_servers=None, timezone=None) -> FixResultDict` as a fix template (steps `ntp_servers`, `timezone`, `verify`; None leaves a value alone; exactly these servers, in order), and `time_sync_writes`. An unknown zone, a malformed server, an empty list or a value outside `time_sync_writes` is refused before anything is written. `TIME_SYNC_VALUES` and `check_ntp_servers` are public. - `PosixTimeSyncMixin` over `run_command`: one reading as the login user (`timedatectl show`, the active client: chrony's configuration + `chronyc -n sources`, `timedatectl show-timesync`, ntpd, OpenNTPD); the zone by `timedatectl set-timezone`; chrony's servers in `/etc/chrony/sources.d/netork.sources` (else a `confdir` or an included `/etc/chrony.d/netork.conf`) with every other `server`/`pool`/`peer` line and foreign `sourcedir` 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) and a restart. ntpd and OpenNTPD are read, not written. Writes stage files as the login user; root reads no stdin. - `napalm_device_types.posix_tz`, moved from netOrk's `core/posix_tz.py`: `posix_tz`, `is_iana_zone`, `is_posix_tz`, `UnknownTimezone` (plain English), and `parse_posix_tz` -> `PosixTzDict` (UTC offset, summer-time offset and transitions) for switches. New dependency `tzdata>=2024.1`. - Release 4.35.0 in the same PR: napalm-linux and the other drivers of the epic implement it and need it on PyPI. ## Related Issue NetOrk/netork#2361 (part of NetOrk/netork#2360, time sync) ## Testing - `pytest` (1596 passed, coverage 97 %), `ruff format --check`, `ruff check`, `mypy`, `napalm-standard check` and `ratchet` locally. - The new tests at the lowest dependency versions (`uv --resolution lowest-direct`, tzdata 2024.1): 106 passed. - The POSIX reading and writes are tested by a real `sh` over a directory tree with fake `timedatectl`, `systemctl` and `chronyc` (Debian, RHEL and SUSE chrony layouts, systemd-timesyncd, ntpd, OpenNTPD, no client). - napalm-linux, napalm-openmediavault and napalm-qnap-qts test suites pass against this branch.
christianmanivong added 1 commit 2026-11-11 13:33:16 +00:00
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
073087da69
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.
christianmanivong merged commit 6c7f164004 into main 2026-11-11 14:05:02 +00:00
christianmanivong deleted branch feature/time-sync-2361 2026-11-11 14:05:02 +00:00
Sign in to join this conversation.