ser2netweb 3.0.0__py3-none-any.whl

ser2netweb/console.py

@@ -0,0 +1,181 @@
+"""First-launch console picker for the admin UI bind IP/port.
+
+On first run (or with --reconfigure) we ask, on the terminal, which local IP the
+configuration web UI should listen on — chosen from the machine's own addresses
+(every interface for IPv4, IPv6 or both, loopback, each NIC address) or a custom one.
+Every interface of both families is stored as "" (asyncio's every interface). In a
+non-interactive context (service/headless) we keep the address configured, else
+127.0.0.1 (see choose_admin_bind).
+
+The port offered is tried first (port_in_use): when another program has it — the
+usual case is a second instance on the same machine — the picker says so and offers
+the next free port, but takes a port typed in (it never refuses one: that program may
+be gone by the time this one starts). Without a terminal the port stays as it is, with
+a warning for the log.
+"""
+from __future__ import annotations
+
+import errno
+import os
+import shlex
+import socket
+import sys
+
+from . import envvars, layout
+from .config import AdminUI, host_port, shown_host
+from .engine import bindhint, netinfo
+
+# how far past a taken port the picker looks for a free one
+_FREE_PORT_TRIES = 50
+
+
+def port_in_use(ip: str, port: int) -> bool:
+    """Does another socket listen on ip:port now, so that the admin UI couldn't bind it?
+    Tried as asyncio's create_server binds (uvicorn's listener): SO_REUSEADDR on POSIX,
+    IPV6_V6ONLY for an IPv6 address; the socket is closed at once. Only "address in use"
+    counts: an address this machine doesn't have is not this check's business. "" (every
+    interface of both families) is tried as 0.0.0.0 and as ::, as httpguard.listen binds it."""
+    if not ip:
+        return port_in_use("0.0.0.0", port) or port_in_use("::", port)
+    try:
+        family = socket.AF_INET6 if ":" in ip else socket.AF_INET
+        sock = socket.socket(family, socket.SOCK_STREAM)
+    except OSError:
+        return False
+    with sock:
+        try:
+            if os.name == "posix" and sys.platform != "cygwin":
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            if family == socket.AF_INET6 and hasattr(socket, "IPPROTO_IPV6"):
+                sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
+            sock.bind((ip, port))
+        except OSError as e:
+            # Windows: WSAEADDRINUSE, or WSAEACCES for a port held exclusively / reserved
+            return e.errno == errno.EADDRINUSE or getattr(e, "winerror", None) in (10048, 10013)
+    return False
+
+
+def next_free_port(ip: str, port: int) -> int | None:
+    """The first port after `port` that port_in_use() finds free on `ip`, or None."""
+    for candidate in range(port + 1, min(port + _FREE_PORT_TRIES, 65535) + 1):
+        if not port_in_use(ip, candidate):
+            return candidate
+    return None
+
+
+def in_use_warning(ip: str, port: int) -> str:
+    return (f"WARNING: port {port} on {shown_host(ip)} is in use (another ser2netweb instance or another "
+            "program?) — the web UI can't listen there until it is free. Give this instance "
+            "its own port: --reconfigure, or SER2NETWEB_BIND_IP + SER2NETWEB_PORT")
+
+
+def _quoted(arg: str) -> str:
+    if os.name == "nt":
+        return f'"{arg}"' if " " in arg else arg
+    return shlex.quote(arg)
+
+
+def reconfigure_hint(data_dir: str, service_name: str = "", environ=None) -> tuple[str, str]:
+    """How this installation changes the admin UI's address (for the Settings page):
+    ("env", "") when SER2NETWEB_BIND_IP (or SER2NET_BIND_IP) sets it (a container: its
+    environment wins at every start); ("service", command) for the Windows service, whose
+    reinstall with --reconfigure asks for it again; else ("console", command), a start with
+    --reconfigure."""
+    if envvars.text("SER2NETWEB_BIND_IP", environ):
+        return "env", ""
+    if getattr(sys, "frozen", False):
+        prog = _quoted(sys.executable)
+    elif layout.kind() == layout.PIP:
+        prog = "ser2netweb"  # the command pip / pipx installed
+    else:
+        script = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                              "ser2netweb.py")
+        prog = f"{_quoted(sys.executable)} {_quoted(script)}"
+    if service_name:
+        # (ser2net: 2.x's default service, which --install-service of the default moves over)
+        name = ("" if service_name in ("ser2netweb", "ser2net")
+                else f" --service-name {_quoted(service_name)}")
+        return "service", f"{prog} --install-service --reconfigure{name}"
+    return "console", f"{prog} --reconfigure --data-dir {_quoted(data_dir)}"
+
+
+def choose_admin_bind(current: AdminUI | None = None,
+                      notes: list[str] | None = None) -> tuple[str, int]:
+    """(bind IP, port) for the admin UI, asked on the console. Without a terminal the
+    current (or default) address. A warning for the start-up log goes to `notes` when the
+    port kept is taken."""
+    candidates = netinfo.list_ip_candidates()
+    # (a configured "" is every interface, IPv4 and IPv6: a choice made here before)
+    default_ip = current.bind_ip if current is not None else "127.0.0.1"
+    default_port = (current.port if current else None) or 8080
+
+    if not sys.stdin or not sys.stdin.isatty():
+        # No terminal to prompt at (service/headless). Default to LOOPBACK so the
+        # admin UI is never network-exposed without an explicit choice + password.
+        where = "loopback" if default_ip in ("127.0.0.1", "::1", "localhost") else "as configured"
+        print(f"[ser2netweb] non-interactive console; admin UI bind defaults to "
+              f"{host_port(default_ip, default_port)} ({where}). Run with a terminal or "
+              f"--reconfigure to expose it on the network.", flush=True)
+        if port_in_use(default_ip, default_port):
+            warning = in_use_warning(default_ip, default_port)
+            print(f"[ser2netweb] {warning}", flush=True)
+            if notes is not None:
+                notes.append(warning)
+        return default_ip, default_port
+
+    print("\n=== ser2netweb — configuration interface setup ===")
+    print("Choose which local IP address the web config UI should listen on:\n")
+    for i, c in enumerate(candidates, 1):
+        print(f"  {i}) {c['label']}")
+    print("  C) Custom IP address")
+
+    ip = default_ip
+    while True:
+        raw = input(f"\nSelection [1-{len(candidates)} or C] (default 1): ").strip() or "1"
+        if raw.lower() == "c":
+            custom = input("  Enter custom IP: ").strip()
+            try:
+                ip = netinfo.validate_ip(custom)
+                break
+            except ValueError as e:
+                print(f"  {e}")
+                continue
+        try:
+            idx = int(raw)
+            if 1 <= idx <= len(candidates):
+                ip = candidates[idx - 1]["value"]
+                if ip == netinfo.BOTH_FAMILIES:
+                    ip = ""  # every interface, IPv4 and IPv6 (as asyncio reads "")
+                break
+        except ValueError:
+            pass
+        print("  Invalid selection, try again.")
+
+    if port_in_use(ip, default_port):
+        free = next_free_port(ip, default_port)
+        print(f"  Port {default_port} on {shown_host(ip)} is in use (another ser2netweb instance or another "
+              "program?)" + (f"; {free} is free." if free else "."))
+        default_port = free or default_port
+    while True:
+        raw = input(f"Web UI TCP port [{default_port}]: ").strip() or str(default_port)
+        try:
+            port = int(raw)
+            if 1 <= port <= 65535:
+                break
+        except ValueError:
+            pass
+        print("  Invalid port, try again.")
+    if port_in_use(ip, port):
+        print(f"  NOTE: port {port} on {shown_host(ip)} is in use right now: the web UI can't listen "
+              "there until the program that has it stops.")
+        if notes is not None:
+            notes.append(in_use_warning(ip, port))
+
+    if note := bindhint.admin_port_note(port):
+        print(f"  NOTE: {note.removeprefix('WARNING: ')}")
+    print(f"\n[ser2netweb] Configuration UI will listen on  http://{host_port(ip, port)}")
+    if ip not in ("127.0.0.1", "localhost", "::1"):
+        print("[ser2netweb] NOTE: this is reachable from the network. You will set an "
+              "admin password on first access.")
+    print()
+    return ip, port

