driver / lint (pull_request) Successful in 15s
driver / standard (pull_request) Successful in 17s
driver / types (pull_request) Successful in 56s
driver / test (3.13) (pull_request) Successful in 57s
driver / test (3.12) (pull_request) Successful in 1m3s
driver / lowest (pull_request) Successful in 28s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 1m4s
CI / driver (pull_request) Successful in 2m19s
driver / publish (pull_request) Skipped
291 lines
12 KiB
Python
291 lines
12 KiB
Python
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""The firmware OpenWrt's attended sysupgrade server offers, and installing it with owut.
|
|
|
|
A package upgrade on OpenWrt writes the whole new package to the overlay, while
|
|
the old one stays in the read-only image: every upgrade costs flash, and the
|
|
overlay only fills. A sysupgrade to the next release of the device's own line
|
|
brings those packages in the new image, together with every package installed
|
|
since, so the overlay is left with little more than the configuration
|
|
(NetOrk/netork#2615).
|
|
|
|
**The offer** (napalm-device-types ``FirmwareOfferMixin``) comes from the
|
|
sysupgrade server's ``/json/v1/overview.json``: every release line, its
|
|
versions and the targets it builds. One file serves every device, so it is
|
|
fetched by the worker, at most once a day per server and process
|
|
(:data:`_FRESH_FOR`); a server that did not answer is not asked again for an
|
|
hour. The server is the one the device is set to
|
|
(``attendedsysupgrade.@server[0].url``, which owut and LuCI use), or the public
|
|
one. ``latest_version`` is the newest release of the device's own line
|
|
(25.12.2 → 25.12.6), release candidates only where the line has no release; a
|
|
later line is named in ``latest_major_version`` and never offered as the
|
|
upgrade. A snapshot, or a target the line no longer builds, has no offer.
|
|
|
|
**Installing** (``FirmwareUpgradeMixin``) is owut's ``upgrade``: it collects the
|
|
installed packages, has the server build an image with them, checks it and runs
|
|
sysupgrade, which keeps the configuration and restarts the device. owut exists
|
|
from 24.10 on; ``installable`` says whether it is installed, and is left out on
|
|
an older release. It runs detached from the session, ignoring its hang-up, and
|
|
writes to :data:`_LOG`; ``get_update_progress`` reads that log. owut prints
|
|
:data:`_INSTALLING` right before sysupgrade stops every process, the wrapper's
|
|
status line included, so that line is the upgrade's end.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import re
|
|
import time
|
|
import urllib.request
|
|
from typing import TYPE_CHECKING, Any, Final
|
|
|
|
from napalm_device_types import (
|
|
FirmwareOfferDict,
|
|
FirmwareOfferMixin,
|
|
FirmwareUpgradeMixin,
|
|
UpdateProgressDict,
|
|
)
|
|
|
|
if TYPE_CHECKING:
|
|
from napalm_device_types import CommandResult
|
|
|
|
#: The public sysupgrade server, owut's default.
|
|
DEFAULT_SERVER: Final = "https://sysupgrade.openwrt.org"
|
|
_OVERVIEW_PATH: Final = "/json/v1/overview.json"
|
|
#: Seconds an answer is used before the server is asked again.
|
|
_FRESH_FOR: Final = 24 * 3600
|
|
#: Seconds a failed fetch is remembered, so a server that is down is not asked per device.
|
|
_RETRY_AFTER: Final = 3600
|
|
_FETCH_TIMEOUT: Final = 15
|
|
#: overview.json is about 20 KB; anything far larger is not it.
|
|
_MAX_BYTES: Final = 2 * 1024 * 1024
|
|
|
|
#: Per server URL: (monotonic time fetched, overview or None for a failed fetch).
|
|
_OVERVIEWS: dict[str, tuple[float, dict[str, Any] | None]] = {}
|
|
|
|
# On the device, not here: its /tmp is RAM, where owut keeps its image too.
|
|
_LOG: Final = "/tmp/owut-upgrade.log" # nosec B108
|
|
_PID: Final = "/tmp/owut-upgrade.pid" # nosec B108
|
|
_STATUS: Final = "__OWUT_RC="
|
|
_STATUS_RE: Final = re.compile(rf"^{_STATUS}(\d+)\s*$", re.MULTILINE)
|
|
#: What owut prints right before it hands the image to sysupgrade.
|
|
_INSTALLING: Final = re.compile(r"^Installing \S+ and rebooting", re.MULTILINE)
|
|
#: A release, or a release candidate: 25.12.6, 25.12.0-rc5.
|
|
_VERSION: Final = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:-rc(\d+))?$")
|
|
#: The first release line owut exists for.
|
|
_OWUT_SINCE: Final = (24, 10)
|
|
|
|
#: One round trip as the login user: the release, the server it is set to, owut.
|
|
_READ_DEVICE: Final = (
|
|
"cat /etc/openwrt_release; "
|
|
'echo "__ASU_URL=$(uci -q get attendedsysupgrade.@server[0].url)"; '
|
|
"command -v owut >/dev/null 2>&1 && echo __OWUT=1; :"
|
|
)
|
|
_LOG_COMMAND: Final = f"cat {_LOG}"
|
|
|
|
|
|
def _start_command(version: str) -> str:
|
|
"""owut's upgrade, detached and deaf to the session's hang-up; refused while one runs."""
|
|
return (
|
|
f'if [ -f {_PID} ] && kill -0 "$(cat {_PID})" 2>/dev/null; then '
|
|
"echo 'an upgrade is already running' >&2; exit 3; fi; "
|
|
"command -v owut >/dev/null 2>&1 || { echo 'owut is not installed' >&2; exit 4; }; "
|
|
f"rm -f {_LOG}; "
|
|
f'sh -c \'echo $$ > {_PID}; trap "" HUP; owut upgrade --version-to {version}; '
|
|
f"echo {_STATUS}$?' </dev/null >{_LOG} 2>&1 &"
|
|
)
|
|
|
|
|
|
def _version_key(version: str) -> tuple[int, int, int, float] | None:
|
|
"""Sortable: a release candidate before its release; None for anything else."""
|
|
match = _VERSION.match(version)
|
|
if match is None:
|
|
return None
|
|
major, minor, patch, rc = match.groups()
|
|
return int(major), int(minor), int(patch), float(rc) if rc else float("inf")
|
|
|
|
|
|
def _line_of(version: str) -> str:
|
|
"""``25.12`` of ``25.12.2``: the release line, as the server names it."""
|
|
return ".".join(version.split(".")[:2])
|
|
|
|
|
|
def _newest(versions: list[str]) -> str | None:
|
|
"""The newest release; a release candidate only where the line has no release."""
|
|
keyed = [(key, v) for v in versions if (key := _version_key(v)) is not None]
|
|
releases = [(key, v) for key, v in keyed if key[3] == float("inf")]
|
|
pool = releases or keyed
|
|
return max(pool)[1] if pool else None
|
|
|
|
|
|
def _builds(branch: dict[str, Any], target: str) -> bool:
|
|
return (
|
|
bool(branch.get("enabled"))
|
|
and not branch.get("snapshot")
|
|
and target in (branch.get("targets") or [])
|
|
)
|
|
|
|
|
|
def _fetch_json(url: str) -> dict[str, Any]:
|
|
"""GET *url* as JSON; raises on any failure."""
|
|
request = urllib.request.Request(url, headers={"User-Agent": "napalm-openwrt"})
|
|
# http(s) only: _server_url gives nothing else.
|
|
with urllib.request.urlopen(request, timeout=_FETCH_TIMEOUT) as response: # noqa: S310 # nosec B310
|
|
data = json.loads(response.read(_MAX_BYTES))
|
|
if not isinstance(data, dict):
|
|
raise ValueError("overview.json is not an object")
|
|
return data
|
|
|
|
|
|
def _overview(server: str) -> dict[str, Any] | None:
|
|
"""The server's overview, from the cache while it is fresh; None when it did not answer."""
|
|
url = server + _OVERVIEW_PATH
|
|
now = time.monotonic()
|
|
cached = _OVERVIEWS.get(url)
|
|
if cached is not None:
|
|
fetched_at, data = cached
|
|
if now - fetched_at < (_FRESH_FOR if data is not None else _RETRY_AFTER):
|
|
return data
|
|
fetched: dict[str, Any] | None
|
|
try:
|
|
fetched = _fetch_json(url)
|
|
except Exception:
|
|
fetched = None
|
|
_OVERVIEWS[url] = (now, fetched)
|
|
return fetched
|
|
|
|
|
|
def _server_url(configured: str) -> str:
|
|
"""The server the device is set to, if it is an http(s) URL; else the public one."""
|
|
url = configured.strip().rstrip("/")
|
|
return url if re.match(r"^https?://[^\s/]+", url) else DEFAULT_SERVER
|
|
|
|
|
|
def _later_line(overview: dict[str, Any], line: str, target: str) -> str | None:
|
|
"""The newest release of the newest later line that builds *target*."""
|
|
current = _version_key(line + ".0")
|
|
if current is None:
|
|
return None
|
|
later = [
|
|
(key, str(name))
|
|
for name in overview.get("branches") or {}
|
|
if (key := _version_key(f"{name}.0")) is not None and key[:2] > current[:2]
|
|
]
|
|
for _key, name in sorted(later, reverse=True):
|
|
newest = _latest_of_line(overview, name, target)
|
|
if newest is not None:
|
|
return newest
|
|
return None
|
|
|
|
|
|
def _latest_of_line(overview: dict[str, Any], line: str, target: str) -> str | None:
|
|
"""The newest release of *line*, if the line builds *target*."""
|
|
branch = (overview.get("branches") or {}).get(line)
|
|
if not isinstance(branch, dict) or not _builds(branch, target):
|
|
return None
|
|
return _newest(list(branch.get("versions") or []))
|
|
|
|
|
|
def _offer(
|
|
overview: dict[str, Any], current: str, target: str, owut: bool
|
|
) -> FirmwareOfferDict | None:
|
|
"""The offer for a device on release *current* (a release, see ``_VERSION``)."""
|
|
line = _line_of(current)
|
|
latest = _latest_of_line(overview, line, target)
|
|
key, latest_key = _version_key(current), _version_key(latest or "")
|
|
if key is None or latest is None or latest_key is None:
|
|
return None
|
|
offer: FirmwareOfferDict = {
|
|
"current_version": current,
|
|
"latest_version": latest,
|
|
"newer": latest_key > key,
|
|
}
|
|
if key[:2] >= _OWUT_SINCE:
|
|
offer["installable"] = owut
|
|
later = _later_line(overview, line, target)
|
|
if later is not None:
|
|
offer["latest_major_version"] = later
|
|
return offer
|
|
|
|
|
|
class OpenWrtFirmwareMixin(FirmwareOfferMixin, FirmwareUpgradeMixin):
|
|
"""``get_firmware_offer``, ``start_firmware_upgrade`` and ``get_update_progress``."""
|
|
|
|
if TYPE_CHECKING: # pragma: no cover - the driver's
|
|
|
|
def run_command(
|
|
self,
|
|
command: str,
|
|
*,
|
|
privileged: bool = False,
|
|
timeout: float = 60,
|
|
stdin: bytes | None = None,
|
|
) -> CommandResult: ...
|
|
|
|
@staticmethod
|
|
def _parse_openwrt_release(output: str) -> dict[str, str]: ...
|
|
|
|
def _read_firmware_facts(self) -> tuple[dict[str, str], str, bool]:
|
|
out = self.run_command(_READ_DEVICE).stdout
|
|
configured = next(
|
|
(ln.split("=", 1)[1] for ln in out.splitlines() if ln.startswith("__ASU_URL=")), ""
|
|
)
|
|
owut = any(ln.strip() == "__OWUT=1" for ln in out.splitlines())
|
|
return self._parse_openwrt_release(out), _server_url(configured), owut
|
|
|
|
def get_firmware_offer(self) -> FirmwareOfferDict | None:
|
|
"""The release running and the newest of its line the sysupgrade server builds.
|
|
|
|
None for a snapshot, a target the line does not build, or a server that
|
|
did not answer.
|
|
"""
|
|
release, server, owut = self._read_firmware_facts()
|
|
current = release.get("DISTRIB_RELEASE", "")
|
|
target = release.get("DISTRIB_TARGET", "")
|
|
if _version_key(current) is None or not target:
|
|
return None
|
|
overview = _overview(server)
|
|
if overview is None:
|
|
return None
|
|
return _offer(overview, current, target, owut)
|
|
|
|
def start_firmware_upgrade(self, version: str) -> None:
|
|
"""Start owut's upgrade to *version*; the device restarts at its end.
|
|
|
|
:raises ValueError: *version* is not a release (``25.12.6``, ``25.12.0-rc5``).
|
|
:raises RuntimeError: a login other than root, owut missing, an upgrade running.
|
|
"""
|
|
if _version_key(version) is None:
|
|
raise ValueError(f"Not an OpenWrt release: {version!r}")
|
|
try:
|
|
result = self.run_command(_start_command(version), privileged=True, timeout=30)
|
|
except PermissionError as exc:
|
|
raise RuntimeError(str(exc)) from exc
|
|
if result.exit_code:
|
|
reason = result.stderr.strip() or result.stdout.strip()
|
|
raise RuntimeError(reason or f"owut did not start (exit status {result.exit_code})")
|
|
|
|
def get_update_progress(self) -> UpdateProgressDict:
|
|
"""Where owut's upgrade stands, from its log (``UpdateMixin.get_update_progress``)."""
|
|
result = self.run_command(_LOG_COMMAND)
|
|
if result.exit_code:
|
|
return {"state": "idle", "log": ""}
|
|
text = result.stdout
|
|
statuses = _STATUS_RE.findall(text)
|
|
log = _STATUS_RE.sub("", text).strip()
|
|
if _INSTALLING.search(text):
|
|
return {"state": "done", "log": log}
|
|
if statuses:
|
|
return {"state": "failed", "log": log}
|
|
return {"state": "running", "log": log}
|