deploy/docs+cleanup: describe symlink model; drop stale scripts/ tracked paths
deploy/README.md: rewrite intro to reflect that deploy/files/ and
deploy/scripts/ are the canonical sources of truth (not examples), with
hardening drop-ins explicitly listed; reference fixtures in
files/usr/local/lib/systemd/system/ noted as such.
spec: add ## Status block marking the deployment-responsibility migration
shipped 2026-05-15.
Cleanup: remove the old scripts/{libexec,sbin,tests}/ paths that were
still tracked after the 2834ad4 move to deploy/scripts/. The content
is already present at deploy/scripts/; these entries were a tracking
artifact from an incomplete git mv.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
mwiegand
parent
2834ad4911
commit
450f9f1591
14 changed files with 38 additions and 805 deletions
|
|
@ -1,48 +1,51 @@
|
|||
# left4me deploy — reference exemplar
|
||||
|
||||
> **This directory is reference material, not the source of truth.**
|
||||
> The canonical deploy of `ovh.left4me` is driven by
|
||||
> [ckn-bw](https://git.sublimity.de/cronekorkn/ckn-bw)'s `bundles/left4me/`
|
||||
> (attached via `groups/applications/left4me.py`); run `bw apply ovh.left4me`
|
||||
> from the ckn-bw repo to deploy.
|
||||
>
|
||||
> The privileged scripts the application installs live under
|
||||
> [`deploy/scripts/libexec/`](scripts/libexec/) and
|
||||
> [`deploy/scripts/sbin/`](scripts/sbin/) — application code that also
|
||||
> lives under `deploy/` for layout consistency. ckn-bw creates target-side
|
||||
> symlinks from `/usr/local/{libexec/left4me,sbin}/` into
|
||||
> **`deploy/files/` is the canonical source of truth** for static deployment
|
||||
> artifacts — sudoers, sysctl drop-in, and hardening drop-ins for the
|
||||
> systemd service units. ckn-bw delivers these via **target-side symlinks**
|
||||
> from their on-host paths into `/opt/left4me/src/deploy/files/...` (safe
|
||||
> because `/opt/left4me/src` is root-owned at runtime; the application cannot
|
||||
> rewrite its own deployment artifacts).
|
||||
>
|
||||
> **`deploy/scripts/` is the canonical source of truth** for privileged
|
||||
> helpers. ckn-bw creates target-side symlinks from
|
||||
> `/usr/local/{libexec/left4me,sbin}/` into
|
||||
> `/opt/left4me/src/deploy/scripts/{libexec,sbin}/` after `git_deploy`.
|
||||
>
|
||||
> What remains under `deploy/files/` and `deploy/templates/` is a set of
|
||||
> readable **examples** — sudoers, sysctl, sandbox-resolv.conf, env
|
||||
> templates, and a curated subset of the systemd units ckn-bw's reactor
|
||||
> emits at apply time. They exist so a fresh consumer (other than ckn-bw)
|
||||
> could read this tree and assemble an equivalent deployment. They are
|
||||
> **not** the bytes ckn-bw installs; ckn-bw carries its own copies of the
|
||||
> verbatim configs in `bundles/left4me/files/etc/`, and emits the live
|
||||
> units from `bundles/left4me/metadata.py`'s `systemd_units` reactor.
|
||||
> What remains under `deploy/files/usr/local/lib/systemd/system/` is a set
|
||||
> of **reference fixtures** — a curated subset of the systemd units ckn-bw's
|
||||
> reactor emits at apply time. They exist so a fresh consumer (other than
|
||||
> ckn-bw) can read this tree and understand the live unit shape, and so that
|
||||
> `deploy/tests/test_example_units.py` can assert the reference matches the
|
||||
> live form. The live base units are emitted by ckn-bw's `systemd/units`
|
||||
> reactor with per-host CPU pinning and worker counts; the reference files
|
||||
> must not include hardening directives (those live in the drop-ins, not the
|
||||
> base units).
|
||||
|
||||
## What's here
|
||||
|
||||
| Path | Role |
|
||||
|---|---|
|
||||
| `files/etc/sudoers.d/left4me` | Example sudoers grants. Lockdown test: `deploy/scripts/tests/test_sudoers_grants.py`. |
|
||||
| `files/etc/sysctl.d/99-left4me.conf` | Example sysctl perf baseline (UDP buffers, fq_codel + BBR). |
|
||||
| `files/etc/left4me/sandbox-resolv.conf` | Example `/etc/resolv.conf` bound into the script-overlay sandbox. |
|
||||
| `files/usr/local/lib/systemd/system/left4me-web.service` | Example of the web-app unit the reactor emits. |
|
||||
| `files/usr/local/lib/systemd/system/left4me-server@.service` | Example of the per-instance gameserver unit. |
|
||||
| `files/usr/local/lib/systemd/system/left4me-workshop-refresh.{service,timer}` | Example of the daily workshop-refresh cron-equivalent. |
|
||||
| `files/usr/local/lib/systemd/system/l4d2-{game,build}.slice` | Example slice definitions (CPU/IO weights). |
|
||||
| `files/etc/sudoers.d/left4me` | **Canonical** sudoers grants. Symlinked to `/etc/sudoers.d/left4me`. CI syntax test: `tests/test_sudoers.py`. |
|
||||
| `files/etc/sysctl.d/99-left4me.conf` | **Canonical** sysctl drop-in (UDP buffers, fq_codel + BBR, `kernel.yama.ptrace_scope=2`). Symlinked to `/etc/sysctl.d/99-left4me.conf`. |
|
||||
| `files/etc/systemd/system/left4me-web.service.d/10-hardening.conf` | **Canonical** hardening drop-in for `left4me-web.service`. Symlinked to the same on-host path. |
|
||||
| `files/etc/systemd/system/left4me-server@.service.d/10-hardening.conf` | **Canonical** hardening drop-in for `left4me-server@.service`. Symlinked to the same on-host path. |
|
||||
| `files/etc/left4me/sandbox-resolv.conf` | Example `/etc/resolv.conf` bound into the script-overlay sandbox (delivered as a bw `files{}` item, not a symlink). |
|
||||
| `files/usr/local/lib/systemd/system/left4me-web.service` | **Reference fixture** — the web-app unit the reactor emits (per-host worker/thread counts omitted). |
|
||||
| `files/usr/local/lib/systemd/system/left4me-server@.service` | **Reference fixture** — the per-instance gameserver unit template the reactor emits. |
|
||||
| `files/usr/local/lib/systemd/system/left4me-workshop-refresh.{service,timer}` | **Reference fixture** — the daily workshop-refresh cron-equivalent. |
|
||||
| `files/usr/local/lib/systemd/system/l4d2-{game,build}.slice` | **Reference fixture** — slice definitions (CPU/IO weights; reactor fills in `AllowedCPUs=` from host metadata). |
|
||||
| `scripts/libexec/{left4me-overlay,left4me-systemctl,left4me-journalctl,left4me-script-sandbox}` | **Canonical** privileged helper commands. Symlinked under `/usr/local/libexec/left4me/`. |
|
||||
| `scripts/sbin/left4me` | **Canonical** admin CLI wrapper. Symlinked to `/usr/local/sbin/left4me`. |
|
||||
| `templates/etc/left4me/host.env` | Example host-library env (deployment-fixed paths). |
|
||||
| `templates/etc/left4me/web.env.template` | Example web-app env. ckn-bw renders the real version via the matching Mako template in `bundles/left4me/files/etc/left4me/web.env.mako`. |
|
||||
| `tests/test_example_units.py` | Locks down the example units & env templates above. |
|
||||
|
||||
The privileged scripts (`left4me-overlay`, `left4me-script-sandbox`,
|
||||
`left4me-systemctl`, `left4me-journalctl`, `sbin/left4me`) used to live
|
||||
under this tree at `files/usr/local/{libexec,sbin}/`; they moved first to
|
||||
`scripts/{libexec,sbin}/` and then to `deploy/scripts/{libexec,sbin}/` for
|
||||
layout consistency (everything ckn-bw deploys to the host now lives under
|
||||
`deploy/`).
|
||||
| `tests/test_example_units.py` | Locks down the reference units and env templates above; also asserts hardening drop-in shape. |
|
||||
| `tests/test_sudoers.py` | Runs `visudo -cf` against the sudoers file in CI. |
|
||||
|
||||
## Target layout
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,11 @@
|
|||
# Deployment responsibility — design
|
||||
|
||||
## Status
|
||||
|
||||
**Shipped 2026-05-15.** All five migration steps landed and verified on
|
||||
ovh.left4me. Implementation plan:
|
||||
`docs/superpowers/plans/2026-05-15-deployment-responsibility.md`.
|
||||
|
||||
## Context
|
||||
|
||||
Trace: `2026-05-06-left4me-deployment-design.md` established the original
|
||||
|
|
|
|||
|
|
@ -1,53 +0,0 @@
|
|||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
usage() {
|
||||
printf '%s\n' "usage: left4me-journalctl <server-name> --lines <n> --follow|--no-follow" >&2
|
||||
exit 2
|
||||
}
|
||||
|
||||
validate_name() {
|
||||
name=$1
|
||||
[ -n "$name" ] || usage
|
||||
case "$name" in
|
||||
.*|*..*|*/*|*\\*) usage ;;
|
||||
esac
|
||||
case "$name" in
|
||||
*[!A-Za-z0-9_.-]*) usage ;;
|
||||
esac
|
||||
}
|
||||
|
||||
[ "$#" -eq 4 ] || usage
|
||||
name=$1
|
||||
lines_flag=$2
|
||||
lines=$3
|
||||
follow_flag=$4
|
||||
|
||||
validate_name "$name"
|
||||
[ "$lines_flag" = "--lines" ] || usage
|
||||
case "$lines" in
|
||||
''|*[!0-9]*) usage ;;
|
||||
esac
|
||||
|
||||
follow_arg=
|
||||
case "$follow_flag" in
|
||||
--follow) follow_arg=-f ;;
|
||||
--no-follow) ;;
|
||||
*) usage ;;
|
||||
esac
|
||||
|
||||
unit="left4me-server@${name}.service"
|
||||
if [ -x /bin/journalctl ]; then
|
||||
journalctl=/bin/journalctl
|
||||
elif [ -x /usr/bin/journalctl ]; then
|
||||
journalctl=/usr/bin/journalctl
|
||||
else
|
||||
printf '%s\n' 'journalctl not found at /bin/journalctl or /usr/bin/journalctl' >&2
|
||||
exit 69
|
||||
fi
|
||||
|
||||
if [ -n "$follow_arg" ]; then
|
||||
exec "$journalctl" -u "$unit" -n "$lines" -o cat "$follow_arg"
|
||||
fi
|
||||
|
||||
exec "$journalctl" -u "$unit" -n "$lines" -o cat
|
||||
|
|
@ -1,244 +0,0 @@
|
|||
#!/usr/bin/python3
|
||||
"""Privileged overlay mount helper for left4me.
|
||||
|
||||
Invoked from the systemd unit's ExecStartPre / ExecStopPost via
|
||||
`+/usr/bin/nsenter --mount=/proc/1/ns/mnt -- …`. The unit-level
|
||||
nsenter is what makes this work: it runs the helper Python interpreter
|
||||
inside PID 1's mount namespace. Without it, the `+` Exec prefix
|
||||
removes the sandbox/credentials but does NOT detach from the unit's
|
||||
per-service mount namespace, and the helper process itself would pin
|
||||
that namespace alive — turning every umount into a multi-second EBUSY
|
||||
race with the kernel's deferred namespace cleanup. With the unit-level
|
||||
nsenter the helper has no such reference and umount succeeds first try.
|
||||
|
||||
Validates inputs strictly, then performs `mount -t overlay` /
|
||||
`umount` directly — no internal nsenter, since the helper is already
|
||||
running where the syscalls need to take effect.
|
||||
|
||||
Verbs:
|
||||
mount <name> Reads ${LEFT4ME_ROOT}/instances/<name>/instance.env
|
||||
for L4D2_LOWERDIRS, validates every lowerdir is
|
||||
under one of installation/overlays/workshop_cache/
|
||||
global_overlay_cache, then mounts the kernel
|
||||
overlay at runtime/<name>/merged.
|
||||
umount <name> Unmounts runtime/<name>/merged and cleans up the
|
||||
kernel-overlayfs `work/work` orphan.
|
||||
|
||||
Set LEFT4ME_OVERLAY_PRINT_ONLY=1 to print the would-be argv (one line,
|
||||
shell-quoted) and exit 0 instead of execv. Used by tests.
|
||||
"""
|
||||
|
||||
import os
|
||||
import re
|
||||
import shlex
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
|
||||
DEFAULT_ROOT = "/var/lib/left4me"
|
||||
LOWERDIR_ALLOWLIST = (
|
||||
"installation",
|
||||
"overlays",
|
||||
"global_overlay_cache",
|
||||
"workshop_cache",
|
||||
)
|
||||
MAX_LOWERDIRS = 500
|
||||
MOUNT_BIN = "/bin/mount"
|
||||
UMOUNT_BIN = "/bin/umount"
|
||||
|
||||
|
||||
def die(msg: str) -> None:
|
||||
sys.stderr.write(f"left4me-overlay: {msg}\n")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def root() -> Path:
|
||||
return Path(os.environ.get("LEFT4ME_ROOT") or DEFAULT_ROOT)
|
||||
|
||||
|
||||
def validate_name(name: str) -> str:
|
||||
if not NAME_RE.fullmatch(name):
|
||||
die(f"invalid instance name: {name!r}")
|
||||
return name
|
||||
|
||||
|
||||
def parse_lowerdirs(env_path: Path) -> list[str]:
|
||||
if not env_path.is_file():
|
||||
die(f"instance.env not found: {env_path}")
|
||||
raw = None
|
||||
for line in env_path.read_text().splitlines():
|
||||
if "=" not in line:
|
||||
continue
|
||||
key, value = line.split("=", 1)
|
||||
if key.strip() == "L4D2_LOWERDIRS":
|
||||
raw = value
|
||||
break
|
||||
if raw is None:
|
||||
die(f"L4D2_LOWERDIRS not set in {env_path}")
|
||||
if raw == "":
|
||||
die(f"L4D2_LOWERDIRS is empty in {env_path}")
|
||||
parts = raw.split(":")
|
||||
if any(p == "" for p in parts):
|
||||
die(f"L4D2_LOWERDIRS contains an empty entry: {raw!r}")
|
||||
if len(parts) > MAX_LOWERDIRS:
|
||||
die(f"L4D2_LOWERDIRS has {len(parts)} entries (cap {MAX_LOWERDIRS})")
|
||||
return parts
|
||||
|
||||
|
||||
def canonical_under(allowed_roots: list[Path], path: Path) -> Path:
|
||||
try:
|
||||
canonical = path.resolve(strict=True)
|
||||
except (FileNotFoundError, RuntimeError):
|
||||
die(f"path does not exist or has a symlink loop: {path}")
|
||||
for r in allowed_roots:
|
||||
if canonical == r or r in canonical.parents:
|
||||
return canonical
|
||||
die(f"path is outside the permitted roots: {path} (resolved: {canonical})")
|
||||
|
||||
|
||||
_LISTXATTR = getattr(os, "listxattr", None)
|
||||
|
||||
|
||||
def _entry_has_fuse_xattr(path: str) -> str | None:
|
||||
if _LISTXATTR is None:
|
||||
return None
|
||||
try:
|
||||
attrs = _LISTXATTR(path, follow_symlinks=False)
|
||||
except OSError:
|
||||
return None
|
||||
for a in attrs:
|
||||
if a.startswith("user.fuseoverlayfs."):
|
||||
return a
|
||||
return None
|
||||
|
||||
|
||||
def assert_no_fuse_xattrs(upper: Path) -> None:
|
||||
if not upper.exists() or _LISTXATTR is None:
|
||||
return
|
||||
for dirpath, dirnames, filenames in os.walk(upper):
|
||||
for entry in (dirpath, *(os.path.join(dirpath, n) for n in dirnames),
|
||||
*(os.path.join(dirpath, n) for n in filenames)):
|
||||
tainted = _entry_has_fuse_xattr(entry)
|
||||
if tainted:
|
||||
die(
|
||||
f"upperdir contains fuse-overlayfs xattr {tainted!r} on {entry}; "
|
||||
"wipe upper/ and work/ before mounting"
|
||||
)
|
||||
|
||||
|
||||
def _print_argv(argv: list[str]) -> None:
|
||||
"""Emit one shell-quoted argv line to stdout (PRINT_ONLY helper, no exit)."""
|
||||
print(" ".join(shlex.quote(a) for a in argv))
|
||||
|
||||
|
||||
def exec_or_print(argv: list[str]) -> None:
|
||||
if os.environ.get("LEFT4ME_OVERLAY_PRINT_ONLY") == "1":
|
||||
_print_argv(argv)
|
||||
sys.exit(0)
|
||||
os.execv(argv[0], argv)
|
||||
|
||||
|
||||
def cmd_mount(name: str) -> None:
|
||||
name = validate_name(name)
|
||||
r = root()
|
||||
runtime_name_dir = (r / "runtime" / name).resolve(strict=True)
|
||||
merged_for_check = (runtime_name_dir / "merged").resolve(strict=True)
|
||||
|
||||
# Idempotency for unit restart cycles: if a previous start mounted
|
||||
# successfully but ExecStart failed afterwards (and Restart=on-failure
|
||||
# fires another cycle), the second ExecStartPre would otherwise refuse
|
||||
# to mount-on-top. Short-circuit here so the second cycle just gets
|
||||
# straight to ExecStart. PRINT_ONLY (test mode) bypasses this so the
|
||||
# tests can exercise the full nsenter argv regardless of mount state.
|
||||
if (
|
||||
os.environ.get("LEFT4ME_OVERLAY_PRINT_ONLY") != "1"
|
||||
and os.path.ismount(merged_for_check)
|
||||
):
|
||||
return
|
||||
|
||||
instance_env = r / "instances" / name / "instance.env"
|
||||
raw_lowerdirs = parse_lowerdirs(instance_env)
|
||||
|
||||
allowed_roots = [(r / sub).resolve() for sub in LOWERDIR_ALLOWLIST]
|
||||
canonical_lowerdirs = [str(canonical_under(allowed_roots, Path(p))) for p in raw_lowerdirs]
|
||||
|
||||
upper = (runtime_name_dir / "upper").resolve(strict=True)
|
||||
work = (runtime_name_dir / "work").resolve(strict=True)
|
||||
merged = merged_for_check
|
||||
for label, path in (("upper", upper), ("work", work), ("merged", merged)):
|
||||
if path.parent != runtime_name_dir:
|
||||
die(f"{label} resolved outside runtime/{name}: {path}")
|
||||
|
||||
assert_no_fuse_xattrs(upper)
|
||||
|
||||
options = f"lowerdir={':'.join(canonical_lowerdirs)},upperdir={upper},workdir={work}"
|
||||
argv = [
|
||||
MOUNT_BIN,
|
||||
"-t", "overlay",
|
||||
"overlay",
|
||||
"-o", options,
|
||||
str(merged),
|
||||
]
|
||||
exec_or_print(argv)
|
||||
|
||||
|
||||
def cmd_umount(name: str) -> None:
|
||||
name = validate_name(name)
|
||||
r = root()
|
||||
runtime_name_dir = (r / "runtime" / name).resolve(strict=True)
|
||||
merged_path = runtime_name_dir / "merged"
|
||||
work_inner = runtime_name_dir / "work" / "work"
|
||||
|
||||
overlay_umount_argv = [
|
||||
UMOUNT_BIN,
|
||||
# Resolve only if it exists; PRINT_ONLY tests always pre-create it.
|
||||
str(merged_path.resolve(strict=True) if merged_path.exists() else merged_path),
|
||||
]
|
||||
|
||||
if os.environ.get("LEFT4ME_OVERLAY_PRINT_ONLY") == "1":
|
||||
_print_argv(overlay_umount_argv)
|
||||
sys.exit(0)
|
||||
|
||||
if merged_path.exists():
|
||||
merged = merged_path.resolve(strict=True)
|
||||
if merged.parent != runtime_name_dir:
|
||||
die(f"merged resolved outside runtime/{name}: {merged}")
|
||||
# Idempotency: only umount if currently a mount point. Mirrors
|
||||
# cmd_mount's symmetric check; a redundant cleanup pass — or a
|
||||
# call after a partial _purge_instance — must be a no-op.
|
||||
#
|
||||
# No retry loop here: with the helper running in PID 1's mount
|
||||
# namespace (via the unit-level `nsenter --mount=/proc/1/ns/mnt`
|
||||
# in ExecStopPost), it holds no reference to the unit's
|
||||
# per-service mount namespace, so the cgroup-empty → namespace
|
||||
# reaped → umount-clears sequence happens without any race
|
||||
# window for us to ride out. EBUSY here is a real error.
|
||||
if os.path.ismount(merged):
|
||||
subprocess.run(overlay_umount_argv, check=True)
|
||||
|
||||
# Kernel-overlayfs creates work_inner during mount with root:root mode
|
||||
# 0/0. After unmount it's an orphan that the unit's User= (left4me)
|
||||
# cannot traverse via shutil.rmtree, so reset/delete in instances.py
|
||||
# blows up with EACCES on `runtime/<name>/work/work`. The helper is
|
||||
# the only code path with root that knows about this directory, so
|
||||
# the cleanup belongs here. Safe to nuke — the kernel re-creates it
|
||||
# on the next mount. Run unconditionally — covers both "we just
|
||||
# unmounted" and "previous teardown didn't finish" cases.
|
||||
if work_inner.exists():
|
||||
shutil.rmtree(work_inner)
|
||||
|
||||
|
||||
def main(argv: list[str]) -> None:
|
||||
if len(argv) != 3 or argv[1] not in ("mount", "umount"):
|
||||
sys.stderr.write("usage: left4me-overlay mount|umount <name>\n")
|
||||
sys.exit(2)
|
||||
if argv[1] == "mount":
|
||||
cmd_mount(argv[2])
|
||||
else:
|
||||
cmd_umount(argv[2])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main(sys.argv)
|
||||
|
|
@ -1,81 +0,0 @@
|
|||
#!/bin/bash
|
||||
# Privileged sandbox launcher for left4me script overlays.
|
||||
#
|
||||
# Invoked via sudo by the web user with two arguments:
|
||||
# <overlay_id> numeric overlay id; bind-mounts /var/lib/left4me/overlays/<id>
|
||||
# read-write at /overlay inside the sandbox.
|
||||
# <script_path> absolute path to a bash file already written by the web app;
|
||||
# bind-mounted read-only at /script.sh inside the sandbox.
|
||||
#
|
||||
# The script runs as a transient systemd .service with the full hardening
|
||||
# surface: cgroup limits + walltime kill, NoNewPrivileges, ProtectSystem,
|
||||
# ProtectHome, kernel-tunable / -module / -log protection, namespace
|
||||
# restriction, address-family restriction, capability bounding (empty),
|
||||
# seccomp filter (@system-service @network-io), MemoryDenyWriteExecute,
|
||||
# LockPersonality, RestrictSUIDSGID. Network namespace is *not* restricted —
|
||||
# scripts must reach the public internet to download workshop / l4d2center
|
||||
# / cedapug content. PID namespace is shared with the host (no
|
||||
# PrivatePID= directive in systemd); host PIDs are visible via /proc.
|
||||
# Same-uid attack surface (the sandbox runs as left4me, so do the
|
||||
# gameservers and the web app) is covered by the hardening profile plus
|
||||
# system-wide kernel.yama.ptrace_scope=2 — see
|
||||
# docs/superpowers/specs/2026-05-15-hardening-threat-model.md.
|
||||
set -euo pipefail
|
||||
|
||||
# Self-wrap into PID 1's mount namespace before doing anything mount-related.
|
||||
# The web app's left4me-web.service has PrivateTmp=true, which gives it a
|
||||
# private mount namespace. When the worker invokes us via sudo, we inherit
|
||||
# that namespace; our `mount --bind` would land there. systemd-run below
|
||||
# spawns transient units in PID 1's namespace (where they don't see the
|
||||
# private bind), so the sandbox would bind onto an empty staging dir and
|
||||
# permission-deny on every write. The sentinel env var avoids an exec loop.
|
||||
if [[ "${L4D2_SANDBOX_IN_PID1_MNT_NS:-}" != "1" ]]; then
|
||||
exec env L4D2_SANDBOX_IN_PID1_MNT_NS=1 \
|
||||
/usr/bin/nsenter --mount=/proc/1/ns/mnt -- "$0" "$@"
|
||||
fi
|
||||
|
||||
[[ $# -eq 2 ]] || { echo "usage: $0 <overlay_id> <script>" >&2; exit 64; }
|
||||
|
||||
OVERLAY_ID=$1
|
||||
SCRIPT=$2
|
||||
|
||||
[[ "$OVERLAY_ID" =~ ^[0-9]+$ ]] || { echo "bad overlay id" >&2; exit 64; }
|
||||
OVERLAY_DIR=/var/lib/left4me/overlays/$OVERLAY_ID
|
||||
[[ -d $OVERLAY_DIR ]] || { echo "no overlay dir at $OVERLAY_DIR" >&2; exit 65; }
|
||||
[[ -f $SCRIPT ]] || { echo "no script at $SCRIPT" >&2; exit 65; }
|
||||
|
||||
if [[ "${LEFT4ME_SCRIPT_SANDBOX_DRY_RUN:-}" == "1" ]]; then
|
||||
echo "DRY RUN: overlay_id=$OVERLAY_ID script=$SCRIPT overlay_dir=$OVERLAY_DIR"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
SCRIPT_RC=0
|
||||
systemd-run --quiet --collect --wait --pipe \
|
||||
--unit="left4me-script-${OVERLAY_ID}-$$" \
|
||||
--slice=l4d2-build.slice \
|
||||
-p OOMScoreAdjust=500 \
|
||||
-p User=left4me -p Group=left4me \
|
||||
-p UMask=0022 \
|
||||
-p NoNewPrivileges=yes \
|
||||
-p ProtectSystem=strict -p ProtectHome=yes \
|
||||
-p PrivateTmp=yes -p PrivateDevices=yes -p PrivateIPC=yes \
|
||||
-p ProtectKernelTunables=yes -p ProtectKernelModules=yes \
|
||||
-p ProtectKernelLogs=yes -p ProtectControlGroups=yes \
|
||||
-p RestrictNamespaces=yes \
|
||||
-p RestrictAddressFamilies="AF_INET AF_INET6 AF_UNIX" \
|
||||
-p RestrictSUIDSGID=yes -p LockPersonality=yes \
|
||||
-p MemoryDenyWriteExecute=yes \
|
||||
-p SystemCallFilter="@system-service @network-io" \
|
||||
-p SystemCallArchitectures=native \
|
||||
-p CapabilityBoundingSet= -p AmbientCapabilities= \
|
||||
-p IPAddressDeny="127.0.0.0/8 ::1/128 169.254.0.0/16 fe80::/10 224.0.0.0/4 ff00::/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 100.64.0.0/10 fc00::/7" \
|
||||
-p TemporaryFileSystem="/etc /var/lib" \
|
||||
-p BindReadOnlyPaths="/etc/left4me/sandbox-resolv.conf:/etc/resolv.conf /etc/ssl /etc/ca-certificates /etc/nsswitch.conf /etc/alternatives ${SCRIPT}:/script.sh" \
|
||||
-p BindPaths="${OVERLAY_DIR}:/overlay" \
|
||||
-p WorkingDirectory=/overlay \
|
||||
-p Environment="HOME=/tmp PATH=/usr/bin:/usr/sbin OVERLAY=/overlay" \
|
||||
-p MemoryMax=4G -p MemorySwapMax=0 -p TasksMax=512 \
|
||||
-p CPUQuota=200% -p RuntimeMaxSec=3600 \
|
||||
-- /bin/bash /script.sh || SCRIPT_RC=$?
|
||||
|
||||
exit $SCRIPT_RC
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
usage() {
|
||||
printf '%s\n' "usage: left4me-systemctl enable|disable|show <server-name>" >&2
|
||||
exit 2
|
||||
}
|
||||
|
||||
validate_name() {
|
||||
name=$1
|
||||
[ -n "$name" ] || usage
|
||||
case "$name" in
|
||||
.*|*..*|*/*|*\\*) usage ;;
|
||||
esac
|
||||
case "$name" in
|
||||
*[!A-Za-z0-9_.-]*) usage ;;
|
||||
esac
|
||||
}
|
||||
|
||||
[ "$#" -eq 2 ] || usage
|
||||
action=$1
|
||||
name=$2
|
||||
|
||||
case "$action" in
|
||||
enable|disable|show) ;;
|
||||
*) usage ;;
|
||||
esac
|
||||
|
||||
validate_name "$name"
|
||||
unit="left4me-server@${name}.service"
|
||||
if [ -x /bin/systemctl ]; then
|
||||
systemctl=/bin/systemctl
|
||||
elif [ -x /usr/bin/systemctl ]; then
|
||||
systemctl=/usr/bin/systemctl
|
||||
else
|
||||
printf '%s\n' 'systemctl not found at /bin/systemctl or /usr/bin/systemctl' >&2
|
||||
exit 69
|
||||
fi
|
||||
|
||||
case "$action" in
|
||||
enable) exec "$systemctl" enable --now "$unit" ;;
|
||||
disable) exec "$systemctl" disable --now "$unit" ;;
|
||||
show) exec "$systemctl" show --property=ActiveState --property=SubState "$unit" ;;
|
||||
esac
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
#!/bin/sh
|
||||
# Run l4d2web flask CLI commands as the left4me user with the deploy env loaded.
|
||||
# Usage: left4me <flask-subcommand> [args...]
|
||||
# Examples:
|
||||
# left4me create-user alice --admin
|
||||
# left4me seed-script-overlays /opt/left4me/src/examples/script-overlays
|
||||
# left4me routes
|
||||
set -eu
|
||||
exec sudo -u left4me sh -c '
|
||||
set -a
|
||||
. /etc/left4me/host.env
|
||||
. /etc/left4me/web.env
|
||||
set +a
|
||||
export JOB_WORKER_ENABLED=false
|
||||
export PYTHONPATH=/opt/left4me/src
|
||||
exec /var/lib/left4me/.venv/bin/flask --app l4d2web.app:create_app "$@"
|
||||
' sh "$@"
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
"""Shared fixtures and path constants for `scripts/tests/`."""
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[2]
|
||||
SCRIPTS = ROOT / "scripts"
|
||||
LIBEXEC = SCRIPTS / "libexec"
|
||||
SBIN = SCRIPTS / "sbin"
|
||||
|
||||
# `deploy/` is reference material; the sudoers example lives there and is
|
||||
# the canonical statement of which paths sudo grants to the `left4me` uid.
|
||||
# `scripts/tests/test_sudoers_grants.py` reads it from across the dir
|
||||
# boundary because the contract being audited is about *scripts*, not deploy.
|
||||
DEPLOY = ROOT / "deploy"
|
||||
|
||||
|
||||
def fake_command(tmp_path, command_name):
|
||||
"""Drop a no-op stub of `command_name` into `tmp_path`. Returns the
|
||||
marker file the stub writes its args to, so tests can assert that the
|
||||
helper rejected bad input before invoking the real command.
|
||||
"""
|
||||
marker = tmp_path / f"{command_name}.args"
|
||||
command = tmp_path / command_name
|
||||
command.write_text(f"#!/bin/sh\nprintf '%s\\n' \"$*\" > '{marker}'\nexit 0\n")
|
||||
command.chmod(0o755)
|
||||
return marker
|
||||
|
||||
|
||||
def env_with_fake_commands(tmp_path):
|
||||
"""Build an environment that prepends `tmp_path` onto PATH so helpers
|
||||
find the fake commands first.
|
||||
"""
|
||||
env = os.environ.copy()
|
||||
env["PATH"] = f"{tmp_path}{os.pathsep}{env.get('PATH', '')}"
|
||||
return env
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
from conftest import LIBEXEC
|
||||
|
||||
|
||||
SYSTEMCTL_HELPER = LIBEXEC / "left4me-systemctl"
|
||||
JOURNALCTL_HELPER = LIBEXEC / "left4me-journalctl"
|
||||
|
||||
|
||||
def test_helpers_use_fixed_system_tool_paths_not_sudo_path():
|
||||
systemctl = SYSTEMCTL_HELPER.read_text()
|
||||
journalctl = JOURNALCTL_HELPER.read_text()
|
||||
|
||||
assert "command -v systemctl" not in systemctl
|
||||
assert "command -v journalctl" not in journalctl
|
||||
assert "/bin/systemctl" in systemctl or "/usr/bin/systemctl" in systemctl
|
||||
assert "/bin/journalctl" in journalctl or "/usr/bin/journalctl" in journalctl
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
import subprocess
|
||||
|
||||
from conftest import LIBEXEC, env_with_fake_commands, fake_command
|
||||
|
||||
|
||||
JOURNALCTL_HELPER = LIBEXEC / "left4me-journalctl"
|
||||
|
||||
|
||||
def test_journalctl_helper_passes_shell_syntax_check_and_rejects_bad_args(tmp_path):
|
||||
subprocess.run(["sh", "-n", str(JOURNALCTL_HELPER)], check=True)
|
||||
marker = fake_command(tmp_path, "journalctl")
|
||||
|
||||
for args in [
|
||||
["../evil", "--lines", "25", "--no-follow"],
|
||||
["alpha", "--bad", "25", "--no-follow"],
|
||||
["alpha", "--lines", "not-number", "--no-follow"],
|
||||
["alpha", "--lines", "25", "--bad-follow"],
|
||||
["bad/name", "--lines", "25", "--no-follow"],
|
||||
]:
|
||||
result = subprocess.run(
|
||||
["sh", str(JOURNALCTL_HELPER), *args],
|
||||
env=env_with_fake_commands(tmp_path),
|
||||
check=False,
|
||||
)
|
||||
assert result.returncode != 0
|
||||
assert not marker.exists()
|
||||
|
||||
script = JOURNALCTL_HELPER.read_text()
|
||||
assert 'unit="left4me-server@${name}.service"' in script
|
||||
assert 'exec "$journalctl" -u "$unit" -n "$lines" -o cat "$follow_arg"' in script
|
||||
assert 'exec "$journalctl" -u "$unit" -n "$lines" -o cat' in script
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
from conftest import LIBEXEC
|
||||
|
||||
|
||||
OVERLAY_HELPER = LIBEXEC / "left4me-overlay"
|
||||
|
||||
|
||||
def test_overlay_helper_is_python_with_strict_validation():
|
||||
text = OVERLAY_HELPER.read_text()
|
||||
assert text.startswith("#!/usr/bin/python3")
|
||||
# Validation surface
|
||||
assert "NAME_RE = re.compile" in text
|
||||
assert "LOWERDIR_ALLOWLIST" in text
|
||||
assert "user.fuseoverlayfs." in text
|
||||
assert "MAX_LOWERDIRS = 500" in text
|
||||
# Mounts via PID 1's mount namespace
|
||||
assert "/proc/1/ns/mnt" in text
|
||||
assert "nsenter" in text
|
||||
# Verbs are mount and umount (not unmount)
|
||||
assert '"mount"' in text and '"umount"' in text
|
||||
assert '"unmount"' not in text
|
||||
|
||||
|
||||
def test_overlay_helper_mount_is_idempotent_when_already_mounted():
|
||||
"""ExecStartPre runs on every Restart=on-failure cycle. If a previous
|
||||
start mounted successfully but ExecStart failed afterwards, the next
|
||||
ExecStartPre would re-mount on top -- which fails. The helper must
|
||||
short-circuit when merged is already a mount point.
|
||||
"""
|
||||
text = OVERLAY_HELPER.read_text()
|
||||
# Two ismount checks now: one in cmd_mount (skip if mounted),
|
||||
# one in cmd_umount (skip if not mounted).
|
||||
assert text.count("os.path.ismount") >= 2
|
||||
|
|
@ -1,146 +0,0 @@
|
|||
import subprocess
|
||||
|
||||
from conftest import LIBEXEC
|
||||
|
||||
|
||||
SCRIPT_SANDBOX_HELPER = LIBEXEC / "left4me-script-sandbox"
|
||||
|
||||
|
||||
def test_script_sandbox_helper_present():
|
||||
assert SCRIPT_SANDBOX_HELPER.is_file()
|
||||
assert SCRIPT_SANDBOX_HELPER.read_text().startswith("#!/bin/bash")
|
||||
mode = SCRIPT_SANDBOX_HELPER.stat().st_mode & 0o777
|
||||
assert mode == 0o755, f"expected 0755, got {oct(mode)}"
|
||||
|
||||
|
||||
def test_script_sandbox_helper_passes_shell_syntax_check():
|
||||
subprocess.run(["bash", "-n", str(SCRIPT_SANDBOX_HELPER)], check=True)
|
||||
|
||||
|
||||
def test_script_sandbox_helper_invokes_systemd_run_with_hardening():
|
||||
text = SCRIPT_SANDBOX_HELPER.read_text()
|
||||
|
||||
# systemd-run service mode (no --scope), with synchronous I/O to caller.
|
||||
assert "systemd-run" in text
|
||||
assert "--scope" not in text, "v2 uses transient service units, not scopes"
|
||||
assert "--pipe" in text
|
||||
assert "--wait" in text
|
||||
assert "--collect" in text
|
||||
assert "--unit=" in text
|
||||
|
||||
# No bwrap.
|
||||
assert "bwrap" not in text
|
||||
assert "bubblewrap" not in text
|
||||
|
||||
# UID drop via systemd directives.
|
||||
assert "User=left4me" in text
|
||||
assert "Group=left4me" in text
|
||||
|
||||
# Cgroup limits unchanged from v1.
|
||||
assert "MemoryMax=4G" in text
|
||||
assert "MemorySwapMax=0" in text
|
||||
assert "TasksMax=512" in text
|
||||
assert "CPUQuota=200%" in text
|
||||
assert "RuntimeMaxSec=3600" in text
|
||||
|
||||
# Hardening directives that v1 (scope mode) couldn't carry.
|
||||
assert "NoNewPrivileges=yes" in text
|
||||
assert "ProtectSystem=strict" in text
|
||||
assert "ProtectHome=yes" in text
|
||||
assert "PrivateTmp=yes" in text
|
||||
assert "PrivateDevices=yes" in text
|
||||
assert "PrivateIPC=yes" in text
|
||||
assert "ProtectKernelTunables=yes" in text
|
||||
assert "ProtectKernelModules=yes" in text
|
||||
assert "ProtectKernelLogs=yes" in text
|
||||
assert "ProtectControlGroups=yes" in text
|
||||
assert "RestrictNamespaces=yes" in text
|
||||
assert "RestrictSUIDSGID=yes" in text
|
||||
assert "LockPersonality=yes" in text
|
||||
assert "MemoryDenyWriteExecute=yes" in text
|
||||
assert "SystemCallFilter=" in text
|
||||
assert "@system-service" in text
|
||||
assert "@network-io" in text
|
||||
assert "CapabilityBoundingSet=" in text
|
||||
assert "AmbientCapabilities=" in text
|
||||
assert 'RestrictAddressFamilies="AF_INET AF_INET6 AF_UNIX"' in text
|
||||
|
||||
# Network namespace stays shared with host.
|
||||
assert "PrivateNetwork=" not in text
|
||||
|
||||
# Mount setup: /etc and /var/lib masked with tmpfs; selective binds back.
|
||||
assert 'TemporaryFileSystem="/etc /var/lib"' in text
|
||||
assert "BindReadOnlyPaths=" in text
|
||||
# The resolv.conf bind points at the sandbox-only file (not the host's
|
||||
# /etc/resolv.conf, which typically references a private-IP DNS server
|
||||
# that IPAddressDeny= blocks).
|
||||
assert "/etc/left4me/sandbox-resolv.conf:/etc/resolv.conf" in text
|
||||
assert "/etc/ssl" in text
|
||||
assert "/etc/ca-certificates" in text
|
||||
assert "/etc/nsswitch.conf" in text
|
||||
assert "/etc/alternatives" in text
|
||||
assert "${SCRIPT}:/script.sh" in text
|
||||
assert 'BindPaths="${OVERLAY_DIR}:/overlay"' in text
|
||||
|
||||
# IP egress filter: allow public, deny localhost / RFC1918 / link-local /
|
||||
# multicast / CGNAT / ULA. systemd's "more specific rule wins" semantics
|
||||
# mean public IPs hit the allow and listed ranges hit the deny.
|
||||
# IPAddressDeny alone — no IPAddressAllow=any. Empirically, having both
|
||||
# set causes the allow to win on this systemd/kernel combo regardless of
|
||||
# the documented "more specific rule wins" behaviour. With only Deny,
|
||||
# the kernel's default "allow all" applies to non-listed addresses.
|
||||
assert "IPAddressDeny=" in text
|
||||
assert "IPAddressAllow=any" not in text
|
||||
# Explicit CIDRs — systemd-run's -p parser doesn't accept the
|
||||
# `localhost` / `link-local` / `multicast` shorthand keywords that
|
||||
# work in unit files (only the full strings parse).
|
||||
for token in (
|
||||
"127.0.0.0/8",
|
||||
"::1/128",
|
||||
"169.254.0.0/16",
|
||||
"fe80::/10",
|
||||
"224.0.0.0/4",
|
||||
"ff00::/8",
|
||||
"10.0.0.0/8",
|
||||
"172.16.0.0/12",
|
||||
"192.168.0.0/16",
|
||||
"100.64.0.0/10",
|
||||
"fc00::/7",
|
||||
):
|
||||
assert token in text, f"missing {token!r} in IPAddressDeny set"
|
||||
|
||||
|
||||
def test_script_sandbox_in_build_slice_with_oom_adjust():
|
||||
text = SCRIPT_SANDBOX_HELPER.read_text()
|
||||
|
||||
# Put the transient unit in the low-weight build slice so it yields to
|
||||
# game-server instances under CPU/IO contention.
|
||||
assert "--slice=l4d2-build.slice" in text
|
||||
|
||||
# Sandbox dies first if the host hits memory pressure; servers
|
||||
# (OOMScoreAdjust=-200) survive.
|
||||
assert "-p OOMScoreAdjust=500" in text
|
||||
|
||||
|
||||
def test_script_sandbox_helper_validates_overlay_id():
|
||||
text = SCRIPT_SANDBOX_HELPER.read_text()
|
||||
# Numeric-only overlay id
|
||||
assert '[[ "$OVERLAY_ID" =~ ^[0-9]+$ ]]' in text
|
||||
# Overlay dir must exist
|
||||
assert "/var/lib/left4me/overlays/" in text
|
||||
assert "[[ -d $OVERLAY_DIR ]]" in text
|
||||
# Script path must exist
|
||||
assert "[[ -f $SCRIPT ]]" in text
|
||||
|
||||
|
||||
def test_script_sandbox_helper_dry_run_mode(tmp_path):
|
||||
overlay_root = tmp_path / "var/lib/left4me/overlays/42"
|
||||
overlay_root.mkdir(parents=True)
|
||||
fake_script = tmp_path / "fake.sh"
|
||||
fake_script.write_text("echo hi")
|
||||
|
||||
helper_text = SCRIPT_SANDBOX_HELPER.read_text()
|
||||
# We can't actually exec this without root; just verify the dry-run
|
||||
# guard short-circuits before systemd-run runs.
|
||||
assert 'LEFT4ME_SCRIPT_SANDBOX_DRY_RUN' in helper_text
|
||||
assert 'exit 0' in helper_text
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
"""Audit the script→sudoers contract.
|
||||
|
||||
The sudoers file in `deploy/files/etc/sudoers.d/left4me` is a reference
|
||||
example; ckn-bw ships its own verbatim copy under
|
||||
`bundles/left4me/files/etc/sudoers.d/left4me`. The two are expected to
|
||||
match. This test lives under `scripts/tests/` because the contract being
|
||||
audited is about *scripts* (which paths the `left4me` uid can sudo into)
|
||||
even though the file it reads is in `deploy/`.
|
||||
"""
|
||||
from conftest import DEPLOY
|
||||
|
||||
|
||||
SUDOERS = DEPLOY / "files/etc/sudoers.d/left4me"
|
||||
|
||||
|
||||
def test_sudoers_allows_only_left4me_helpers_not_raw_system_tools():
|
||||
sudoers = SUDOERS.read_text()
|
||||
|
||||
assert (
|
||||
"left4me ALL=(root) NOPASSWD: "
|
||||
"/usr/local/libexec/left4me/left4me-systemctl *"
|
||||
) in sudoers
|
||||
assert (
|
||||
"left4me ALL=(root) NOPASSWD: "
|
||||
"/usr/local/libexec/left4me/left4me-journalctl *"
|
||||
) in sudoers
|
||||
assert "/usr/local/libexec/left4me/left4me-overlay mount *" in sudoers
|
||||
assert "/usr/local/libexec/left4me/left4me-overlay umount *" in sudoers
|
||||
assert (
|
||||
"left4me ALL=(root) NOPASSWD: "
|
||||
"/usr/local/libexec/left4me/left4me-script-sandbox"
|
||||
) in sudoers
|
||||
assert "/bin/systemctl" not in sudoers
|
||||
assert "/usr/bin/systemctl" not in sudoers
|
||||
assert "/bin/journalctl" not in sudoers
|
||||
assert "/usr/bin/journalctl" not in sudoers
|
||||
assert "/bin/mount" not in sudoers
|
||||
assert "/bin/umount" not in sudoers
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
import subprocess
|
||||
|
||||
from conftest import LIBEXEC, env_with_fake_commands, fake_command
|
||||
|
||||
|
||||
SYSTEMCTL_HELPER = LIBEXEC / "left4me-systemctl"
|
||||
|
||||
|
||||
def test_systemctl_helper_passes_shell_syntax_check_and_rejects_bad_args(tmp_path):
|
||||
subprocess.run(["sh", "-n", str(SYSTEMCTL_HELPER)], check=True)
|
||||
marker = fake_command(tmp_path, "systemctl")
|
||||
|
||||
for args in [
|
||||
["bad/action", "alpha"],
|
||||
# `start` and `stop` are no longer accepted verbs — the lifecycle now
|
||||
# uses `enable`/`disable` for reboot survival via WantedBy= symlinks.
|
||||
["start", "alpha"],
|
||||
["stop", "alpha"],
|
||||
["enable", ""],
|
||||
["enable", ".hidden"],
|
||||
["enable", "bad..name"],
|
||||
["enable", "bad/name"],
|
||||
["enable", "bad\\name"],
|
||||
["enable", "bad name"],
|
||||
]:
|
||||
result = subprocess.run(
|
||||
["sh", str(SYSTEMCTL_HELPER), *args],
|
||||
env=env_with_fake_commands(tmp_path),
|
||||
check=False,
|
||||
)
|
||||
assert result.returncode != 0
|
||||
assert not marker.exists()
|
||||
|
||||
script = SYSTEMCTL_HELPER.read_text()
|
||||
assert 'unit="left4me-server@${name}.service"' in script
|
||||
assert 'enable) exec "$systemctl" enable --now "$unit"' in script
|
||||
assert 'disable) exec "$systemctl" disable --now "$unit"' in script
|
||||
assert "--property=ActiveState" in script
|
||||
assert "--property=SubState" in script
|
||||
Loading…
Reference in a new issue