ser2netweb/datalock.py

@@ -0,0 +1,181 @@
+"""One running ser2netweb per data directory.
+
+Two instances on the same data directory — a second start while the Windows service or
+the systemd unit runs, --reconfigure next to the running server — would each save their
+own copy of config.json over the other's and lose each other's changes. runtime.main()
+therefore takes an exclusive lock on <data>/ser2net.lock before it writes anything and
+holds it until the server has stopped; a second start on that directory stops with one
+line that names the process holding it. The operating system drops the lock when the
+process ends, however it ends, so a crash leaves no stale lock behind (the file itself
+stays; earlier releases ignore it).
+
+Where the lock can't be taken — a read-only data directory, a network share without
+lock support — the start goes on without it and the start-up log says so.
+POSIX: flock(); Windows: a byte-range lock (msvcrt.locking).
+
+`ser2netweb --set-password` / `--sign-out-all` (ser2netweb/accounts.py) hold the lock too, while
+they change config.json of a stopped ser2netweb: they mark it as brief ("<pid> brief" in
+the file), and a start that finds it held that way waits for them (BRIEF_WAIT_S)
+instead of refusing.
+"""
+from __future__ import annotations
+
+import errno
+import os
+import sys
+import time
+
+LOCK_NAME = "ser2net.lock"
+BRIEF = "brief"        # the lock file's second word: held by a command that exits soon
+BRIEF_WAIT_S = 15.0    # how long a start waits for such a command
+SETTLE_S = 0.5         # ... and for a holder that may not have written its line yet
+# A Windows byte-range lock also keeps other processes from reading that range: lock a
+# byte far past the holder's process id (written at the start of the file), so a start
+# that is refused can still name the holder.
+_WIN_OFFSET = 1 << 30
+_held: dict[str, int] = {}  # data directory -> fd that holds its lock
+
+
+class Held(Exception):
+    """Another process holds the data directory's lock (brief: a --set-password /
+    --sign-out-all that is changing config.json)."""
+
+    def __init__(self, data_dir: str, pid: int | None, brief: bool = False):
+        self.data_dir, self.pid, self.brief = data_dir, pid, brief
+        process = f" (process {pid})" if pid else ""
+        if brief:
+            super().__init__(f"ser2netweb --set-password / --sign-out-all{process} is changing "
+                             f"the data directory {data_dir}")
+        else:
+            super().__init__(f"another ser2netweb{process} is already running with the data "
+                             f"directory {data_dir}")
+
+
+def _lock(fd: int) -> bool:
+    """Lock fd without waiting: True when locked, False when another process holds it.
+    Any other OSError means this file system can't lock."""
+    if sys.platform == "win32":
+        import msvcrt
+
+        os.lseek(fd, _WIN_OFFSET, os.SEEK_SET)
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        except OSError as e:
+            if e.errno in (errno.EACCES, errno.EDEADLK):
+                return False
+            raise
+        return True
+    import fcntl
+
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        return False
+    return True
+
+
+def _unlock(fd: int) -> None:
+    if sys.platform == "win32":
+        import msvcrt
+
+        os.lseek(fd, _WIN_OFFSET, os.SEEK_SET)
+        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+    else:
+        import fcntl
+
+        fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+def _holder(fd: int) -> tuple[int | None, bool]:
+    """(process id, brief) from the holder's line: "<pid>" or "<pid> brief"."""
+    try:
+        os.lseek(fd, 0, os.SEEK_SET)
+        words = os.read(fd, 32).decode("ascii", "replace").split()
+    except OSError:
+        return None, False
+    pid = int(words[0]) if words and words[0].isdigit() else None
+    return pid, words[1:2] == [BRIEF]
+
+
+def _open(path: str) -> tuple[int, bool]:
+    """(fd, writable). Read-only is enough for the lock itself (the process id isn't
+    written then); raises OSError when the file can't be opened at all."""
+    try:
+        return os.open(path, os.O_RDWR | os.O_CREAT, 0o600), True
+    except OSError:
+        if not os.path.isfile(path):
+            raise
+    return os.open(path, os.O_RDONLY), False
+
+
+def acquire(data_dir: str, *, brief: bool = False, wait: float = 0.0) -> str | None:
+    """Hold data_dir's lock until release() or the end of the process. Raises Held when
+    another process holds it; a brief holder is waited for up to `wait` seconds first
+    (one that has not written its line yet: SETTLE_S of them). brief=True marks this
+    holder as brief. Returns a warning for the start-up log when it can't be taken here
+    (the start goes on without it), else None."""
+    data_dir = os.path.abspath(data_dir)
+    if data_dir in _held:
+        return None
+    path = os.path.join(data_dir, LOCK_NAME)
+    start = time.monotonic()
+    while True:
+        try:
+            fd, writable = _open(path)
+        except OSError as e:
+            return (f"WARNING: can't lock the data directory ({path}: {e.strerror or e}) — "
+                    "nothing keeps a second ser2netweb from using it at the same time")
+        try:
+            locked = _lock(fd)
+        except OSError as e:
+            os.close(fd)
+            return (f"WARNING: can't lock the data directory ({path}: locking is not "
+                    f"supported there: {e.strerror or e}) — nothing keeps a second ser2netweb "
+                    "from using it at the same time")
+        if locked:
+            break
+        pid, by_brief = _holder(fd)
+        os.close(fd)
+        if time.monotonic() - start >= (wait if by_brief else min(wait, SETTLE_S)):
+            raise Held(data_dir, pid, by_brief)
+        time.sleep(0.1)
+    if writable:
+        try:
+            os.ftruncate(fd, 0)
+            os.lseek(fd, 0, os.SEEK_SET)
+            os.write(fd, f"{os.getpid()}{' ' + BRIEF if brief else ''}\n".encode("ascii"))
+        except OSError:
+            pass  # the lock holds; only the name in a refusal is lost
+    _held[data_dir] = fd
+    return None
+
+
+def release(data_dir: str) -> None:
+    fd = _held.pop(os.path.abspath(data_dir), None)
+    if fd is not None:
+        os.close(fd)  # closing the file drops the lock
+
+
+def holds(data_dir: str) -> bool:
+    """This process holds data_dir's lock."""
+    return os.path.abspath(data_dir) in _held
+
+
+def holder(data_dir: str) -> int | None:
+    """Without keeping it: the process id holding data_dir's lock (0 when it can't be
+    read), or None when nobody holds it. For --install-service, which must leave the
+    lock to the service it starts."""
+    path = os.path.join(os.path.abspath(data_dir), LOCK_NAME)
+    try:
+        fd = os.open(path, os.O_RDONLY)
+    except OSError:
+        return None  # no lock file: no ser2netweb that locks has run here
+    try:
+        if _lock(fd):
+            _unlock(fd)
+            return None
+        return _holder(fd)[0] or 0
+    except OSError:
+        return None
+    finally:
+        os.close(fd)

