netboot 0.1.0__py3-none-any.whl

netboot/_netutils.py

@@ -0,0 +1,341 @@
+"""Vendored network utilities for netboot (internal).
+
+A thin, typed convenience layer over the standard library's :mod:`ipaddress`
+plus a handful of host helpers (DNS lookup, ping, local NIC discovery). Used
+internally as ``netboot._netutils`` and re-exported from :mod:`netboot.utils.net`.
+
+This is a private, in-tree copy; it may later be extracted back into a standalone
+distribution. Do not depend on the module path from outside netboot.
+
+All IP/network types are the concrete :mod:`ipaddress` classes (or thin
+factories over them), so ``.exploded``, ``.network_address``, ``.netmask`` and
+``addr in network`` membership all behave exactly as the stdlib does.
+"""
+
+from __future__ import annotations
+
+import ipaddress as _ipaddress
+import os as _os
+import platform as _platform
+import re as _re
+import socket as _socket
+from subprocess import run as _run
+from typing import List, Optional, Union
+
+# Re-export the concrete stdlib types so consumers can annotate with them.
+from ipaddress import (
+    IPv4Address,
+    IPv4Interface,
+    IPv4Network,
+    IPv6Address,
+    IPv6Interface,
+    IPv6Network,
+)
+
+__all__ = [
+    "IPAddress",
+    "IPInterface",
+    "IPNetwork",
+    "IPv4Address",
+    "IPv4Interface",
+    "IPv4Network",
+    "IPv6Address",
+    "IPv6Interface",
+    "IPv6Network",
+    "MACAddress",
+    "parse_ip",
+    "parse_network",
+    "is_valid_ip",
+    "nslookup",
+    "ping",
+    "active_nic_addresses",
+    "get_ip_address",
+    "nic_info",
+    "HOST_DN",
+]
+
+__version__ = "0.1.0"
+
+#: Fully-qualified (or short) name of the host running this process.
+HOST_DN = _platform.node()
+
+# Type aliases describing the values these factories accept / return. Kept as
+# runtime objects (not just annotations) so they read well in tracebacks.
+_AddressValue = Union[str, int, "_ipaddress._BaseAddress"]
+_NetworkValue = Union[str, int, "_ipaddress._BaseNetwork", "_ipaddress._BaseAddress"]
+
+
+# ---------------------------------------------------------------------------
+# IP address / interface / network factories
+# ---------------------------------------------------------------------------
+
+def IPAddress(value: _AddressValue) -> Union[IPv4Address, IPv6Address]:
+    """Return an :class:`ipaddress.IPv4Address`/:class:`IPv6Address`.
+
+    Accepts a string (``"10.0.0.5"``), a packed/integer form, or an existing
+    address object (returned as-is by the stdlib). This is a factory, not a
+    class -- ``isinstance(x, IPAddress)`` is not meaningful; test against
+    ``IPv4Address``/``IPv6Address`` instead.
+    """
+    return _ipaddress.ip_address(value)
+
+
+def IPInterface(value: _AddressValue) -> Union[IPv4Interface, IPv6Interface]:
+    """Return an :class:`ipaddress.IPv4Interface`/:class:`IPv6Interface`.
+
+    An interface carries both a host address and its network, exposing ``.ip``,
+    ``.netmask`` and ``.network`` (each with ``.exploded``), e.g.::
+
+        IPInterface("10.0.0.5/24").network.network_address.exploded
+    """
+    return _ipaddress.ip_interface(value)
+
+
+def IPNetwork(value: _NetworkValue, strict: bool = False) -> Union[IPv4Network, IPv6Network]:
+    """Return an :class:`ipaddress.IPv4Network`/:class:`IPv6Network`.
+
+    Defaults to ``strict=False`` so a host address with a prefix (e.g.
+    ``"10.0.0.5/24"``) is accepted and normalised to its network rather than
+    raising. Supports ``.network_address``, ``.netmask`` and ``addr in network``
+    membership tests.
+    """
+    return _ipaddress.ip_network(value, strict=strict)
+
+
+def parse_ip(value: Optional[_AddressValue]) -> Optional[Union[IPv4Address, IPv6Address]]:
+    """Coerce ``value`` to an :class:`ipaddress` address, tolerating emptiness.
+
+    Returns ``None`` for ``None`` or an empty/whitespace-only string -- callers
+    frequently hold an as-yet-unresolved ``ip`` field (``""``) and pass it
+    straight through, so an empty value maps to a falsy ``None`` rather than
+    raising. Any other value is delegated to :func:`IPAddress`, which raises
+    :class:`ValueError` on genuinely malformed input.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str) and not value.strip():
+        return None
+    return IPAddress(value)
+
+
+def parse_network(value: Optional[_NetworkValue]) -> Optional[Union[IPv4Network, IPv6Network]]:
+    """Coerce ``value`` to an :class:`ipaddress` network (non-strict).
+
+    Mirrors :func:`parse_ip`: ``None`` or an empty string yields ``None``;
+    anything else is delegated to :func:`IPNetwork`.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str) and not value.strip():
+        return None
+    return IPNetwork(value)
+
+
+def is_valid_ip(value: object) -> bool:
+    """Return ``True`` if ``value`` is a valid IPv4/IPv6 address.
+
+    Never raises: any input that :func:`ipaddress.ip_address` rejects (including
+    non-string types and empty strings) yields ``False``.
+    """
+    try:
+        _ipaddress.ip_address(value)  # type: ignore[arg-type]
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+# ---------------------------------------------------------------------------
+# MAC address
+# ---------------------------------------------------------------------------
+
+class MACAddress:
+    """An IEEE 802 MAC address.
+
+    Accepts the common textual forms on construction -- colon (``AA:BB:CC:DD:EE:FF``),
+    hyphen (``AA-BB-CC-DD-EE-FF``), dot/Cisco (``aabb.ccdd.eeff``) or bare
+    (``AABBCCDDEEFF``) -- as well as an ``int`` or another ``MACAddress``. The
+    value is normalised to lowercase and compared/hashed by its canonical bytes,
+    so instances are usable as dict keys and set members.
+
+    ``as_str(sep)`` renders the address with an arbitrary separator between
+    octets; ``sep=""`` produces the bare form.
+    """
+
+    #: Compiled pattern matching the accepted textual MAC forms. Exposed as a
+    #: class attribute so callers can pre-screen text with
+    #: ``MACAddress._VALID_MAC.match(text)`` before attempting construction.
+    _VALID_MAC = _re.compile(
+        r"^(?:"
+        r"[0-9A-Fa-f]{2}(?:[:-][0-9A-Fa-f]{2}){5}"  # colon/hyphen separated
+        r"|[0-9A-Fa-f]{4}(?:\.[0-9A-Fa-f]{4}){2}"     # dot / Cisco triplets
+        r"|[0-9A-Fa-f]{12}"                            # bare, no separators
+        r")$"
+    )
+
+    __slots__ = ("_octets",)
+
+    def __init__(self, value: Union[str, int, bytes, "MACAddress"]) -> None:
+        if isinstance(value, MACAddress):
+            self._octets = value._octets
+            return
+        if isinstance(value, (bytes, bytearray)):
+            octets = bytes(value)
+            if len(octets) != 6:
+                raise ValueError("MAC address must be 6 bytes, got %d" % len(octets))
+            self._octets = octets
+            return
+        if isinstance(value, int):
+            if value < 0 or value > 0xFFFFFFFFFFFF:
+                raise ValueError("MAC integer out of range: %r" % (value,))
+            self._octets = value.to_bytes(6, "big")
+            return
+        if isinstance(value, str):
+            text = value.strip()
+            if not self._VALID_MAC.match(text):
+                raise ValueError("Invalid MAC address: %r" % (value,))
+            hexdigits = _re.sub(r"[.:-]", "", text)
+            self._octets = bytes.fromhex(hexdigits)
+            return
+        raise TypeError("Cannot build MACAddress from %r" % (type(value).__name__,))
+
+    def as_str(self, sep: str = ":") -> str:
+        """Return the MAC as a lowercase string with ``sep`` between octets."""
+        return sep.join("%02x" % b for b in self._octets)
+
+    @property
+    def packed(self) -> bytes:
+        """The 6 raw bytes of the address."""
+        return self._octets
+
+    def __int__(self) -> int:
+        return int.from_bytes(self._octets, "big")
+
+    def __str__(self) -> str:
+        return self.as_str(":")
+
+    def __repr__(self) -> str:
+        return "MACAddress(%r)" % (self.as_str(":"),)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, MACAddress):
+            return self._octets == other._octets
+        if isinstance(other, str):
+            try:
+                return self._octets == MACAddress(other)._octets
+            except (ValueError, TypeError):
+                return NotImplemented
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self._octets)
+
+
+# ---------------------------------------------------------------------------
+# DNS / reachability
+# ---------------------------------------------------------------------------
+
+def nslookup(query: str, ns: Optional[Union[str, List[str]]] = None, type: str = "a") -> List[str]:
+    """Resolve ``query`` via DNS and return the answers as a list of strings.
+
+    Contract: always returns a ``list`` of string records (e.g. one or more
+    ``"93.184.216.34"`` for an ``A`` lookup), and an **empty list** when the
+    name does not resolve or any DNS error occurs -- never ``None``. Callers can
+    therefore write ``if result:`` and index ``result[0]`` safely.
+
+    :param query: the name (or address, for reverse types) to look up.
+    :param ns: optional nameserver, or list of nameservers, to query instead of
+        the system resolver.
+    :param type: DNS record type (``"a"``, ``"aaaa"``, ``"mx"`` ...).
+
+    Requires the ``dnspython`` package.
+    """
+    from dns import resolver as _resolver
+
+    r = _resolver.Resolver(configure=not ns)
+    if isinstance(ns, str):
+        ns = [ns]
+    if ns:
+        r.nameservers = list(ns)
+    try:
+        answer = r.resolve(query, type)
+    except Exception:
+        return []
+    return [str(record) for record in answer]
+
+
+def ping(hostname: str, tries: int = 1) -> bool:
+    """Return ``True`` if ``hostname`` answers a single ICMP echo within ``tries``.
+
+    Shells out to the platform ``ping`` (Windows ``-n``/``-w`` vs POSIX
+    ``-c``/``-W``), sending one packet per attempt with a 1s timeout, and
+    returns on the first success. An empty ``hostname`` is ``False``.
+    """
+    if not hostname:
+        return False
+    if _os.name == "nt":
+        options = ["-n", "1", "-w", "1000"]
+    else:
+        options = ["-c", "1", "-W", "1", "-n"]
+    tries = tries or 1
+    while tries > 0:
+        response = _run(["ping", *options, hostname], capture_output=True)
+        if response.returncode == 0:
+            return True
+        tries -= 1
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Local NIC discovery
+# ---------------------------------------------------------------------------
+
+def active_nic_addresses() -> List[IPv4Address]:
+    """Return the host's active (non-loopback) IPv4 address as a 1-element list.
+
+    Resolves the local hostname and filters out ``127.*`` loopback entries.
+    Returns an empty list if only loopback addresses are found. Cross-platform.
+    """
+    try:
+        _, _, ips = _socket.gethostbyname_ex(_socket.gethostname())
+    except OSError:
+        return []
+    return [IPv4Address(ip) for ip in ips if not ip.startswith("127.")][:1]
+
+
+def get_ip_address(nic_name: str) -> str:
+    """Return the IPv4 address bound to interface ``nic_name`` (POSIX only).
+
+    Uses an ``SIOCGIFADDR`` ioctl and therefore requires the POSIX-only
+    :mod:`fcntl` module. Raises :class:`OSError` (``NotImplementedError`` under
+    Windows, where ``fcntl`` is unavailable).
+    """
+    import struct
+
+    try:
+        import fcntl
+    except ImportError as exc:  # pragma: no cover - platform dependent
+        raise NotImplementedError("get_ip_address requires POSIX fcntl") from exc
+
+    s = _socket.socket(_socket.AF_INET, _socket.SOCK_DGRAM)
+    try:
+        return _socket.inet_ntoa(
+            fcntl.ioctl(
+                s.fileno(),
+                0x8915,  # SIOCGIFADDR
+                struct.pack("256s", nic_name[:15].encode("utf-8")),
+            )[20:24]
+        )
+    finally:
+        s.close()
+
+
+def nic_info() -> List[tuple]:
+    """Return ``[(name, ipv4), ...]`` for each interface (POSIX only).
+
+    Enumerates interfaces via :func:`socket.if_nameindex` (POSIX only) and pairs
+    each with its :func:`get_ip_address`. Raises on platforms without these
+    facilities (e.g. Windows).
+    """
+    if not hasattr(_socket, "if_nameindex"):  # pragma: no cover - platform dependent
+        raise NotImplementedError("nic_info requires POSIX socket.if_nameindex")
+    return [(name, get_ip_address(name)) for _, name in _socket.if_nameindex()]

