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
import concurrent.futures as cf
import contextlib
import datetime
import errno
import fcntl
import hashlib
import html
......@@ -290,11 +291,204 @@ class MacPlatform(Platform):
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):
sysplat = sysplat or sys.platform
if sysplat == "darwin":
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()
......
......@@ -497,6 +497,145 @@ class PlatformTests(unittest.TestCase):
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
# 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
def test_other_platform_refuses_agent_and_points_at_serve(self):
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