ser2netweb/engine/access.py

@@ -0,0 +1,173 @@
+"""Who may use a listening mapping: the per-client policy of the transparent bridge
+(bridge.MappingRunner) and the Modbus gateway (modbus_gateway.ModbusGatewayRunner).
+
+- ``allowed_client_ips``: blank admits every source, otherwise only the listed IPs/CIDRs
+  (an IPv4-mapped IPv6 peer counts as its IPv4 address, an IPv4-mapped entry as the IPv4
+  addresses it maps, and a bare 0.0.0.0 or :: as every source, IPv4 and IPv6); entries
+  that are no address or network (a hand-edited config.json) are left out, and a list
+  with no usable entry at all admits nobody, never everyone;
+- at ``max_connections`` a source in ``priority_client_ips`` always gets in by kicking a
+  client (the oldest non-priority one, else the oldest); any other source gets in only
+  with ``kick_old_user``, by kicking the oldest non-priority client: it never takes a
+  priority client's place, and is refused while only priority clients are connected.
+  Only clients still connected count: one kicked (or otherwise on its way out) is neither
+  counted nor kicked again, so connections that arrive together can't all take the same
+  slot;
+- ``read_only``: a client may watch the device but not change it. Each runner enforces it
+  for its protocol: the bridge never writes a client's bytes to the port (and its RFC2217
+  session refuses line changes), the Modbus gateway answers write requests with an
+  exception instead of putting them on the bus and refuses MQTT/Sparkplug writes.
+
+Also the TLS context of a listener (``network.tls``), the same for both runners.
+"""
+from __future__ import annotations
+
+import contextlib
+import ipaddress
+import itertools
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable, Collection, Iterable, Optional, Protocol
+
+from ..config import ClientNetwork as Network
+from ..config import canonical_ip, client_networks
+from . import tls
+
+if TYPE_CHECKING:
+    import ssl
+
+    from ..config import NetworkSettings
+
+
+class Client(Protocol):
+    """A connected client as the policy sees it."""
+    peer: str            # "ip:port", for the log
+    priority: bool       # admitted as a priority client
+    seq: int             # its place in the order clients connected in (connection_order)
+    connected_at: float  # time.monotonic() when it connected: for how long it has been
+
+    @property
+    def closing(self) -> bool: ...  # kicked, or ending: still listed until it is gone
+
+    def kick(self, reason: str = ...) -> None: ...
+
+
+# a bare wildcard in an IP/CIDR list: every client, of either family
+_ANY: tuple[Network, ...] = (ipaddress.IPv4Network("0.0.0.0/0"), ipaddress.IPv6Network("::/0"))
+_MAPPED = ipaddress.IPv6Network("::ffff:0:0/96")
+
+
+def _unmapped(net: Network) -> Network:
+    """An IPv4-mapped IPv6 network (::ffff:10.0.0.0/120) as the IPv4 network it maps
+    (10.0.0.0/24): a client's IPv4-mapped address is compared as its IPv4 address."""
+    if isinstance(net, ipaddress.IPv6Network) and net.prefixlen >= 96 and net.subnet_of(_MAPPED):
+        return ipaddress.IPv4Network((int(net.network_address) & 0xFFFFFFFF, net.prefixlen - 96))
+    return net
+
+
+_ORDER = itertools.count(1)
+
+
+def connection_order() -> int:
+    """The next number in the order clients connect in (one count for every mapping): which
+    of two clients came first is told by it, never by a clock - a clock set back or
+    forward can't make the newest client the oldest, and two clients that connect within
+    one tick of a coarse clock (about 15.6 ms on Windows) still have an order."""
+    return next(_ORDER)
+
+
+def parse_nets(cidrs: Iterable[Any]) -> list[Network]:
+    """The networks of an IP/CIDR list. A bare wildcard address (0.0.0.0, ::) stands for
+    every client, IPv4 and IPv6 alike (0.0.0.0/0 and ::/0 are each one family); an
+    IPv4-mapped entry for the IPv4 addresses it maps. An entry that is no address or
+    network is left out (config.client_networks: the edits refuse it, the runner names it
+    at start)."""
+    nets: list[Network] = []
+    for c in cidrs or []:
+        text = c if isinstance(c, str) else str(c)
+        with contextlib.suppress(ValueError, TypeError):
+            if "/" not in text and ipaddress.ip_address(canonical_ip(text.strip())).is_unspecified:
+                nets += _ANY
+                continue
+        found, _ignored = client_networks([text])
+        nets += [_unmapped(n) for n in found]
+    return nets
+
+
+def ip_in_nets(ip: str, nets: Collection[Network]) -> bool:
+    if not nets:
+        return False
+    with contextlib.suppress(ValueError):
+        addr = ipaddress.ip_address(ip)
+        # treat IPv4-mapped IPv6 (::ffff:1.2.3.4) as the underlying IPv4
+        if isinstance(addr, ipaddress.IPv6Address) and addr.ipv4_mapped:
+            addr = addr.ipv4_mapped
+        return any(addr in net for net in nets)
+    return False
+
+
+def pick_victim(clients: Collection[Client], priority: bool = True) -> Optional[Client]:
+    """The client to evict to make room for a newcomer: the oldest (first connected)
+    non-priority one. Only a priority newcomer (``priority``) falls back to the oldest
+    client overall; for any other there is none to evict while only priority clients are
+    connected (None)."""
+    pool = [c for c in clients if not c.priority]
+    if not pool and priority:
+        pool = list(clients)
+    return min(pool, key=lambda c: c.seq) if pool else None
+
+
+@dataclass(frozen=True)
+class Admission:
+    """AccessPolicy.admit's verdict on a new connection."""
+    admitted: bool
+    priority: bool = False     # the source is a priority client
+    at_capacity: bool = False  # refused because the mapping already has max_connections
+
+
+class AccessPolicy:
+    def __init__(self, net: NetworkSettings) -> None:
+        self.net = net
+        self._allowed = parse_nets(net.allowed_client_ips)
+        self._priority = parse_nets(net.priority_client_ips)
+        # no allow-list = everyone; one whose entries are all unusable = nobody (the runner
+        # logs which entries it left out at start: MappingConfig.ignored_settings)
+        self._everyone = not net.allowed_client_ips
+
+    def allowed(self, ip: str) -> bool:
+        return self._everyone or ip_in_nets(ip, self._allowed)
+
+    def is_priority(self, ip: str) -> bool:
+        return ip_in_nets(ip, self._priority)
+
+    def admit(self, ip: str, label: str, clients: Collection[Client],
+              log: Callable[[str], None]) -> Admission:
+        """Let a new connection from ``ip`` (``label``: ip:port, for the log) in or not,
+        given the ``clients`` listed now. Kicks one of them to make room when the policy
+        says so; logs each refusal and kick. The caller closes a refused connection, and
+        adds an admitted one to ``clients`` before it awaits anything (so the next
+        connection is decided with this one counted)."""
+        if not self.allowed(ip):
+            log(f"rejected {label}: not in allowed list")
+            return Admission(False)
+        priority = self.is_priority(ip)
+        live = [c for c in clients if not c.closing]  # a kicked one is still listed a while
+        if len(live) >= self.net.max_connections:
+            # A priority client always gets in (kick to make room); a normal client
+            # gets in only if kick_old_user is set, and never in a priority client's place.
+            if not (priority or self.net.kick_old_user):
+                log(f"rejected {label}: max connections reached")
+                return Admission(False, priority, at_capacity=True)
+            victim = pick_victim(live, priority)
+            if victim is None:
+                log(f"rejected {label}: max connections reached (all priority clients)")
+                return Admission(False, priority, at_capacity=True)
+            why = "priority client" if priority else "new client"
+            log(f"kicking {victim.peer} for {why} {label}")
+            victim.kick(f"kicked for {why} {label}")
+        return Admission(True, priority)
+
+
+def server_ssl(net: NetworkSettings) -> Optional[ssl.SSLContext]:
+    """The TLS context of a mapping's TCP listener (None without TLS; engine/tls.py).
+    Raises tls.TlsFileError when its files can't be used."""
+    return tls.mapping_context(net)