netboot/cmds/__init__.py

@@ -0,0 +1,5 @@
+"""Built-in netboot commands.
+
+Each module here is a duho command exposing ``register(parser, args)`` and
+``run(netboot, args, conf)``; :mod:`netboot.main` discovers them as ``netboot.cmds``.
+"""

netboot/cmds/complete.py

@@ -0,0 +1,24 @@
+"""Complete the PXE process for a target: run post-boot cleanup tasks."""
+
+from __future__ import annotations
+
+import argparse
+
+from netboot import Pixie
+from netboot.logging import LOGGER
+
+
+def register(parser: argparse.ArgumentParser, args) -> None:
+    parser.add_argument(
+        "target", help="-/Hostname/MAC/IP of the target to complete"
+    )
+
+
+def run(netboot: Pixie, args, conf: dict) -> int:
+    target = netboot.lookup_target(args.target)
+    if target is None:
+        LOGGER.error("Target not found: %s", args.target)
+        return 1
+    LOGGER.info("Running post-PXE tasks for: %s", args.target)
+    netboot.complete(target)
+    return 0

netboot/cmds/initiate.py

@@ -0,0 +1,36 @@
+"""Initiate the PXE process for a target: render artifacts and arm DHCP."""
+
+from __future__ import annotations
+
+import argparse
+
+from netboot import Pixie
+from netboot.logging import LOGGER
+
+
+def register(parser: argparse.ArgumentParser, args) -> None:
+    parser.add_argument(
+        "target", help="-/Hostname/MAC/IP of the target to initiate"
+    )
+    parser.add_argument(
+        "--iscsi",
+        action="store_true",
+        default=False,
+        help="Prepare as an iSCSI LUN",
+    )
+
+
+def run(netboot: Pixie, args, conf: dict) -> int:
+    target = netboot.lookup_target(args.target)
+    if target is None:
+        LOGGER.error("Target not found: %s", args.target)
+        return 1
+    LOGGER.info(
+        "Initiating Hostname: %s IP: %s MAC: %s",
+        target.hostname,
+        target.ip,
+        target.mac,
+    )
+    netboot.initialize(target)
+    LOGGER.info("Netboot initiated for: %s", args.target)
+    return 0

