embedded-lab-control 0.2.0__py3-none-any.whl

labctl/serial/ser2net.py

@@ -0,0 +1,338 @@
+"""
+ser2net configuration generator.
+
+Generates ser2net YAML configuration for exposing serial ports over TCP.
+Supports ser2net 4.0+ YAML configuration format.
+"""
+
+import errno
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+PARITY_CHARS = {"none": "n", "even": "e", "odd": "o"}
+
+
+@dataclass
+class Ser2NetPort:
+    """Configuration for a single ser2net port."""
+
+    name: str
+    device: str  # e.g., /dev/lab/sbc1-console
+    tcp_port: int
+    baud: int = 115200
+    databits: int = 8
+    parity: str = "none"  # none, even, odd
+    stopbits: int = 1
+    local: bool = True  # Only allow local connections
+    kickolduser: bool = False  # Don't kick existing connections
+
+    def to_ser2net_dict(self) -> dict:
+        """Convert to ser2net YAML connection format."""
+        # ser2net serial params: <baud><parity><databits><stopbits>, e.g. 115200n81
+        parity_char = PARITY_CHARS.get(self.parity.lower(), "n")
+        conn_str = f"{self.baud}{parity_char}{self.databits}{self.stopbits}"
+
+        # Build options list
+        options = []
+        if self.local:
+            options.append("local")
+        if not self.kickolduser:
+            options.append("-kickolduser")
+
+        # Ensure device path is absolute
+        device = self.device
+        if not device.startswith("/"):
+            device = f"/dev/lab/{device}"
+
+        connection = {
+            "accepter": f"tcp,{self.tcp_port}",
+            "connector": f"serialdev,{device},{conn_str}",
+            "enable": "on",
+        }
+
+        if options:
+            connection["options"] = {opt: True for opt in options}
+
+        return connection
+
+
+def generate_ser2net_config(
+    ports: list[Ser2NetPort],
+    include_header: bool = True,
+) -> str:
+    """
+    Generate ser2net YAML configuration from port list.
+
+    Args:
+        ports: List of Ser2NetPort configurations
+        include_header: Include YAML header and comments
+
+    Returns:
+        YAML string for /etc/ser2net.yaml
+    """
+    output_lines = []
+
+    if include_header:
+        output_lines.extend(
+            [
+                "%YAML 1.1",
+                "---",
+                "# Lab Controller ser2net configuration",
+                "# Generated by labctl",
+                "#",
+                "# Reload with: sudo systemctl restart ser2net",
+                "# Test with: nc localhost <port>",
+                "",
+            ]
+        )
+
+    # Add each connection
+    for port in ports:
+        parity_char = PARITY_CHARS.get(port.parity.lower(), "n")
+        conn_str = f"{port.baud}{parity_char}{port.databits}{port.stopbits}"
+
+        # Build options - local means only localhost connections
+        local_spec = "localhost," if port.local else ""
+
+        # Ensure device path is absolute (fix for bare device names)
+        device = port.device
+        if not device.startswith("/"):
+            device = f"/dev/lab/{device}"
+
+        output_lines.append(f"connection: &{port.name}")
+        output_lines.append(f"  accepter: tcp,{local_spec}{port.tcp_port}")
+        output_lines.append(f"  connector: serialdev,{device},{conn_str},local")
+        output_lines.append("  enable: on")
+        output_lines.append("  options:")
+        output_lines.append(
+            f"    kickolduser: {'true' if port.kickolduser else 'false'}"
+        )
+        output_lines.append("")
+
+    return "\n".join(output_lines)
+
+
+def load_port_mapping(mapping_file: Path) -> list[dict]:
+    """Load port mapping from YAML file."""
+    with open(mapping_file) as f:
+        data = yaml.safe_load(f)
+    return data.get("ports", [])
+
+
+def generate_from_mapping(
+    mapping_file: Path,
+    base_tcp_port: int = 3000,
+    baud: int = 115200,
+) -> str:
+    """
+    Generate ser2net config from udev port mapping file.
+
+    Args:
+        mapping_file: Path to port-mapping.yaml
+        base_tcp_port: Starting TCP port number
+        baud: Default baud rate
+
+    Returns:
+        ser2net YAML configuration string
+    """
+    ports_data = load_port_mapping(mapping_file)
+
+    ports = []
+    for i, port_info in enumerate(ports_data):
+        name = port_info.get("name")
+        if not name:
+            continue
+
+        port = Ser2NetPort(
+            name=name,
+            device=f"/dev/lab/{name}",
+            tcp_port=base_tcp_port + i,
+            baud=baud,
+        )
+        ports.append(port)
+
+    return generate_ser2net_config(ports)
+
+
+if __name__ == "__main__":
+    # Example usage
+    ports = [
+        Ser2NetPort(
+            name="sbc1-console",
+            device="/dev/lab/sbc1-console",
+            tcp_port=3001,
+            baud=115200,
+        ),
+        Ser2NetPort(
+            name="sbc2-console",
+            device="/dev/lab/sbc2-console",
+            tcp_port=3002,
+            baud=115200,
+        ),
+    ]
+
+    print(generate_ser2net_config(ports))
+
+
+def write_ser2net_config(path: str, content: str) -> None:
+    """Replace the ser2net config at absolute ``path`` with ``content``.
+
+    `ser2net generate --install` may run as root (sudo), with the path
+    taken from ``ser2net.config_file``. Nothing is followed: the directory
+    is opened with no symlink on any component, and an existing file must
+    be a regular file with a single link.
+
+    The write is atomic: a temporary file is created in the same directory
+    (relative to that directory descriptor), given the existing file's
+    owner and mode (0644 for a new one), fsynced, and renamed over the old
+    file. A labctl group member without write access to the directory
+    (/etc) but with it to the file (install-services.sh makes
+    /etc/ser2net.yaml group-writable) can't create the temporary file;
+    the existing file is then rewritten in place instead.
+    """
+    import secrets
+
+    from labctl.core.safe_open import open_dir_nofollow, open_regular_nonblocking
+
+    if not os.path.isabs(path):
+        raise ValueError(f"ser2net config path must be absolute: {path!r}")
+    directory, name = os.path.split(path)
+    data = content.encode()
+    dir_fd = open_dir_nofollow(directory)
+    try:
+        existing = _existing_single_link(name, dir_fd, path, open_regular_nonblocking)
+        if existing is not None and _owner_change_refused(existing, dir_fd):
+            # A temporary file couldn't be given the existing file's owner
+            # (not root, and it is someone else's): rewrite it in place.
+            _rewrite_in_place(name, dir_fd, path, data, open_regular_nonblocking)
+            return
+        tmp_name = f".{name}.labctl-{secrets.token_hex(4)}"
+        try:
+            tmp = os.open(
+                tmp_name,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=dir_fd,
+            )
+        except PermissionError:
+            if existing is None:
+                raise
+            _rewrite_in_place(name, dir_fd, path, data, open_regular_nonblocking)
+            return
+        try:
+            try:
+                if existing is not None and (
+                    os.fstat(tmp).st_uid,
+                    os.fstat(tmp).st_gid,
+                ) != (existing.st_uid, existing.st_gid):
+                    os.fchown(tmp, existing.st_uid, existing.st_gid)
+            except PermissionError:
+                # Predicted above; kept as a backstop.
+                os.close(tmp)
+                tmp = None
+                os.unlink(tmp_name, dir_fd=dir_fd)
+                _rewrite_in_place(name, dir_fd, path, data, open_regular_nonblocking)
+                return
+            mode = existing.st_mode & 0o7777 if existing is not None else 0o644
+            os.fchmod(tmp, mode)
+            _write_all(tmp, data)
+            os.fsync(tmp)
+            os.close(tmp)
+            tmp = None
+            os.rename(tmp_name, name, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+            os.fsync(dir_fd)
+        except BaseException:
+            if tmp is not None:
+                os.close(tmp)
+            try:
+                os.unlink(tmp_name, dir_fd=dir_fd)
+            except FileNotFoundError:
+                pass
+            raise
+    finally:
+        os.close(dir_fd)
+
+
+def check_ser2net_config_writable(path: str) -> None:
+    """Raise as :func:`write_ser2net_config` would if it couldn't write
+    ``path``, changing nothing: the directory opens with no symlink on the
+    way, an existing file is a single-link regular file, and either the
+    directory takes new files (the atomic replace) or the file can be
+    opened for writing (the in-place rewrite)."""
+    from labctl.core.safe_open import open_dir_nofollow, open_regular_nonblocking
+
+    if not os.path.isabs(path):
+        raise ValueError(f"ser2net config path must be absolute: {path!r}")
+    directory, name = os.path.split(path)
+    dir_fd = open_dir_nofollow(directory)
+    try:
+        existing = _existing_single_link(name, dir_fd, path, open_regular_nonblocking)
+        # The same choice write_ser2net_config makes: the atomic replace
+        # when the directory takes new files and the temporary file can be
+        # given the existing file's owner; otherwise the in-place rewrite,
+        # which needs the file itself writable.
+        atomic = os.access(directory, os.W_OK | os.X_OK) and not (
+            existing is not None and _owner_change_refused(existing, dir_fd)
+        )
+        if atomic:
+            return
+        if existing is None:
+            raise PermissionError(errno.EACCES, f"can't create {path}")
+        fd = open_regular_nonblocking(name, os.O_WRONLY, dir_fd=dir_fd)
+        os.close(fd)
+    finally:
+        os.close(dir_fd)
+
+
+def _owner_change_refused(existing: os.stat_result, dir_fd: int) -> bool:
+    """Whether a new file in the directory couldn't be given ``existing``'s
+    owner and group: it would be ours (and the directory's group if it is
+    setgid, else our group), and only root may give a file away or to a
+    group it isn't in."""
+    euid = os.geteuid()
+    if euid == 0:
+        return False
+    dir_st = os.fstat(dir_fd)
+    new_gid = dir_st.st_gid if dir_st.st_mode & stat.S_ISGID else os.getegid()
+    if (existing.st_uid, existing.st_gid) == (euid, new_gid):
+        return False
+    if existing.st_uid != euid:
+        return True
+    return existing.st_gid not in set(os.getgroups()) | {os.getegid()}
+
+
+def _existing_single_link(name, dir_fd, path, opener):
+    """The existing file's stat (None if missing); refuses a symlink, a
+    non-regular file or one with more than one hard link."""
+    try:
+        fd = opener(name, os.O_RDONLY, dir_fd=dir_fd)
+    except FileNotFoundError:
+        return None
+    try:
+        st = os.fstat(fd)
+    finally:
+        os.close(fd)
+    if st.st_nlink != 1:
+        raise OSError(errno.EMLINK, f"{path} has more than one hard link")
+    return st
+
+
+def _rewrite_in_place(name, dir_fd, path, data, opener):
+    fd = opener(name, os.O_WRONLY, dir_fd=dir_fd)
+    try:
+        if os.fstat(fd).st_nlink != 1:
+            raise OSError(errno.EMLINK, f"{path} has more than one hard link")
+        os.ftruncate(fd, 0)
+        _write_all(fd, data)
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _write_all(fd: int, data: bytes) -> None:
+    while data:
+        data = data[os.write(fd, data) :]

labctl/serial/udev.py

@@ -0,0 +1,273 @@
+"""
+Udev rule generation for lab serial devices.
+
+Generates and installs udev rules from the serial_devices database table,
+creating /dev/lab/<name> symlinks for registered USB-serial adapters.
+"""
+
+import re
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from labctl.core.models import SerialDevice
+
+UDEV_RULES_PATH = Path("/etc/udev/rules.d/99-lab-serial.rules")
+
+UDEV_HEADER = """\
+# Lab Controller Serial Device Rules
+# Auto-generated by labctl - do not edit manually
+# Regenerate with: labctl serial udev --install
+#
+# Devices are root:dialout 0660: the labctl services (in dialout) and
+# ser2net (root) open them; users outside dialout reach consoles through
+# ser2net, but can't drive relays or open a console that has no ser2net
+# port (`labctl console` then opens the device itself).
+"""
+
+
+def generate_udev_rules(devices: list["SerialDevice"]) -> str:
+    """Generate udev rules text from a list of serial devices."""
+    lines = [UDEV_HEADER]
+
+    for dev in sorted(devices, key=lambda d: d.name):
+        comment_parts = []
+        if dev.vendor:
+            comment_parts.append(dev.vendor)
+        if dev.model:
+            comment_parts.append(dev.model)
+        comment = f" ({', '.join(comment_parts)})" if comment_parts else ""
+
+        lines.append(f"# {dev.name}{comment}")
+        lines.append(
+            f'SUBSYSTEM=="tty", KERNELS=="{dev.usb_path}", '
+            f'SYMLINK+="lab/{dev.name}", GROUP="dialout", MODE="0660"'
+        )
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+# udev allows whitespace around operators (`SYMLINK += "lab/x"`). The
+# assignment pattern doesn't match the `SYMLINK=="..."` comparison.
+_RULE_SYMLINK_RE = re.compile(r'\bSYMLINK\s*\+?=\s*"([^"]*)"')
+_RULE_KERNELS_RE = re.compile(r'\bKERNELS\s*==\s*"([^"]*)"')
+
+
+def rule_links(rules_text: str) -> dict[str, str | None]:
+    """The ``/dev/lab/<name>`` links a rules file creates: name -> USB path
+    (KERNELS), or None when the rule's USB path can't be parsed. Every
+    ``SYMLINK`` / ``SYMLINK+`` value naming ``lab/<name>`` counts, in any
+    attribute order and among other link names."""
+    links: dict[str, str | None] = {}
+    for line in rules_text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        names = [
+            link[len("lab/") :]
+            for value in _RULE_SYMLINK_RE.findall(line)
+            for link in value.split()
+            if link.startswith("lab/") and len(link) > len("lab/")
+        ]
+        if not names:
+            continue
+        kernels = _RULE_KERNELS_RE.search(line)
+        for name in names:
+            links[name] = kernels.group(1) if kernels else None
+    return links
+
+
+def installed_rule_links(
+    rules_path: Path | None = None,
+) -> dict[str, str | None] | None:
+    """The links the installed rules file creates ({} when there is none
+    yet), or None when it exists but can't be read."""
+    try:
+        return rule_links((rules_path or UDEV_RULES_PATH).read_text())
+    except FileNotFoundError:
+        return {}
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def changed_links(old: dict[str, str | None], new: dict[str, str]) -> set[str]:
+    """Link names that installing ``new`` over ``old`` removes or points
+    at a different USB path; an old link whose USB path couldn't be
+    parsed (None) counts as changed. New names only add links, so they're
+    not included."""
+    return {name for name, usb_path in old.items() if new.get(name) != usb_path}
+
+
+def device_group_note(group: str = "dialout") -> str | None:
+    """What the user running labctl must do to open the root:<group> 0660
+    devices the rules create, or None when nothing. Under sudo that is the
+    invoking user (SUDO_USER), not root; plain root needs nothing, nor does
+    a system without ``group``."""
+    import grp
+    import os
+    import pwd
+
+    try:
+        entry = grp.getgrnam(group)
+    except KeyError:
+        return None
+    gid = entry.gr_gid
+    sudo_user = os.environ.get("SUDO_USER") if os.geteuid() == 0 else None
+    if os.geteuid() == 0 and sudo_user in (None, "root"):
+        return None
+    if sudo_user is None:
+        if gid == os.getegid() or gid in os.getgroups():
+            return None
+        try:
+            account = pwd.getpwuid(os.geteuid())
+        except KeyError:
+            return None
+        user, primary_gid = account.pw_name, account.pw_gid
+    else:
+        try:
+            user, primary_gid = sudo_user, pwd.getpwnam(sudo_user).pw_gid
+        except KeyError:
+            return None
+    member = user in entry.gr_mem or primary_gid == gid
+    if member and sudo_user is not None:
+        return None
+    access = (
+        f"the devices are root:{group} 0660, so you can't open them directly "
+        f"(relays from the CLI, `labctl console` without ser2net) until "
+    )
+    if member:
+        return access + (
+            f"you log in again: {user} was added to {group} after this "
+            f"session started"
+        )
+    return access + (
+        f"{user} joins {group}: sudo usermod -aG {group} {user} (then log in " f"again)"
+    )
+
+
+def install_udev_rules(
+    rules_text: str,
+    rules_path: Path = UDEV_RULES_PATH,
+) -> None:
+    """Write udev rules to the system rules directory.
+
+    Raises PermissionError if unable to write.
+    """
+    rules_path.write_text(rules_text)
+
+
+def reload_udev() -> bool:
+    """Reload udev rules and trigger device re-evaluation.
+
+    Tries direct execution first, falls back to sudo if permission denied.
+    Returns True on success.
+    """
+    for use_sudo in (False, True):
+        try:
+            prefix = ["sudo"] if use_sudo else []
+            subprocess.run(
+                [*prefix, "udevadm", "control", "--reload-rules"],
+                check=True,
+                capture_output=True,
+            )
+            subprocess.run(
+                [*prefix, "udevadm", "trigger", "--subsystem-match=tty"],
+                check=True,
+                capture_output=True,
+            )
+            return True
+        except subprocess.CalledProcessError:
+            if not use_sudo:
+                continue  # Retry with sudo
+            return False
+        except FileNotFoundError:
+            return False
+    return False
+
+
+def discover_usb_serial() -> list[dict]:
+    """Discover connected USB-serial devices by reading /sys.
+
+    Returns a list of dicts with keys:
+        device, path, usb_path, vendor, model, serial
+    """
+    devices = []
+    tty_classes = [Path("/sys/class/tty")]
+
+    for tty_dir in tty_classes:
+        if not tty_dir.exists():
+            continue
+        for entry in sorted(tty_dir.iterdir()):
+            name = entry.name
+            if not (name.startswith("ttyUSB") or name.startswith("ttyACM")):
+                continue
+
+            device_link = entry / "device"
+            if not device_link.exists():
+                continue
+
+            # Walk up to find the USB device path
+            info = _get_udev_info(name)
+            if info and info.get("usb_path"):
+                devices.append(info)
+
+    return devices
+
+
+def _get_udev_info(tty_name: str) -> dict | None:
+    """Get USB device info via udevadm."""
+    try:
+        result = subprocess.run(
+            ["udevadm", "info", "--name", f"/dev/{tty_name}", "--attribute-walk"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return None
+
+        usb_path = None
+        vendor = None
+        model = None
+        serial = None
+
+        # udevadm --attribute-walk starts at the device and walks UP
+        # to the root. We want the first (most specific) match for each field.
+        for line in result.stdout.splitlines():
+            line = line.strip()
+            if line.startswith('KERNELS=="') and not line.startswith('KERNELS=="tty'):
+                val = line.split('"')[1]
+                # USB device paths look like "1-10.1.3"
+                # Skip: PCI paths (0000:), interface descriptors (contain :),
+                # and bare hub paths (no dot = just "1-12")
+                if (
+                    val
+                    and "-" in val
+                    and ":" not in val
+                    and "." in val
+                    and not val.startswith("0000:")
+                    and usb_path is None
+                ):
+                    usb_path = val
+            elif line.startswith('ATTRS{manufacturer}=="') and vendor is None:
+                vendor = line.split('"')[1]
+            elif line.startswith('ATTRS{product}=="') and model is None:
+                model = line.split('"')[1]
+            elif line.startswith('ATTRS{serial}=="') and serial is None:
+                serial = line.split('"')[1]
+
+        if not usb_path:
+            return None
+
+        return {
+            "device": tty_name,
+            "path": f"/dev/{tty_name}",
+            "usb_path": usb_path,
+            "vendor": vendor or "",
+            "model": model or "",
+            "serial": serial or "",
+        }
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return None