Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b4929990f1 | ||
|
|
3db6c6385c | ||
|
|
c5154d954b | ||
|
|
211d0c02eb | ||
|
|
74d2f42b0e | ||
|
|
c25f39768f | ||
|
|
9ecc6823c8 |
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
|
||||
@@ -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.
|
||||
"""
|
||||
|
||||
@@ -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
@@ -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"
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
},
|
||||
"mypy_relaxed": [],
|
||||
"python_file_lines": {
|
||||
"napalm_device_types/models.py": 1454
|
||||
"napalm_device_types/models.py": 1442
|
||||
},
|
||||
"untyped_public": []
|
||||
}
|
||||
@@ -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
|
||||
@@ -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__
|
||||
Reference in new issue
Block a user