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

Merged
christianmanivong merged 1 commits from feature/time-sync-2364 into main 2026-11-11 14:30:43 +00:00
Owner

What

OpenWrtDriver implements napalm-device-types 4.35.0's TimeSyncMixin in a new OpenWrtTimeSyncMixin (napalm_openwrt/time_sync_mixin.py). time_sync_writes is both values. Everything is in UCI's system config.

Reading is one uci -q show system as the login user, over an exec channel:

  • ntp_servers: the system.ntp.server list, every entry. An option holding servers separated by spaces is split, the way sysntpd splits it. A disabled client (system.ntp.enabled='0') reads as [], because sysntpd then starts no ntpd.
  • timezone: the rule in system.@system[0].timezone decides, because it is what libc reads as TZ (NetOrk/netork#1849). zonename is read as the zone only when that rule keeps the zone's time. LuCI's spaces become underscores again (America/New York → America/New_York). Rules are compared by their offsets and transitions, not their abbreviations, so the stock zonename='UTC' with timezone='GMT0' reads as UTC. A rule that is not the named zone's, or a rule with no name, reads as the one zone (from tzdata's Z lines, links not counted) that has that rule: IST-5:30 reads as Asia/Kolkata. Where several zones share the rule it reads as None (CET-1CEST,… is Berlin, Paris, Madrid, …), so the driver does not guess. The #1849 case (an IANA name as the rule) reads as None.
  • synchronized is None. BusyBox ntpd keeps no state another process can read, and ubus call system info has nothing on the clock source. daemon is None because the router runs its own client.

Writing runs as root (run_command(privileged=True)). OpenWrt has no sudo, so any other login is refused before anything runs. Each step reads first and writes nothing and restarts nothing when the router already has the value:

  • servers: uci delete system.ntp.server, then one uci add_list per server, enabled=1 and use_dhcp=0, uci commit system, /etc/init.d/sysntpd enable and restart. The ntp section is created if it is missing.
  • zone: zonename gets LuCI's spelling, so LuCI's zone list shows the zone as selected, and timezone gets posix_tz(zone). Then uci commit system, /etc/init.d/system reload (which writes /tmp/TZ) and /etc/init.d/log restart (logd reads the zone when it starts). These are the same commands netOrk's _uci_timezone and the system/ntp branch of _uci_builders.py send today.

get_ntp_servers() and get_ntp_peers() moved here from system_mixin.py. They now use the same reading as get_time_sync(), so the two always agree.

Floor: napalm_device_types>=4.35.0.

Why

NetOrk/netork#2360: netOrk aligns every device's time servers and zone, with automatic alignment on each poll as the default. For APs this replaces netOrk's own UCI builders for the AP profile's timezone / ntp_servers (NetOrk/netork#2364), which netOrk will delete.

Decisions

  • use_dhcp=0 on write. sysntpd adds the NTP servers from a DHCP lease to the configured list unless this is off. The contract says the device ends up with exactly the servers given, so a write turns it off. The read does not check it (the DHCP servers are not in UCI), so a router whose list already matches is not rewritten just to switch it off.
  • A disabled client reads as no servers. If it read as the configured list, netOrk would see an aligned router whose clock takes time from nothing. Reading [] makes netOrk align it, and the write enables the client. get_ntp_servers() follows, so netOrk derives no NTP checks for servers the router does not use.
  • Fixed on the way: get_ntp_servers() returned only the first server of a list, because uci prints a list as 'a' 'b' 'c' on one line.

Note for netOrk (#2362): when this driver reports timezone=None, the router runs on a rule that no single zone has, or on no valid rule at all (#1849). Aligning it once sets name and rule, and from then on it reads by name. So for this driver, treating None as "differs" is safe and does not churn. verify accepts None either way.

Tests

tests/unit/test_time_sync.py uses a fake uci behind run_command. It prints uci show system the way uci does, starting from the stock 23.05 config, the LuCI-configured AP fixture of netOrk#164, LuCI's spaced names and the #1849 config, and it applies the uci set/delete/add_list lines a write sends, so verify reads back what was written. The tests cover:

  • reading each of these configs;
  • the reverse rule lookup;
  • the command sequences;
  • idempotency: the same values twice give a single write, and the stock config written to UTC sends nothing;
  • a refused uci write restarts nothing;
  • a non-root login writes nothing;
  • get_ntp_servers() agrees with get_time_sync().

Not checked on a real router. 325 passed; the new module is at 100 % coverage. ruff, mypy, napalm-standard check and ratchet are clean.

Refs NetOrk/netork#2364

## What `OpenWrtDriver` implements napalm-device-types 4.35.0's `TimeSyncMixin` in a new `OpenWrtTimeSyncMixin` (`napalm_openwrt/time_sync_mixin.py`). `time_sync_writes` is both values. Everything is in UCI's `system` config. **Reading** is one `uci -q show system` as the login user, over an exec channel: - `ntp_servers`: the `system.ntp.server` list, every entry. An option holding servers separated by spaces is split, the way sysntpd splits it. A disabled client (`system.ntp.enabled='0'`) reads as `[]`, because sysntpd then starts no ntpd. - `timezone`: the rule in `system.@system[0].timezone` decides, because it is what libc reads as `TZ` (NetOrk/netork#1849). `zonename` is read as the zone only when that rule keeps the zone's time. LuCI's spaces become underscores again (`America/New York` → `America/New_York`). Rules are compared by their offsets and transitions, not their abbreviations, so the stock `zonename='UTC'` with `timezone='GMT0'` reads as `UTC`. A rule that is not the named zone's, or a rule with no name, reads as the one zone (from tzdata's `Z` lines, links not counted) that has that rule: `IST-5:30` reads as `Asia/Kolkata`. Where several zones share the rule it reads as `None` (`CET-1CEST,…` is Berlin, Paris, Madrid, …), so the driver does not guess. The #1849 case (an IANA name as the rule) reads as `None`. - `synchronized` is `None`. BusyBox ntpd keeps no state another process can read, and `ubus call system info` has nothing on the clock source. `daemon` is `None` because the router runs its own client. **Writing** runs as root (`run_command(privileged=True)`). OpenWrt has no sudo, so any other login is refused before anything runs. Each step reads first and **writes nothing and restarts nothing when the router already has the value**: - servers: `uci delete system.ntp.server`, then one `uci add_list` per server, `enabled=1` and `use_dhcp=0`, `uci commit system`, `/etc/init.d/sysntpd enable` and `restart`. The `ntp` section is created if it is missing. - zone: `zonename` gets LuCI's spelling, so LuCI's zone list shows the zone as selected, and `timezone` gets `posix_tz(zone)`. Then `uci commit system`, `/etc/init.d/system reload` (which writes `/tmp/TZ`) and `/etc/init.d/log restart` (logd reads the zone when it starts). These are the same commands netOrk's `_uci_timezone` and the `system/ntp` branch of `_uci_builders.py` send today. `get_ntp_servers()` and `get_ntp_peers()` moved here from `system_mixin.py`. They now use the same reading as `get_time_sync()`, so the two always agree. Floor: `napalm_device_types>=4.35.0`. ## Why NetOrk/netork#2360: netOrk aligns every device's time servers and zone, with automatic alignment on each poll as the default. For APs this replaces netOrk's own UCI builders for the AP profile's `timezone` / `ntp_servers` (NetOrk/netork#2364), which netOrk will delete. ## Decisions - **`use_dhcp=0` on write.** sysntpd adds the NTP servers from a DHCP lease to the configured list unless this is off. The contract says the device ends up with *exactly* the servers given, so a write turns it off. The read does not check it (the DHCP servers are not in UCI), so a router whose list already matches is not rewritten just to switch it off. - **A disabled client reads as no servers.** If it read as the configured list, netOrk would see an aligned router whose clock takes time from nothing. Reading `[]` makes netOrk align it, and the write enables the client. `get_ntp_servers()` follows, so netOrk derives no NTP checks for servers the router does not use. - **Fixed on the way:** `get_ntp_servers()` returned only the first server of a list, because uci prints a list as `'a' 'b' 'c'` on one line. Note for netOrk (#2362): when this driver reports `timezone=None`, the router runs on a rule that no single zone has, or on no valid rule at all (#1849). Aligning it once sets name and rule, and from then on it reads by name. So for this driver, treating `None` as "differs" is safe and does not churn. `verify` accepts `None` either way. ## Tests `tests/unit/test_time_sync.py` uses a fake `uci` behind `run_command`. It prints `uci show system` the way uci does, starting from the stock 23.05 config, the LuCI-configured AP fixture of netOrk#164, LuCI's spaced names and the #1849 config, and it applies the `uci set`/`delete`/`add_list` lines a write sends, so `verify` reads back what was written. The tests cover: - reading each of these configs; - the reverse rule lookup; - the command sequences; - idempotency: the same values twice give a single write, and the stock config written to `UTC` sends nothing; - a refused uci write restarts nothing; - a non-root login writes nothing; - `get_ntp_servers()` agrees with `get_time_sync()`. Not checked on a real router. 325 passed; the new module is at 100 % coverage. ruff, mypy, `napalm-standard check` and `ratchet` are clean. Refs NetOrk/netork#2364
christianmanivong added 1 commit 2026-11-11 14:23:21 +00:00
feat(time-sync): NTP servers and time zone through TimeSyncMixin
driver / standard (pull_request) Successful in 15s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 53s
driver / test (3.12) (pull_request) Successful in 58s
driver / test (3.13) (pull_request) Successful in 56s
driver / lowest (pull_request) Successful in 27s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Successful in 2m26s
driver / publish (pull_request) Skipped
7bb15f5af3
netOrk aligns every device's time sources and zone through the driver
(NetOrk/netork#2360); for APs that replaces the UCI commands netOrk
built itself for the AP profile fields (NetOrk/netork#2364).

Both values live in UCI's system config:
- The servers are system.ntp.server. A write replaces the list, enables
  the client, sets use_dhcp=0 so the servers of a DHCP lease are not
  added, and restarts sysntpd: the router ends up with exactly these.
  A disabled client reads as no servers.
- The zone is zonename (the IANA name, in LuCI's spelling with spaces)
  and timezone, the POSIX rule from posix_tz that libc reads as TZ. The
  rule is what counts (NetOrk/netork#1849), so the name is read as the
  zone only where the rule in force is that zone's; a rule alone reads
  as the one zone that has it, or None where several share it. A write
  sets both, reloads /etc/init.d/system and restarts logd, which reads
  the zone at start.

netOrk aligns on every poll, so each step compares first and writes
and restarts nothing when the router already has the values. GMT0 (the
stock rule) counts as UTC's time.

get_ntp_servers now uses the same reading, so it agrees with
get_time_sync; it used to keep only the first server of a list, as uci
prints a list as 'a' 'b' on one line. synchronized is None: BusyBox
ntpd keeps no state to read.

The floor on napalm-device-types is 4.35.0, the first with
TimeSyncMixin.
christianmanivong merged commit 836539d1fe into main 2026-11-11 14:30:43 +00:00
christianmanivong deleted branch feature/time-sync-2364 2026-11-11 14:30:43 +00:00
Sign in to join this conversation.