feat(time-sync): read the time servers and zone of config.xml (NetOrk/netork#2363) #47

Merged
christianmanivong merged 1 commits from feature/time-sync-2363 into main 2026-11-11 14:29:06 +00:00
Owner

What

The driver implements napalm-device-types 4.35.0's TimeSyncMixin as a read only (napalm_opnsense/time_sync.py, OPNsenseTimeSyncMixin):

  • get_time_sync(): ntp_servers from config.xml <system><timeservers> (space-separated, in the order of Services → Network Time → General), timezone from <system><timezone> (an IANA name; empty or missing reads as Etc/UTC, which system_timezone_configure() puts in place then), synchronized from /api/ntpd/service/status (a row with status *, the system peer), daemon "ntpd".
    • config.xml comes from GET /api/core/backup/download/this, the download get_config() already uses. A failed or non-XML read raises.
    • Without time servers OPNsense does not run ntpd (ntpd_enabled()), so synchronized is False and the status is not asked; a failed status read is None and keeps the rest of the reading.
  • time_sync_writes = frozenset() and configure_time_sync = None, so callable(getattr(driver, "configure_time_sync", None)) is truthfully False.
  • TIME_SERVERS_MENU = ("Services", "Network Time", "General") and TIME_ZONE_MENU = ("System", "Settings", "General"), as data, like SSH_SETTINGS_MENU for the SSH algorithms.
  • get_ntp_servers() moves into the mixin and returns the same configured list. It read a peers field /api/ntpd/service/status does not have (the endpoint answers with ntpq's associations as rows, resolved addresses, not the configured names), so it never found a server. A failed read now raises instead of reading as "no servers".

Why it writes nothing (NetOrk/netork#2363)

  • Both values live on legacy PHP pages: services_ntpd.php (servers, plus ntpd.prefer/iburst/ispool/noselect per server) and system_general.php (zone). No MVC model or API controller reads or writes system.timeservers or system.timezone, on stable/26.7 or master (checked in opnsense/core today). /api/ntpd/service/* only has meta, gps and status.
  • The only API that writes the zone is the initial setup wizard (/api/core/initial_setup/configure), which writes hostname, domain, DNS, the WAN/LAN interfaces and the root password together. Restoring an edited config.xml through the backup API would replace the whole configuration. Neither is safe on a box that is often the gateway and its LAN's time server, so both are left out. The driver is API-only (USES_SSH = False), so there is no configctl path either.
  • Not writing also means nothing here can stop ntpd or change which interfaces it serves time on.
  • In an HA pair the "Network Time" sync item (ntpd, section ntpd,system.timeservers) carries the servers to the backup; the zone is not synced.

So on OPNsense a differing server list or zone stays a warning that names the page; netOrk's automatic alignment cannot act on it.

opnsense.py shrinks by 20 lines (baseline 3055 → 3035). The dependency floor is now napalm-device-types>=4.35.0. CHANGELOG under Unreleased; the version bump is left to the release commit, as for every feature here.

Tests

Fixtures only, nothing run on a device. tests/unit/test_time_sync.py (26 tests), written first and red until the mixin existed:

  • config_xml_sample.xml is OPNsense's own src/etc/config.xml.sample (core master) without the default root user; variants change the servers, the zone, or drop an element.
  • ntpd_service_status.json is /api/ntpd/service/status in its 26.7 shape (ntpq -pnw rows, pool associations __pool, system peer *).
  • They go through the real session path (session.get), and check the reading only GETs and never POSTs.

The old TestGetNtpServers (on the non-existent peers shape) is replaced. Full suite green (573), coverage 85 % (time_sync.py 100 %), ruff, mypy (the new module under strict), bandit, napalm-standard check and ratchet.

Refs NetOrk/netork#2363

## What The driver implements napalm-device-types 4.35.0's `TimeSyncMixin` as a **read only** (`napalm_opnsense/time_sync.py`, `OPNsenseTimeSyncMixin`): - `get_time_sync()`: `ntp_servers` from config.xml `<system><timeservers>` (space-separated, in the order of *Services → Network Time → General*), `timezone` from `<system><timezone>` (an IANA name; empty or missing reads as `Etc/UTC`, which `system_timezone_configure()` puts in place then), `synchronized` from `/api/ntpd/service/status` (a row with status `*`, the system peer), `daemon` `"ntpd"`. - config.xml comes from `GET /api/core/backup/download/this`, the download `get_config()` already uses. A failed or non-XML read raises. - Without time servers OPNsense does not run ntpd (`ntpd_enabled()`), so `synchronized` is `False` and the status is not asked; a failed status read is `None` and keeps the rest of the reading. - `time_sync_writes = frozenset()` and `configure_time_sync = None`, so `callable(getattr(driver, "configure_time_sync", None))` is truthfully False. - `TIME_SERVERS_MENU = ("Services", "Network Time", "General")` and `TIME_ZONE_MENU = ("System", "Settings", "General")`, as data, like `SSH_SETTINGS_MENU` for the SSH algorithms. - `get_ntp_servers()` moves into the mixin and returns the same configured list. It read a `peers` field `/api/ntpd/service/status` does not have (the endpoint answers with ntpq's associations as `rows`, resolved addresses, not the configured names), so it never found a server. A failed read now raises instead of reading as "no servers". ## Why it writes nothing (NetOrk/netork#2363) - Both values live on legacy PHP pages: `services_ntpd.php` (servers, plus `ntpd.prefer/iburst/ispool/noselect` per server) and `system_general.php` (zone). No MVC model or API controller reads or writes `system.timeservers` or `system.timezone`, on `stable/26.7` or `master` (checked in opnsense/core today). `/api/ntpd/service/*` only has `meta`, `gps` and `status`. - The only API that writes the zone is the initial setup wizard (`/api/core/initial_setup/configure`), which writes hostname, domain, DNS, the WAN/LAN interfaces and the root password together. Restoring an edited config.xml through the backup API would replace the whole configuration. Neither is safe on a box that is often the gateway and its LAN's time server, so both are left out. The driver is API-only (`USES_SSH = False`), so there is no `configctl` path either. - Not writing also means nothing here can stop ntpd or change which interfaces it serves time on. - In an HA pair the "Network Time" sync item (`ntpd`, section `ntpd,system.timeservers`) carries the servers to the backup; the zone is not synced. So on OPNsense a differing server list or zone stays a warning that names the page; netOrk's automatic alignment cannot act on it. `opnsense.py` shrinks by 20 lines (baseline 3055 → 3035). The dependency floor is now `napalm-device-types>=4.35.0`. CHANGELOG under *Unreleased*; the version bump is left to the release commit, as for every feature here. ## Tests Fixtures only, nothing run on a device. `tests/unit/test_time_sync.py` (26 tests), written first and red until the mixin existed: - `config_xml_sample.xml` is OPNsense's own `src/etc/config.xml.sample` (core `master`) without the default root user; variants change the servers, the zone, or drop an element. - `ntpd_service_status.json` is `/api/ntpd/service/status` in its 26.7 shape (`ntpq -pnw` rows, pool associations `__pool`, system peer `*`). - They go through the real session path (`session.get`), and check the reading only GETs and never POSTs. The old `TestGetNtpServers` (on the non-existent `peers` shape) is replaced. Full suite green (573), coverage 85 % (`time_sync.py` 100 %), ruff, mypy (the new module under strict), bandit, `napalm-standard check` and `ratchet`. Refs NetOrk/netork#2363
christianmanivong added 1 commit 2026-11-11 14:21:12 +00:00
feat(time-sync): read the time servers and zone of config.xml (NetOrk/netork#2363)
driver / standard (pull_request) Successful in 17s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 1m1s
driver / test (3.12) (pull_request) Successful in 1m9s
driver / test (3.13) (pull_request) Successful in 1m3s
driver / lowest (pull_request) Successful in 36s
driver / build (pull_request) Successful in 27s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Successful in 2m33s
driver / publish (pull_request) Skipped
6fdc3ff2c7
netOrk aligns every device with one list of time servers and a zone per
site (NetOrk/netork#2360) through napalm-device-types 4.35.0's
TimeSyncMixin. OPNsense keeps both in config.xml, <system><timeservers>
and <system><timezone>, set on the legacy pages services_ntpd.php and
system_general.php. No API controller reads or writes them, on 26.7 and
on master, so get_time_sync() reads them from the configuration download
get_config already uses and asks /api/ntpd/service/status whether ntpd
follows a system peer.

The driver writes neither value: time_sync_writes is empty and
configure_time_sync is None. Restoring an edited config.xml or running
the initial setup wizard would rewrite far more than the clock, on a box
that is often the gateway and its LAN's time server. TIME_SERVERS_MENU
and TIME_ZONE_MENU say where a person sets them, as SSH_SETTINGS_MENU
does for the SSH algorithms.

get_ntp_servers() now returns the same configured list. It read a
"peers" field the status endpoint does not have (it answers with ntpq's
associations as "rows") and so never found a server.
christianmanivong merged commit 9d7cb64dac into main 2026-11-11 14:29:06 +00:00
christianmanivong deleted branch feature/time-sync-2363 2026-11-11 14:29:06 +00:00
Sign in to join this conversation.