Compare commits

..
7 Commits
Author SHA1 Message Date
christianmanivong b4929990f1 Merge pull request 'chore(release): 4.39.0' (#121) from chore/release-4.39.0 into main
driver / types (push) Successful in 54s
driver / standard (push) Successful in 17s
driver / lint (push) Successful in 13s
driver / test (3.12) (push) Successful in 1m12s
driver / lowest (push) Successful in 36s
driver / test (3.13) (push) Successful in 1m2s
driver / build (push) Successful in 26s
driver / security (push) Successful in 1m20s
driver / publish (push) Successful in 29s
CI / driver (push) Successful in 3m32s
2026-11-14 22:56:28 +00:00
christianmanivong 3db6c6385c Merge pull request 'feat(updates): PackageIndexMissing, for a host without a package index' (#120) from feat/package-index-missing into main
driver / lint (push) Successful in 12s
driver / standard (push) Successful in 14s
driver / types (push) Successful in 53s
driver / test (3.13) (push) Successful in 1m1s
driver / test (3.12) (push) Successful in 1m7s
driver / lowest (push) Successful in 34s
driver / build (push) Successful in 28s
driver / security (push) Successful in 1m0s
CI / driver (push) Successful in 2m15s
driver / publish (push) Skipped
2026-11-14 22:52:11 +00:00
christianmanivong c5154d954b chore(release): 4.39.0
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 12s
driver / types (pull_request) Successful in 49s
driver / test (3.12) (pull_request) Successful in 1m3s
driver / lowest (pull_request) Successful in 33s
driver / test (3.13) (pull_request) Successful in 59s
driver / build (pull_request) Successful in 24s
driver / security (pull_request) Successful in 50s
CI / driver (pull_request) Successful in 2m19s
driver / publish (pull_request) Skipped
2026-11-14 23:52:11 +01:00
christianmanivong 211d0c02eb feat(updates): PackageIndexMissing, for a host without a package index
driver / lint (pull_request) Successful in 15s
driver / standard (pull_request) Successful in 18s
driver / types (pull_request) Successful in 58s
driver / test (3.13) (pull_request) Successful in 1m2s
driver / test (3.12) (pull_request) Successful in 1m10s
driver / lowest (pull_request) Successful in 36s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 52s
CI / driver (pull_request) Successful in 2m12s
driver / publish (pull_request) Skipped
OpenWrt keeps its package index in RAM and loses it on every reboot.
get_available_updates() raises then, rightly, but only as a bare
RuntimeError, so a caller cannot tell it from a read that failed and
reports a communication error for a state a refresh cures.

PackageIndexMissing (a RuntimeError, so existing callers still catch it)
names that case; refresh_available_updates() is the way out.

Refs NetOrk/netork#2527
2026-11-14 23:45:38 +01:00
christianmanivong 74d2f42b0e Merge pull request 'feat(system-identity): read the system firmware with the identity' (#119) from feat/system-firmware into main
driver / standard (push) Successful in 17s
driver / lint (push) Successful in 16s
driver / types (push) Successful in 56s
driver / test (3.12) (push) Successful in 1m13s
driver / test (3.13) (push) Successful in 1m10s
driver / lowest (push) Successful in 43s
driver / build (push) Successful in 31s
driver / security (push) Successful in 1m6s
CI / driver (push) Successful in 2m52s
driver / publish (push) Skipped
2026-11-13 22:11:26 +00:00
christianmanivong c25f39768f refactor(system-identity): keep SystemIdentityDict with its mixin
driver / standard (pull_request) Successful in 18s
driver / lint (pull_request) Successful in 13s
driver / types (pull_request) Successful in 57s
driver / test (3.13) (pull_request) Successful in 1m6s
driver / test (3.12) (pull_request) Successful in 1m15s
driver / lowest (pull_request) Successful in 38s
driver / build (pull_request) Successful in 28s
driver / security (pull_request) Successful in 1m4s
CI / driver (pull_request) Successful in 2m51s
driver / publish (pull_request) Skipped
models.py is over its line limit and may not grow; the dict has no other
user than system_identity.py, as clusters.py and apt_proxy.py keep theirs.

NetOrk/netork#2518
2026-11-13 23:04:18 +01:00
christianmanivong 9ecc6823c8 feat(system-identity): read the system firmware with the identity
driver / lint (pull_request) Successful in 13s
driver / standard (pull_request) Failing after 15s
driver / types (pull_request) Successful in 52s
driver / test (3.13) (pull_request) Successful in 1m3s
driver / test (3.12) (pull_request) Successful in 1m11s
driver / lowest (pull_request) Successful in 39s
driver / build (pull_request) Successful in 28s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Failing after 2m17s
driver / publish (pull_request) Skipped
get_system_identity() also reads bios_vendor, bios_version and bios_date
from /sys/class/dmi/id, in the same round trip as the SMBIOS identity.
The date is given as ISO 8601; anything that is no MM/DD/YYYY reads as
empty. Only the vendors' text defaults are placeholders for the firmware:
a version of "1" is a version, unlike a serial of one repeated character.

Output of the three identity fields alone still parses, with the firmware
empty.

NetOrk/netork#2518
2026-11-13 23:00:23 +01:00
10 changed files with 189 additions and 34 deletions

No files matched your search

+14
View File
@@ -7,9 +7,23 @@ recorded here; their history is the git log.
## [Unreleased]
## [4.39.0] - 2026-11-14
### Added
- `PackageIndexMissing` (a `RuntimeError`): what `get_available_updates()` raises when
the host holds no package index to read from -- OpenWrt's, which lives in RAM, after
every reboot. `refresh_available_updates()` loads it again, so a caller can tell this
from a failed read and refresh instead of reporting an error (NetOrk/netork#2527).
## [4.38.0] - 2026-11-13
### Added
- `get_system_identity()` also reads the host's system firmware (BIOS or UEFI) from the
same SMBIOS tables in the same round trip: `bios_vendor`, `bios_version` and
`bios_date` (ISO 8601, from sysfs's `MM/DD/YYYY`; anything else reads as empty). Only
the vendors' text defaults (`To be filled by O.E.M.`, `Default string`) are
placeholders there -- a version of `1` is a version. Output of the three identity
fields alone still parses, with the firmware empty (NetOrk/netork#2518).
- `ConfigRevisionsMixin`: a device's own configuration history (NetOrk/netork#2511).
`get_config_revisions()` (newest first, the first in place now, as
`ConfigRevisionDict`: id, UTC time, description, user, size) and
+3
View File
@@ -286,6 +286,9 @@ O.E.M.`, `Default string`, all-zero or the common `03000200-…-000700080009` UU
empty: matching on them would join unrelated machines. `is_placeholder_identity` is the
same filter for a BMC driver's side. `product_uuid` and `product_serial` are root's, so a
driver supplies `_run_system_identity_command(command, privileged=)`.
The same round trip reads the host's system firmware (BIOS or UEFI): `bios_vendor`,
`bios_version` and `bios_date` (`YYYY-MM-DD`, from sysfs's `MM/DD/YYYY`). Only the vendors'
text defaults read as empty there; a short version such as `1` is a version.
`OpenSshServerMixin` (`harden_ssh_server`, `get_ssh_server_algorithms`) takes algorithms
out of what an OpenSSH server offers -- the ones ssh-audit flags. It reads the lists sshd
+2 -1
View File
@@ -335,7 +335,7 @@ from napalm_device_types.time_sync import (
check_ntp_servers,
)
from napalm_device_types.time_sync_posix import PosixTimeSyncMixin, parse_time_sync
from napalm_device_types.updates import UpdateMixin
from napalm_device_types.updates import PackageIndexMissing, UpdateMixin
from napalm_device_types.virtual_ips import (
VIRTUAL_IPS_COMMAND,
VirtualIpsMixin,
@@ -505,6 +505,7 @@ __all__ = [
"SystemdServicesMixin",
"SystemdUnavailable",
"parse_systemd_services",
"PackageIndexMissing",
"UpdateMixin",
"VIRTUAL_IPS_COMMAND",
"VirtualIpsMixin",
-12
View File
@@ -1440,15 +1440,3 @@ class ManagementProtocolsDict(TypedDict):
snmp: ProtocolStateDict
kvm: ProtocolStateDict
virtual_media: ProtocolStateDict
class SystemIdentityDict(TypedDict):
"""A host's SMBIOS identity, what ties it to its BMC.
See :mod:`napalm_device_types.system_identity`.
Each value is empty when unknown or a vendor placeholder."""
system_uuid: str # lowercase
product_serial: str
board_serial: str
+66 -15
View File
@@ -1,6 +1,7 @@
"""The SMBIOS identity of a host: system UUID, product serial, board serial.
"""The SMBIOS identity of a host: system UUID, product serial, board serial -- and
its system firmware (BIOS or UEFI): vendor, version, release date.
What ties a server to its BMC. The BMC reports the server's serial number and
The identity is what ties a server to its BMC. The BMC reports the server's serial number and
system UUID; the host reads the same values from its firmware tables. Both sides
read them the same way on every Linux host, so the command, its parse and the
placeholder filter live here once, and a driver only carries the command across.
@@ -13,27 +14,54 @@ Matching on those would join unrelated machines, so they read as empty.
**Root.** ``product_uuid`` and ``product_serial`` are readable by root only; without
it they come back empty, which is "not known", not a mismatch.
**The firmware** comes from the same tables in the same round trip, so a driver that
reads the identity reads it too. It is a fact about the host, not part of its identity:
its placeholders are the vendors' text defaults, never a short value (a version of
``1`` is a version), and sysfs's ``MM/DD/YYYY`` release date is given as ISO 8601.
"""
from __future__ import annotations
import re
from typing import TYPE_CHECKING
from datetime import date
from typing import TYPE_CHECKING, TypedDict
from napalm_device_types.models import SystemIdentityDict
from napalm_device_types.terminal import strip_terminal_codes
class SystemIdentityDict(TypedDict):
"""A host's SMBIOS identity, what ties it to its BMC, and its system firmware.
Each value is empty when unknown or a vendor placeholder."""
system_uuid: str # lowercase
product_serial: str
board_serial: str
bios_vendor: str # the system firmware (BIOS or UEFI): its vendor,
bios_version: str # its version,
bios_date: str # its release date, YYYY-MM-DD
_BEGIN = "IDBEGIN"
_END = "IDEND"
_DMI = "/sys/class/dmi/id"
#: Reads the three files in one round trip, framed so a banner or prompt around the
#: output cannot shift a field.
SYSTEM_IDENTITY_COMMAND = (
f"printf '{_BEGIN}\\n%s\\n%s\\n%s\\n{_END}\\n' "
f'"$(cat {_DMI}/product_uuid 2>/dev/null)" '
f'"$(cat {_DMI}/product_serial 2>/dev/null)" '
f'"$(cat {_DMI}/board_serial 2>/dev/null)"'
#: The files read, in the order the output carries them.
_FILES = (
"product_uuid",
"product_serial",
"board_serial",
"bios_vendor",
"bios_version",
"bios_date",
)
#: Reads the files in one round trip, framed so a banner or prompt around the output
#: cannot shift a field.
_FIELDS = "%s\\n" * len(_FILES)
SYSTEM_IDENTITY_COMMAND = f"printf '{_BEGIN}\\n{_FIELDS}{_END}\\n' " + " ".join(
f'"$(cat {_DMI}/{name} 2>/dev/null)"' for name in _FILES
)
#: Lowercased defaults board vendors leave in place.
@@ -80,6 +108,22 @@ def _clean(value: str) -> str:
return "" if is_placeholder_identity(value) else value
def _clean_text(value: str) -> str:
"""A firmware text, empty for a vendor's text default; a short value stays."""
value = value.strip()
return "" if value.lower() in _PLACEHOLDERS else value
def _iso_date(value: str) -> str:
"""sysfs's ``MM/DD/YYYY`` as ``YYYY-MM-DD``; anything else is no date."""
month, _, rest = value.strip().partition("/")
day, _, year = rest.partition("/")
try:
return date(int(year), int(month), int(day)).isoformat()
except ValueError:
return ""
def parse_system_identity(output: str) -> SystemIdentityDict:
"""The identity from :data:`SYSTEM_IDENTITY_COMMAND`'s output, placeholders empty.
@@ -91,12 +135,16 @@ def parse_system_identity(output: str) -> SystemIdentityDict:
end = lines.index(_END, start)
except ValueError:
raise ValueError("system identity: no intact IDBEGIN/IDEND frame") from None
fields = (lines[start:end] + ["", "", ""])[:3]
uuid, product_serial, board_serial = (_clean(f) for f in fields)
fields = (lines[start:end] + [""] * len(_FILES))[: len(_FILES)]
uuid, product_serial, board_serial = (_clean(f) for f in fields[:3])
bios_vendor, bios_version, bios_date = fields[3:]
return {
"system_uuid": uuid.lower(),
"product_serial": product_serial,
"board_serial": board_serial,
"bios_vendor": _clean_text(bios_vendor),
"bios_version": _clean_text(bios_version),
"bios_date": _iso_date(bios_date),
}
@@ -119,12 +167,15 @@ class SystemIdentityMixin:
def get_system_identity(self) -> SystemIdentityDict:
"""
Returns the host's SMBIOS identity, each value empty when unknown or a vendor
placeholder:
Returns the host's SMBIOS identity and system firmware, each value empty when
unknown or a vendor placeholder:
* system_uuid (str) - lowercase
* product_serial (str)
* board_serial (str)
* bios_vendor (str) - the system firmware's vendor
* bios_version (str)
* bios_date (str) - its release date, ``YYYY-MM-DD``
:raises ValueError: if the output carried no intact reading.
"""
+11
View File
@@ -17,6 +17,15 @@ from typing import TYPE_CHECKING, Any
from napalm_device_types.models import ApplyUpdatesResultDict, UpdateDict, UpdateProgressDict
class PackageIndexMissing(RuntimeError):
"""The host holds no package index to read pending updates from.
Not a fault: OpenWrt keeps its index in RAM and loses it on every reboot.
:meth:`UpdateMixin.refresh_available_updates` loads it again, so a caller
that sees this can refresh instead of reporting a failed read.
"""
class UpdateMixin:
if TYPE_CHECKING:
@@ -37,6 +46,8 @@ class UpdateMixin:
read -- no package index yet, an API that did not answer -- raises
instead: netOrk keeps "pending since" per package, and an empty
list for "don't know" would reset every one of those clocks.
Without a package index it raises :exc:`PackageIndexMissing`, which
:meth:`refresh_available_updates` cures.
Example::
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "napalm-device-types"
version = "4.38.0"
version = "4.39.0"
description = "Abstract device-type base classes for NAPALM drivers"
readme = "README.md"
requires-python = ">=3.12"
+1 -1
View File
@@ -31,7 +31,7 @@
},
"mypy_relaxed": [],
"python_file_lines": {
"napalm_device_types/models.py": 1454
"napalm_device_types/models.py": 1442
},
"untyped_public": []
}
+71 -4
View File
@@ -14,8 +14,19 @@ from napalm_device_types import (
UUID = "31303043-534D-C40C-7A72-6F1300000000"
def _out(uuid: str, product_serial: str, board_serial: str) -> str:
return f"IDBEGIN\n{uuid}\n{product_serial}\n{board_serial}\nIDEND\n"
def _out(
uuid: str,
product_serial: str,
board_serial: str,
bios: tuple[str, str, str] = ("", "", ""),
) -> str:
vendor, version, date = bios
return (
f"IDBEGIN\n{uuid}\n{product_serial}\n{board_serial}\n{vendor}\n{version}\n{date}\nIDEND\n"
)
_NO_FIRMWARE = {"bios_vendor": "", "bios_version": "", "bios_date": ""}
# ── parsing ───────────────────────────────────────────────────────────────────
@@ -26,6 +37,7 @@ def test_reads_uuid_and_both_serials():
"system_uuid": "31303043-534d-c40c-7a72-6f1300000000",
"product_serial": "S123",
"board_serial": "ZM155S026022",
**_NO_FIRMWARE,
}
@@ -81,9 +93,57 @@ def test_unreadable_files_read_as_empty():
"system_uuid": "",
"product_serial": "",
"board_serial": "BS1",
**_NO_FIRMWARE,
}
# ── the system firmware ───────────────────────────────────────────────────────
def test_reads_the_system_firmware():
# pve-dual, a Supermicro X10DRL-i
out = _out(UUID, "", "ZM155S026022", ("American Megatrends Inc.", "3.4", "11/22/2021"))
identity = parse_system_identity(out)
assert identity["bios_vendor"] == "American Megatrends Inc."
assert identity["bios_version"] == "3.4"
assert identity["bios_date"] == "2021-11-22"
def test_a_virtual_machines_firmware_is_read_like_any_other():
out = _out(UUID, "", "", ("EDK II", "4.2023.08-4", "02/15/2024"))
assert parse_system_identity(out)["bios_version"] == "4.2023.08-4"
@pytest.mark.parametrize("version", ["1", "0", "1.0", "A"])
def test_a_short_firmware_version_is_no_placeholder(version):
# Serials of one repeated character are placeholders, versions are not.
out = _out(UUID, "", "", ("Vendor", version, ""))
assert parse_system_identity(out)["bios_version"] == version
@pytest.mark.parametrize("value", ["", "To be filled by O.E.M.", "Default string", "Not Specified"])
def test_a_placeholder_firmware_version_reads_as_empty(value):
out = _out(UUID, "", "", (value, value, ""))
identity = parse_system_identity(out)
assert identity["bios_vendor"] == ""
assert identity["bios_version"] == ""
@pytest.mark.parametrize("date", ["", "not a date", "13/45/2021", "2021-11-22"])
def test_a_firmware_date_that_is_no_smbios_date_reads_as_empty(date):
# sysfs writes the SMBIOS date as MM/DD/YYYY; anything else is no reading of it.
out = _out(UUID, "", "", ("Vendor", "1.2", date))
assert parse_system_identity(out)["bios_date"] == ""
def test_output_of_the_identity_alone_has_no_firmware():
# What a host answered before the firmware was read with it: three fields.
old = f"IDBEGIN\n{UUID}\nS1\nB1\nIDEND\n"
identity = parse_system_identity(old)
assert identity["board_serial"] == "B1"
assert {k: identity[k] for k in _NO_FIRMWARE} == _NO_FIRMWARE
def test_output_without_its_frame_is_not_a_reading():
with pytest.raises(ValueError):
parse_system_identity("sudo: a password is required\n")
@@ -115,6 +175,13 @@ def test_the_driver_only_carries_the_command_across():
assert privileged is True
def test_the_command_reads_the_three_dmi_files():
for name in ("product_uuid", "product_serial", "board_serial"):
def test_the_command_reads_the_dmi_files():
for name in (
"product_uuid",
"product_serial",
"board_serial",
"bios_vendor",
"bios_version",
"bios_date",
):
assert f"/sys/class/dmi/id/{name}" in SYSTEM_IDENTITY_COMMAND
+20
View File
@@ -0,0 +1,20 @@
"""The contract of :class:`~napalm_device_types.updates.UpdateMixin`."""
from __future__ import annotations
import napalm_device_types
from napalm_device_types.updates import PackageIndexMissing
def test_a_missing_index_is_its_own_failure():
"""A reader can tell "no index to read from" from any other failure, and a
caller that only knows failures still catches it as one."""
exc = PackageIndexMissing("The package index is not loaded (run apk update first)")
assert isinstance(exc, RuntimeError)
assert str(exc) == "The package index is not loaded (run apk update first)"
def test_it_is_exported_from_the_package():
assert napalm_device_types.PackageIndexMissing is PackageIndexMissing
assert "PackageIndexMissing" in napalm_device_types.__all__