netboot/content/__init__.py

@@ -0,0 +1,88 @@
+import typing as _ty
+from typing import Union
+
+from pathlib_next import Pathname
+from pathlib_next import PosixPathname as RepoPath
+from pathlib_next.uri import Source, UriPath
+
+from ..utils.config import Namespace as _NS
+from ..utils.net import Host
+
+
+class Resource(_NS):
+    path: Pathname
+    src: str
+
+    def __truediv__(self, key):
+        return Resource(path=self.path / key, src=self.src)
+
+    @classmethod
+    def _parse_path(cls, path: Union[str, Pathname]):
+        if not isinstance(path, Pathname):
+            path = RepoPath(path)
+        return path
+
+
+class Repository(_NS):
+    address: Host
+    services: dict[str, UriPath]
+    local: "_ty.Optional[UriPath]"
+
+    def __init__(self, **kwargs) -> None:
+        self.services = {}
+        kwargs.setdefault("address", None)
+        kwargs.setdefault("local", None)
+        super().__init__(**kwargs)
+        if not isinstance(self.address, Host):
+            self.address = Host(self.address)
+        if self.local and not isinstance(self.local, UriPath):
+            self.local = UriPath(self.local)
+
+    def __getitem__(self, key: tuple[str, str]) -> UriPath:
+        rel_path, service = key
+        return self.get(rel_path, service=service)
+
+    def __truediv__(self, key) -> "Repository":
+        return self.joinpath(key)
+
+    def joinpath(self, subpath: str = None):
+        repo = Repository(address=self.address, services={}, local=self.local)
+        for srvc in self.services:
+            repo.services[srvc] = (
+                f"{self.services[srvc]}/{subpath}" if subpath else self.services[srvc]
+            )
+        if self.local:
+            repo.local = self.local / subpath if subpath else self.local
+        else:
+            # Keep .local a Pathname (not a raw str) so chained joinpath works.
+            repo.local = RepoPath(subpath) if subpath else None
+        return repo
+
+    def get(self, *path: Union[RepoPath, str], service: str = None) -> UriPath:
+        path: RepoPath = RepoPath(
+            *[(p if isinstance(p, Pathname) else RepoPath(p)).as_posix() for p in path]
+        )
+        rel_path = path.as_posix().lstrip("/")
+        baseuri = self.service(service)
+        if not baseuri:
+            return None
+        return baseuri / rel_path
+
+    def service(self, name: str):
+        if name is None:
+            baseuri = self.local
+            name = "file"
+            host = ""
+        else:
+            baseuri = self.services.get(name, None)
+            host = str(self.address.try_ip())
+        if baseuri is None:
+            return None
+        if not isinstance(baseuri, UriPath):
+            baseuri = UriPath(baseuri)
+        if not baseuri.source:
+            baseuri = baseuri.with_source(
+                Source(scheme=name, userinfo=None, host=host, port=None)
+            )
+
+        return baseuri

