diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a30fb2..4ba3128 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,12 @@ recorded here; their history is the git log. ## [Unreleased] ### 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 diff --git a/README.md b/README.md index f8fc9b9..99c3aab 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 94f9b30..8355a18 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -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 diff --git a/napalm_device_types/system_identity.py b/napalm_device_types/system_identity.py index 6549d3b..a32a89c 100644 --- a/napalm_device_types/system_identity.py +++ b/napalm_device_types/system_identity.py @@ -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. """ diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 4065f83..06714cf 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -31,7 +31,7 @@ }, "mypy_relaxed": [], "python_file_lines": { - "napalm_device_types/models.py": 1454 + "napalm_device_types/models.py": 1442 }, "untyped_public": [] } diff --git a/tests/test_system_identity.py b/tests/test_system_identity.py index c874b00..40365ca 100644 --- a/tests/test_system_identity.py +++ b/tests/test_system_identity.py @@ -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