Files
Christian Manivong dc41b8497e
driver / lint (pull_request) Successful in 13s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Successful in 59s
driver / test (3.13) (pull_request) Successful in 52s
driver / test (3.12) (pull_request) Successful in 1m1s
driver / lowest (pull_request) Successful in 26s
driver / build (pull_request) Successful in 27s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Successful in 2m6s
driver / publish (pull_request) Skipped
feat(time-sync): the switch's NTP servers and zone through TimeSyncMixin
netOrk aligns every device's NTP servers and time zone with its site's
(NetOrk/netork#2360, #2366). A JetStream keeps both in one line,
system-time ntp <zone> <primary> <backup> <hours>, with the zone as a
UTC offset from a fixed list and summer time in a system-time dst line
of its own.

get_time_sync() reads the servers from that line and the zone as None:
the switch keeps no name to map back. configure_time_sync() writes an
IANA zone as its offset and a dst recurring rule from the zone's POSIX
rule (posix_tz/parse_posix_tz), and refuses before sending anything
what the switch cannot take: more than two servers, anything but IPv4
addresses, an offset it does not offer, a change outside HH:MM of a day.
Servers and zone share the ntp line, so a call with both writes it once.
A change is saved to the startup configuration; values the switch
already has are not sent again, so the alignment on every poll does not
churn.

The code lives in time_sync.py; get_ntp_servers() now reads through it,
so the driver file shrinks (1999 -> 1987 lines).
2026-11-11 15:17:51 +01:00

255 lines
10 KiB
Python

"""The switch's time sources and zone (napalm-device-types ``TimeSyncMixin``).
A JetStream keeps both in one line of its configuration (CLI reference guide,
"System Time Commands")::
system-time ntp <zone> <primary> <backup> <fetching-rate>
system-time dst recurring <week> <day> <month> <HH:MM> <week> <day> <month> <HH:MM> <minutes>
The zone is a UTC offset from the list the switch offers (``UTC+01:00``, ``UTC``),
the servers are two IPv4 addresses, the rate is in hours. Summer time is a line of
its own. The switch keeps no zone name, so ``timezone`` reads as None; an IANA name
is written as its offset and summer-time rule, from the zone's POSIX rule.
Writing the ``ntp`` line also switches the clock from manual time to NTP. Every
change is saved to the startup configuration, and nothing is sent when the switch
already has what is asked.
"""
from __future__ import annotations
import ipaddress
import re
from collections.abc import Sequence
from typing import TYPE_CHECKING, ClassVar, NamedTuple
from napalm_device_types import TimeSyncDict, TimeSyncMixin
from napalm_device_types.models import FixResultDict, FixStepOutcomeDict
from napalm_device_types.posix_tz import DstTransitionDict, parse_posix_tz, posix_tz
#: ``system-time ntp`` takes a primary and a backup server.
MAX_SERVERS = 2
#: Hours between two fetches when the switch had no ``ntp`` line yet (its default).
DEFAULT_FETCHING_RATE = 12
#: An empty backup server as the switch lists it.
_NO_SERVER = "0.0.0.0" # nosec B104 - a listed value, nothing binds to it
#: The offsets ``system-time ntp`` offers, in minutes east of UTC.
OFFERED_OFFSETS = frozenset(
[hours * 60 for hours in range(-12, 14)] + [-270, -210, 210, 270, 330, 345, 390, 570]
)
_DAYS = ("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat")
_MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
_ZONE = re.compile(r"UTC(?:([+-])(\d{1,2}):(\d{2}))?", re.I)
_NTP_LINE = re.compile(r"system-time\s+ntp\s+(\S+)\s+(.*)", re.I)
class NtpLine(NamedTuple):
"""The ``system-time ntp`` line: zone token, servers in order, fetching rate."""
zone: str
servers: list[str]
rate: int
def parse_ntp_line(running: str) -> NtpLine | None:
"""The ``system-time ntp`` line of *running*; None on manual time.
A server listed as primary and backup counts once, an empty backup not at all.
"""
for line in running.splitlines():
match = _NTP_LINE.fullmatch(line.strip())
if match is None:
continue
tokens = match.group(2).split()
rate = int(tokens[-1]) if tokens and tokens[-1].isdigit() else DEFAULT_FETCHING_RATE
servers: list[str] = []
for token in tokens:
if not token.isdigit() and token != _NO_SERVER and token not in servers:
servers.append(token)
return NtpLine(match.group(1), servers, rate)
return None
def _dst_line(running: str) -> str | None:
for line in running.splitlines():
if line.strip().lower().startswith("system-time dst"):
return " ".join(line.split())
return None
def _zone_minutes(token: str) -> int | None:
match = _ZONE.fullmatch(token)
if match is None:
return None
sign, hours, minutes = match.groups()
if sign is None:
return 0
return (1 if sign == "+" else -1) * (int(hours) * 60 + int(minutes))
def zone_token(utc_offset: int) -> str:
"""*utc_offset* (seconds east of UTC) as ``system-time ntp`` takes it.
:raises ValueError: for an offset the switch does not offer.
"""
minutes, rest = divmod(utc_offset, 60)
if rest or minutes not in OFFERED_OFFSETS:
raise ValueError(f"the switch does not offer the UTC offset {utc_offset / 3600:+g} h")
if minutes == 0:
return "UTC"
hours, mins = divmod(abs(minutes), 60)
return f"UTC{'+' if minutes > 0 else '-'}{hours:02d}:{mins:02d}"
def _when(transition: DstTransitionDict) -> str:
seconds = transition["time"]
if not 0 <= seconds < 86400 or seconds % 60:
raise ValueError("the switch takes a summer-time change at a time of day (HH:MM)")
clock = f"{seconds // 3600:02d}:{seconds % 3600 // 60:02d}"
weekday, month = _DAYS[transition["weekday"]], _MONTHS[transition["month"] - 1]
return f"{transition['week']} {weekday} {month} {clock}"
def dst_command(zone: str) -> tuple[str, str | None]:
"""*zone* as the switch keeps it: the zone token and the ``system-time dst`` line.
The line is None for a zone without summer time. A zone whose "summer" time is
behind its standard time (Europe/Dublin) is written the other way round: the
switch only puts the clock forward.
:raises ValueError: for a zone the switch cannot show.
"""
rule = posix_tz(zone)
parts = parse_posix_tz(rule) if rule else None
if parts is None:
raise ValueError(f"no summer-time rule the switch can take for {zone}")
std, summer = parts["utc_offset"], parts["dst_offset"]
start, end = parts["dst_start"], parts["dst_end"]
if summer is not None and summer < std:
std, summer, start, end = summer, std, end, start
token = zone_token(std)
if summer is None:
return token, None
if start is None or end is None:
raise ValueError(f"{zone} has summer time without a rule for it")
shift = (summer - std) // 60
return token, f"system-time dst recurring {_when(start)} {_when(end)} {shift}"
def _check_servers(servers: Sequence[str]) -> None:
if len(servers) > MAX_SERVERS:
raise ValueError(f"the switch takes at most {MAX_SERVERS} NTP servers, not {len(servers)}")
for server in servers:
try:
ipaddress.IPv4Address(server)
except ValueError:
raise ValueError(
f"the switch takes NTP servers as IPv4 addresses only, not {server!r}"
) from None
def _ntp_command(zone: str, servers: Sequence[str], rate: int) -> str:
backup = servers[1] if len(servers) > 1 else servers[0]
return f"system-time ntp {zone} {servers[0]} {backup} {rate}"
class JetstreamTimeSyncMixin(TimeSyncMixin):
"""``get_time_sync`` and ``configure_time_sync`` over the switch's CLI."""
time_sync_writes: ClassVar[frozenset[str]] = frozenset({"ntp_servers", "timezone"})
#: The zone a running configure_time_sync was asked for: its servers step
#: writes the ``ntp`` line with that zone's offset already.
_zone_asked: str | None = None
if TYPE_CHECKING: # pragma: no cover - the driver's own helpers
def _send_command(self, command: str | list[str]) -> str: ...
def _enter_config_mode(self) -> None: ...
def _exit_config_mode(self) -> None: ...
def _apply_config_lines(self, config_text: str) -> list[str]: ...
def _save_config(self) -> None: ...
def get_time_sync(self) -> TimeSyncDict:
"""The servers of the ``system-time ntp`` line; no zone name, no sync state.
The switch shows neither whether its last fetch worked nor a zone name.
"""
line = parse_ntp_line(self._send_command("show running-config"))
return {
"ntp_servers": line.servers if line else [],
"timezone": None,
"synchronized": None,
"daemon": None,
}
def configure_time_sync(
self, ntp_servers: Sequence[str] | None = None, timezone: str | None = None
) -> FixResultDict:
"""The template's steps; servers and zone share one ``ntp`` line."""
self._zone_asked = timezone
try:
return TimeSyncMixin.configure_time_sync(self, ntp_servers, timezone)
finally:
self._zone_asked = None
def _write_ntp_servers(self, servers: list[str]) -> FixStepOutcomeDict:
_check_servers(servers)
line = parse_ntp_line(self._send_command("show running-config"))
if self._zone_asked is not None:
zone = dst_command(self._zone_asked)[0]
else:
zone = line.zone if line else "UTC"
if line and _same_zone(line.zone, zone) and _same(line.servers, servers):
return {"ok": True, "output": "the switch already has these servers"}
rate = line.rate if line else DEFAULT_FETCHING_RATE
self._apply_time_commands([_ntp_command(zone, servers, rate)])
return {"ok": True, "output": f"NTP servers set: {', '.join(servers)}"}
def _write_time_zone(self, zone: str) -> FixStepOutcomeDict:
token, dst = dst_command(zone)
running = self._send_command("show running-config")
line = parse_ntp_line(running)
if line is None:
raise ValueError(
"the switch keeps its time zone with its NTP servers and has none:"
" name the NTP servers too"
)
commands = (
[] if _same_zone(line.zone, token) else [_ntp_command(token, line.servers, line.rate)]
)
current = _dst_line(running)
if dst is None and current is not None:
commands.append("no system-time dst")
elif dst is not None and (current or "").lower() != dst.lower():
commands.append(dst)
if not commands:
return {"ok": True, "output": f"the switch is already in {zone}"}
self._apply_time_commands(commands)
return {"ok": True, "output": f"time zone set: {token}, " + (dst or "no summer time")}
def _apply_time_commands(self, commands: list[str]) -> None:
"""Send *commands* in ``configure`` and save them; raise on a refused one."""
self._enter_config_mode()
try:
errors = self._apply_config_lines("\n".join(commands))
finally:
self._exit_config_mode()
if errors:
raise RuntimeError("the switch refused:\n" + "\n".join(errors))
self._save_config()
def _same(have: Sequence[str], want: Sequence[str]) -> bool:
return [s.lower() for s in have] == [s.lower() for s in want]
def _same_zone(have: str, want: str) -> bool:
minutes = _zone_minutes(have)
return minutes is not None and minutes == _zone_minutes(want)
__all__ = ["JetstreamTimeSyncMixin", "NtpLine", "dst_command", "parse_ntp_line", "zone_token"]