Commit c8f78544 by PLN (Algolia)

devname: run the agent as a systemd user unit on Linux

agent install writes ~/.config/systemd/user/devname.service (system
python3, Restart=on-failure, RestartSec=5 with a 5-in-120s start limit
so a broken unit gives up instead of retrying forever) and enables it.
A preflight refuses to install a unit that would crash-loop: caddy
missing, low ports closed (neither the unprivileged-port sysctl nor
cap_net_bind_service, read from the xattr), or a system caddy.service
holding :80. Hosts without systemd fall back to devname serve.
parent 250c1f85
...@@ -40,6 +40,7 @@ import argparse ...@@ -40,6 +40,7 @@ import argparse
import concurrent.futures as cf import concurrent.futures as cf
import contextlib import contextlib
import datetime import datetime
import errno
import fcntl import fcntl
import hashlib import hashlib
import html import html
...@@ -290,11 +291,204 @@ class MacPlatform(Platform): ...@@ -290,11 +291,204 @@ class MacPlatform(Platform):
return f"agent {LABEL} restarted" return f"agent {LABEL} restarted"
UNPRIV_PORT_FILE = "/proc/sys/net/ipv4/ip_unprivileged_port_start"
CAP_NET_BIND_SERVICE = 10
SYSCTL_DROPIN = "/etc/sysctl.d/60-devname-low-ports.conf"
def file_has_bind_cap(path):
"""Does this binary carry cap_net_bind_service with the effective flag (what `setcap ...=+ep` writes)?
Read straight from the security.capability xattr: no getcap needed. None = cannot tell."""
try:
raw = os.getxattr(os.path.realpath(path), "security.capability")
except AttributeError:
return None # no xattr support in this Python/OS
except OSError as ex:
return False if ex.errno in (errno.ENODATA, getattr(errno, "ENOATTR", errno.ENODATA)) else None
if len(raw) < 8:
return False
magic = int.from_bytes(raw[0:4], "little")
permitted = int.from_bytes(raw[4:8], "little")
return bool(magic & 1) and bool(permitted >> CAP_NET_BIND_SERVICE & 1)
class LinuxPlatform(Platform):
"""systemd --user agent (no root for the daemon). Binding :80/:443 unprivileged needs ONE of:
the sysctl net.ipv4.ip_unprivileged_port_start<=80, or cap_net_bind_service on the caddy binary.
The sysctl opens low ports to every local process, which is why every site keeps its abort-unless-
loopback guard: the guard, not the bind, is what keeps names local."""
name = "linux"
supervisor = "systemd"
running_words = ("active", "not active")
tool_dirs = ("/usr/bin", "/usr/local/bin", "~/.local/bin", "~/go/bin")
unit = "devname.service"
hints = {
"debian": {
"caddy": "sudo apt install caddy (Ubuntu/Debian archive; for current releases use the Caddy apt repo, "
"https://caddyserver.com/docs/install#debian-ubuntu-raspbian). Either way the package starts a "
"SYSTEM caddy.service on :80: sudo systemctl disable --now caddy",
"mkcert": "sudo apt install mkcert libnss3-tools (libnss3-tools = certutil: Firefox/Chrome trust)",
"avahi": "sudo apt install avahi-daemon avahi-utils",
},
"arch": {
"caddy": "sudo pacman -S caddy (ships a system caddy.service; leave it disabled)",
"mkcert": "sudo pacman -S mkcert nss (nss = certutil: Firefox/Chrome trust)",
"avahi": "sudo pacman -S avahi && sudo systemctl enable --now avahi-daemon",
},
"fedora": {
"caddy": "sudo dnf install caddy (ships a system caddy.service; leave it disabled)",
"mkcert": "sudo dnf install mkcert nss-tools",
"avahi": "sudo dnf install avahi-tools",
},
}
def __init__(self, os_release=None, systemd=None):
super().__init__(os_release)
self.systemd = os.path.isdir("/run/systemd/system") if systemd is None else systemd
if not self.systemd:
self.supervisor = None # OpenRC, runit, a container: same as any other Unix
def family(self):
"""debian / arch / fedora / other, from ID + ID_LIKE (ubuntu says ID_LIKE=debian, endeavouros arch)."""
ids = {self.os_release.get("ID", "")} | set(self.os_release.get("ID_LIKE", "").split())
for fam in ("debian", "arch", "fedora"):
if fam in ids or (fam == "debian" and "ubuntu" in ids) or (fam == "fedora" and "rhel" in ids):
return fam
return "other"
def describe(self):
return f"linux ({self.os_release.get('ID', '?')}, {self.family()} family), supervisor: " + (
"systemd --user" if self.systemd else "none, run `devname serve` yourself")
def install_hint(self, tool):
return self.hints.get(self.family(), {}).get(tool, super().install_hint(tool))
def log_hint(self):
return f"journalctl --user -u {self.unit}" if self.systemd else super().log_hint()
def agent_path(self):
if not self.systemd:
return None
base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(HOME, ".config")
return os.path.join(base, "systemd", "user", self.unit)
def agent_text(self):
if not self.systemd:
self._no_agent()
argv = " ".join(f'"{x}"' if " " in x else x for x in self.agent_argv())
env = f"Environment=DEVNAME_HOME={CONF}\n" if os.environ.get("DEVNAME_HOME") else ""
# StartLimit* in [Unit] with RestartSec=5: five failed starts in 120 s and systemd gives up, loudly.
# (A RestartSec >= 2 never reaches the stock 5-in-10s limit: a broken unit would retry forever.)
return f"""[Unit]
Description=devname: stable local names for dev servers (caddy on :80/:443)
StartLimitIntervalSec=120
StartLimitBurst=5
[Service]
ExecStart={argv}
{env}Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target
"""
def systemctl(self, *args):
r = subprocess.run(["systemctl", "--user", *args], capture_output=True, text=True)
if r.returncode:
raise Err(f"systemctl --user {' '.join(args)} failed: " + (r.stderr or "").strip()[-200:])
def agent_running(self):
if not self.systemd:
return None
rc, out = run_out(["systemctl", "--user", "is-active", self.unit])
return rc == 0 and out == "active"
def low_ports(self, caddy):
"""(ok, detail, fix commands): can an unprivileged caddy bind :80/:443?"""
try:
with open(UNPRIV_PORT_FILE) as fh:
start = int(fh.read().strip())
except (OSError, ValueError):
start = None
if start is not None and start <= 80:
return True, (f"low ports open to users (net.ipv4.ip_unprivileged_port_start={start}); "
"the per-site loopback guard keeps names local"), []
if caddy and file_has_bind_cap(caddy):
return True, (f"{os.path.realpath(caddy)} has cap_net_bind_service "
"(setcap is lost when the package upgrades caddy: re-run it then)"), []
target = os.path.realpath(caddy) if caddy else "$(readlink -f $(command -v caddy))"
return False, f"caddy cannot bind :80/:443 unprivileged (ip_unprivileged_port_start={start}, no setcap)", [
f"echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee {SYSCTL_DROPIN} && sudo sysctl -p {SYSCTL_DROPIN}",
f"or: sudo setcap cap_net_bind_service=+ep {target}",
]
def system_caddy(self):
"""(state, fix) when a SYSTEM caddy.service would fight devname for :80, else None.
Debian/Ubuntu's caddy package enables and starts one on install."""
rc, active = run_out(["systemctl", "is-active", "caddy.service"])
if rc is None:
return None
if active == "active":
return "active", "sudo systemctl disable --now caddy"
if run_out(["systemctl", "is-enabled", "caddy.service"])[1] == "enabled":
return "enabled (starts at boot)", "sudo systemctl disable --now caddy"
return None
def linger(self):
"""True/False: does the user manager (and so the agent) start at boot, before any login?"""
rc, out = run_out(["loginctl", "show-user", str(os.getuid()), "--property=Linger", "--value"])
return None if rc != 0 else out == "yes"
def agent_preflight(self):
problems = []
if not CADDY:
problems.append("caddy not found: " + self.install_hint("caddy"))
ok, detail, fixes = self.low_ports(CADDY)
if not ok:
problems.append(detail + ": " + " ; ".join(fixes))
sc = self.system_caddy()
if sc:
problems.append(f"system caddy.service is {sc[0]} and wants :80 too: {sc[1]}")
return problems
def agent_install(self):
text = self.agent_text()
path = self.agent_path()
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as fh:
fh.write(text)
self.systemctl("daemon-reload")
self.systemctl("enable", "--now", self.unit)
msg = f"systemd user unit {self.unit} installed and started ({path})"
if self.linger() is False:
msg += "; it starts at login only, for boot: loginctl enable-linger"
return msg
def agent_uninstall(self):
if not self.systemd:
self._no_agent()
subprocess.run(["systemctl", "--user", "disable", "--now", self.unit], capture_output=True)
with contextlib.suppress(FileNotFoundError):
os.unlink(self.agent_path())
self.systemctl("daemon-reload")
return f"systemd user unit {self.unit} stopped and removed"
def agent_restart(self):
if not self.systemd:
self._no_agent()
self.systemctl("restart", self.unit)
return f"systemd user unit {self.unit} restarted"
def detect_platform(sysplat=None, os_release=None): def detect_platform(sysplat=None, os_release=None):
sysplat = sysplat or sys.platform sysplat = sysplat or sys.platform
if sysplat == "darwin": if sysplat == "darwin":
return MacPlatform() return MacPlatform()
return Platform(os_release if os_release is not None else read_os_release()) rel = os_release if os_release is not None else read_os_release()
if sysplat.startswith("linux"):
return LinuxPlatform(rel)
return Platform(rel)
PLAT = detect_platform() PLAT = detect_platform()
......
...@@ -497,6 +497,145 @@ class PlatformTests(unittest.TestCase): ...@@ -497,6 +497,145 @@ class PlatformTests(unittest.TestCase):
self.assertIn("launchctl bootstrap failed", err) self.assertIn("launchctl bootstrap failed", err)
self.assertEqual(sum(1 for c in self.run.calls if c[1] == "bootstrap"), 2) # the known transient: one retry self.assertEqual(sum(1 for c in self.run.calls if c[1] == "bootstrap"), 2) # the known transient: one retry
# Linux: systemd --user (mocked: systemctl never runs here, the unit lands in a temp XDG_CONFIG_HOME)
UBUNTU = {"ID": "ubuntu", "ID_LIKE": "debian"}
def linux(self, run=None, port_start="80", systemd=True):
plat = self.use(self.dn.LinuxPlatform(self.UBUNTU, systemd=systemd), run)
ports = pathlib.Path(self._tmp.name) / "ip_unprivileged_port_start"
ports.write_text(port_start + "\n")
for target, attrs in ((self.dn, {"UNPRIV_PORT_FILE": str(ports), "CADDY": "/usr/bin/caddy"}),
(os.environ, None)):
p = (mock.patch.multiple(target, **attrs) if attrs else
mock.patch.dict(target, {"XDG_CONFIG_HOME": os.path.join(self.home, ".config")}))
p.start()
self.addCleanup(p.stop)
return plat
def test_detect_linux_and_distro_family(self):
fam = lambda rel: self.dn.LinuxPlatform(rel, systemd=True).family()
self.assertIsInstance(self.dn.detect_platform("linux", os_release=self.UBUNTU), self.dn.LinuxPlatform)
self.assertEqual(fam(self.UBUNTU), "debian")
self.assertEqual(fam({"ID": "debian"}), "debian")
self.assertEqual(fam({"ID": "linuxmint", "ID_LIKE": "ubuntu"}), "debian")
self.assertEqual(fam({"ID": "arch"}), "arch")
self.assertEqual(fam({"ID": "endeavouros", "ID_LIKE": "arch"}), "arch")
self.assertEqual(fam({"ID": "fedora"}), "fedora")
self.assertEqual(fam({"ID": "alpine"}), "other")
self.assertIn("pacman", self.dn.LinuxPlatform({"ID": "arch"}, systemd=True).install_hint("caddy"))
self.assertIn("libnss3-tools", self.dn.LinuxPlatform(self.UBUNTU, systemd=True).install_hint("mkcert"))
self.assertIn("disable --now caddy", self.dn.LinuxPlatform(self.UBUNTU, systemd=True).install_hint("caddy"))
def test_linux_unit_print_writes_nothing(self):
plat = self.linux()
rc, out, err = self.cli("agent", "install", "--print")
self.assertEqual(rc, 0)
for want in ("[Unit]", "[Service]", "[Install]", "WantedBy=default.target", "Restart=on-failure",
"StartLimitBurst=5", " serve\n", os.path.abspath(str(ROOT / "bin" / "devname"))):
self.assertIn(want, out)
self.assertNotIn("launchctl", out)
self.assertNotIn("network-online", out) # a system target: meaningless in a user manager
self.assertTrue(plat.agent_path().startswith(self.home))
self.assertFalse(os.path.exists(plat.agent_path()))
self.assertEqual(self.run.calls, [])
def test_linux_install_refuses_when_low_ports_are_closed(self):
plat = self.linux(port_start="1024")
with mock.patch.object(self.dn, "file_has_bind_cap", return_value=False):
rc, _, err = self.cli("agent", "install")
self.assertEqual(rc, 2)
self.assertIn("crash-loop", err)
self.assertIn("ip_unprivileged_port_start=80", err)
self.assertIn("sudo setcap cap_net_bind_service=+ep", err)
self.assertFalse(os.path.exists(plat.agent_path()))
self.assertFalse(any(c[:2] == ["systemctl", "--user"] and "enable" in c for c in self.run.calls))
def test_linux_install_refuses_while_a_system_caddy_runs(self):
self.linux(FakeRun({("systemctl", "is-active", "caddy.service"): (0, "active")}))
rc, _, err = self.cli("agent", "install")
self.assertEqual(rc, 2)
self.assertIn("sudo systemctl disable --now caddy", err)
def test_linux_install_status_restart_uninstall(self):
run = FakeRun({("systemctl", "is-active", "caddy.service"): (3, "inactive"),
("systemctl", "is-enabled", "caddy.service"): (1, "disabled"),
("systemctl", "--user", "is-active"): (0, "active"),
("loginctl", "show-user"): (0, "no")})
plat = self.linux(run)
rc, _, err = self.cli("agent", "install")
self.assertEqual(rc, 0, err)
self.assertTrue(os.path.exists(plat.agent_path()))
self.assertIn(["systemctl", "--user", "daemon-reload"], run.calls)
self.assertIn(["systemctl", "--user", "enable", "--now", "devname.service"], run.calls)
self.assertIn("enable-linger", err) # linger off: say the agent starts at login only
self.assertEqual(self.cli("agent", "status")[1].strip(), "active")
self.cli("agent", "restart")
self.assertEqual(run.calls[-1], ["systemctl", "--user", "restart", "devname.service"])
self.assertEqual(self.cli("agent", "uninstall")[0], 0)
self.assertFalse(os.path.exists(plat.agent_path()))
self.assertIn(["systemctl", "--user", "disable", "--now", "devname.service"], run.calls)
def test_linux_force_skips_preflight(self):
plat = self.linux(port_start="1024")
with mock.patch.object(self.dn, "file_has_bind_cap", return_value=False):
self.assertEqual(self.cli("agent", "install", "--force")[0], 0)
self.assertTrue(os.path.exists(plat.agent_path()))
def test_linux_systemctl_failure_is_reported(self):
self.linux(FakeRun({("systemctl", "--user", "enable"): (1, ""),
("systemctl", "is-active", "caddy.service"): (3, "inactive")}))
rc, _, err = self.cli("agent", "install")
self.assertEqual(rc, 2)
self.assertIn("systemctl --user enable --now devname.service failed", err)
def test_linux_without_systemd_behaves_like_any_unix(self):
self.linux(systemd=False)
rc, _, err = self.cli("agent", "install")
self.assertEqual(rc, 2)
self.assertIn("devname serve", err)
def test_low_ports_sysctl_setcap_or_fix(self):
plat = self.linux()
ok, detail, fixes = plat.low_ports("/usr/bin/caddy")
self.assertTrue(ok)
self.assertIn("loopback guard", detail) # the sysctl opens low ports to everyone: the guard must stay
(pathlib.Path(self._tmp.name) / "ip_unprivileged_port_start").write_text("1024\n")
with mock.patch.object(self.dn, "file_has_bind_cap", return_value=True):
ok, detail, _ = plat.low_ports("/usr/bin/caddy")
self.assertTrue(ok)
self.assertIn("cap_net_bind_service", detail)
with mock.patch.object(self.dn, "file_has_bind_cap", return_value=False):
ok, detail, fixes = plat.low_ports("/usr/bin/caddy")
self.assertFalse(ok)
self.assertIn("/etc/sysctl.d/", fixes[0])
self.assertTrue(fixes[0].startswith("echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee"))
self.assertIn("setcap cap_net_bind_service=+ep", fixes[1])
def test_file_capability_xattr_parsing(self):
bit = (1 << self.dn.CAP_NET_BIND_SERVICE).to_bytes(4, "little")
rev2 = 0x02000000
cases = [
((rev2 | 1).to_bytes(4, "little") + bit + b"\0" * 12, True), # +ep
(rev2.to_bytes(4, "little") + bit + b"\0" * 12, False), # +p only: a Go binary would not get it
((rev2 | 1).to_bytes(4, "little") + b"\0" * 16, False), # other caps
]
for raw, want in cases:
with mock.patch.object(self.dn.os, "getxattr", return_value=raw, create=True):
self.assertIs(self.dn.file_has_bind_cap("/x"), want)
with mock.patch.object(self.dn.os, "getxattr", side_effect=OSError(self.dn.errno.ENODATA, "no"), create=True):
self.assertIs(self.dn.file_has_bind_cap("/x"), False)
with mock.patch.object(self.dn.os, "getxattr", side_effect=OSError(self.dn.errno.EACCES, "no"), create=True):
self.assertIsNone(self.dn.file_has_bind_cap("/x"))
def test_system_caddy_detection(self):
plat = self.linux(FakeRun({("systemctl", "is-active", "caddy.service"): (3, "inactive"),
("systemctl", "is-enabled", "caddy.service"): (0, "enabled")}))
state, fix = plat.system_caddy()
self.assertIn("enabled", state)
self.assertEqual(fix, "sudo systemctl disable --now caddy")
self.run.table[("systemctl", "is-enabled", "caddy.service")] = (1, "disabled")
self.assertIsNone(plat.system_caddy())
# any other Unix: no supervisor, a clear refusal # any other Unix: no supervisor, a clear refusal
def test_other_platform_refuses_agent_and_points_at_serve(self): def test_other_platform_refuses_agent_and_points_at_serve(self):
self.use(self.dn.Platform({})) self.use(self.dn.Platform({}))
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment