Files
napalm-openwrt/napalm_openwrt/firmware_mixin.py
T
Christian Manivong 6a8ebfe235
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
fix(security): say why the device's /tmp and the http(s) fetch are fine (bandit)
2026-11-17 13:53:19 +01:00

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}