netboot/dhcp.py

@@ -0,0 +1,123 @@
+import typing as _ty
+from argparse import Namespace
+
+from . import _netutils as netutils
+from yaconfiglib import OpaqueMerge
+
+from .utils.net import IPAddress, IPInterface, IPNetwork
+
+if _ty.TYPE_CHECKING:
+    from . import PixieContext
+
+from urllib.parse import urlparse
+
+
+def _iter_subclasses(cls: type) -> "_ty.Iterator[type]":
+    """Yield every subclass of ``cls``, recursively (not just direct children).
+
+    Plugin ``DhcpServer`` handlers loaded via ``--load-module`` may subclass an
+    intermediate base, so a one-level ``__subclasses__()`` scan would miss them.
+    """
+    for sub in cls.__subclasses__():
+        yield sub
+        yield from _iter_subclasses(sub)
+
+
+class DhcpServer:
+    """Base for DHCP backends. ``DhcpServer(uri)`` dispatches on the URI scheme.
+
+    A concrete backend is a subclass whose lowercased class name matches the URI
+    scheme (e.g. ``class dnsmasq(DhcpServer)`` handles ``dnsmasq://...``); such
+    backends are typically provided by a plugin module imported via
+    ``--load-module``. Subclassing at any depth is honoured.
+    """
+
+    DEFAULT_SCHEME = None
+
+    def __new__(cls, uri: str):
+        if cls is DhcpServer:
+            parsed = urlparse(uri)
+            scheme = parsed.scheme or cls.DEFAULT_SCHEME
+            for sub in _iter_subclasses(cls):
+                if sub.__name__.lower() == scheme:
+                    return object.__new__(sub)
+            raise ValueError(
+                f"No DhcpServer backend registered for scheme {scheme!r} "
+                f"(uri={uri!r}); import a plugin module providing it via --load-module"
+            )
+        return object.__new__(cls)
+
+    def __init__(self, uri: str):
+        self.uri = uri
+
+    def remove_target(self, netboot: "PixieContext"):
+        pass
+
+    def add_target(self, netboot: "PixieContext"):
+        pass
+
+
+class DhcpZone(Namespace, OpaqueMerge):
+    network: IPNetwork
+    gateway: "_ty.Optional[IPAddress]"
+    domain: "_ty.Optional[str]"
+    search: "list[str]"
+    nameservers: "list[IPAddress]"
+    globals: dict
+    dhcpservers: "list[DhcpServer]"
+
+    @property
+    def nameserver(self):
+        return self.nameservers[0] if self.nameservers else ""
+
+    def get_local_server(self, servers: "list[IPAddress]", default: IPAddress):
+        for server in servers:
+            if server in self.network:
+                return server
+        return default
+
+    def __init__(self, **kwargs) -> None:
+        _gateway = kwargs.get("gateway")
+        _network = kwargs.get("network")
+        _netmask = kwargs.get("netmask")
+        if _gateway and not _network:
+            gw: netutils.IPv4Interface = IPInterface(_gateway)
+            if not _netmask and isinstance(_gateway, str) and "/" in _gateway:
+                _netmask = gw.netmask.exploded
+                kwargs["gateway"] = gw.ip.exploded
+            if _netmask:
+                _network = gw.network.network_address.exploded
+
+        if isinstance(_network, str) and "/" in _network:
+            net = IPNetwork(_network)
+            _network = net.network_address.exploded
+            _netmask = net.netmask.exploded
+        if _network:
+            if _netmask and isinstance(_network, str):
+                _network = f"{_network}/{_netmask}"
+            kwargs["network"] = _network
+
+        kwargs.pop("netmask", None)
+        kwargs.setdefault("dhcpservers", [])
+        super().__init__(**kwargs)
+        self.dhcpservers = [
+            server if isinstance(server, DhcpServer) else DhcpServer(server)
+            for server in (self.dhcpservers or [])
+        ]
+        self.network = netutils.parse_network(self.network)
+        for prop, ctr in [("nameservers", netutils.parse_ip), ("search", str)]:
+            value = getattr(self, prop, None)
+            if not value:
+                setattr(self, prop, [])
+            elif not isinstance(value, list):
+                setattr(self, prop, [value])
+            vals = getattr(self, prop)
+            for i, val in enumerate(vals):
+                vals[i] = ctr(val)
+
+        for prop in ["gateway", "domain"]:
+            if not getattr(self, prop, None):
+                setattr(self, prop, None)
+
+        if self.gateway:
+            self.gateway = netutils.parse_ip(self.gateway)

netboot/logging.py

@@ -0,0 +1,17 @@
+"""The netboot logger, plus best-effort quieting of chatty optional deps."""
+
+import logging
+
+LOGGER = logging.getLogger("NETBOOT")
+
+# Quiet third-party loggers if those libraries end up in the process (e.g. a repo
+# backend pulls in urllib3/paramiko). Setting a level does not import anything.
+logging.getLogger("urllib3.connectionpool").setLevel(logging.WARNING)
+logging.getLogger("paramiko.transport").setLevel(logging.WARNING)
+
+try:  # pragma: no cover - only when urllib3 is actually installed
+    import urllib3
+
+    urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+except Exception:
+    pass