ser2netweb/engine/bindhint.py

@@ -0,0 +1,115 @@
+"""Why a listener can't take its port when the system refuses it, and what to do.
+
+On Linux a process that isn't root may listen on a port below
+net.ipv4.ip_unprivileged_port_start (1024 unless changed) only with the
+CAP_NET_BIND_SERVICE capability. The systemd unit runs ser2netweb as such a user, and so
+does the Docker image (uid 10001) on the host network, so Modbus/TCP's 502 or a web UI on
+80 fails with EACCES: "permission denied", with neither the cause nor the fix. On Windows
+the same error (WSAEACCES, 10013) means another program holds the port exclusively, or
+Windows keeps it in an excluded range.
+
+hint() names the case; note() makes it the mapping status's hint (portdiag.Note: the
+dashboard words it in the page's language, the REST API in English); explain() is the
+English line for the logs; admin_port_note() is the start-up warning for an admin UI port
+that this process can't listen on.
+"""
+from __future__ import annotations
+
+import errno
+import os
+import sys
+from typing import Any, Optional
+
+from . import portdiag
+
+PRIVILEGED_PORT = "privileged_port"   # Linux: a port below 1024 without the capability
+EXCLUDED_PORT = "excluded_port"       # Windows: a port another program or Windows keeps
+CAP_NET_BIND_SERVICE = 10             # its bit in the capability sets (linux/capability.h)
+_WSAEACCES = 10013
+
+_EXPLAIN = {
+    PRIVILEGED_PORT: (
+        "ports below {start} need the CAP_NET_BIND_SERVICE capability on Linux (systemd: "
+        "AmbientCapabilities=CAP_NET_BIND_SERVICE; Docker on the host network: "
+        "SER2NETWEB_LOW_PORTS=1), or use port {start} or above (README: Ports below 1024)"),
+    EXCLUDED_PORT: (
+        "Windows doesn't let ser2netweb use this port: another program holds it, or Windows "
+        "reserves it (netsh interface ipv4 show excludedportrange protocol=tcp); pick "
+        "another port"),
+}
+
+
+def unprivileged_port_start() -> int:
+    """The first port a process without the capability may listen on (Linux): 1024 when
+    the setting can't be read (the systemd unit's ProcSubset=pid hides /proc/sys)."""
+    try:
+        with open("/proc/sys/net/ipv4/ip_unprivileged_port_start", encoding="ascii") as fh:
+            return int(fh.read().strip())
+    except (OSError, ValueError):
+        return 1024
+
+
+def _euid() -> int:
+    if sys.platform == "win32":
+        return -1
+    return os.geteuid()
+
+
+def may_bind_low_ports() -> bool:
+    """Linux: whether this process may listen below unprivileged_port_start(): root, or
+    CAP_NET_BIND_SERVICE among its effective capabilities."""
+    if _euid() == 0:
+        return True
+    try:
+        with open("/proc/self/status", encoding="ascii", errors="replace") as fh:
+            for line in fh:
+                if line.startswith("CapEff:"):
+                    return bool(int(line.split()[1], 16) >> CAP_NET_BIND_SERVICE & 1)
+    except (OSError, ValueError, IndexError):
+        pass
+    return False
+
+
+def hint(error: BaseException, port: int, platform: str = sys.platform) -> str:
+    """PRIVILEGED_PORT / EXCLUDED_PORT when the bind of ``port`` failed for that reason,
+    else "". (asyncio keeps the errno when it rewords the error.)"""
+    code = getattr(error, "errno", None)
+    if platform.startswith("linux"):
+        if code == errno.EACCES and 0 < port < unprivileged_port_start():
+            return PRIVILEGED_PORT
+    elif platform == "win32":
+        if code in (errno.EACCES, _WSAEACCES) or getattr(error, "winerror", None) == _WSAEACCES:
+            return EXCLUDED_PORT
+    return ""
+
+
+def for_mapping(error: BaseException, mapping: Any) -> str:
+    """hint() for a mapping that failed to start: only a listener's port counts."""
+    net = getattr(mapping, "network", None)
+    if getattr(mapping, "kind", "") != "net" or not getattr(net, "listens", False):
+        return ""
+    return hint(error, int(getattr(net, "port", 0) or 0))
+
+
+def note(name: str) -> Optional[portdiag.Note]:
+    """The status hint (bridge.RunnerStatus.hint) for a name hint() gave; None for ""."""
+    return portdiag.Note(name) if name else None
+
+
+def explain(name: str) -> str:
+    """The English line for a hint (the logs)."""
+    text = _EXPLAIN.get(name, "")
+    return text.format(start=unprivileged_port_start()) if text else ""
+
+
+def admin_port_note(port: int, platform: str = sys.platform) -> str:
+    """The start-up warning when the admin UI's port is one this process can't listen on
+    (Linux): the web UI would not start (and a service manager restart it again and
+    again). "" otherwise."""
+    if not platform.startswith("linux") or not 0 < port < unprivileged_port_start():
+        return ""
+    if may_bind_low_ports():
+        return ""
+    return (f"WARNING: the admin UI port {port} is below {unprivileged_port_start()}, which "
+            f"this account (uid {_euid()}) can't listen on, so the web UI can't start: "
+            + explain(PRIVILEGED_PORT))