From 8baa05e7ccf991f4731878227b8ec88fdf9704c9 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:42:31 +0100 Subject: [PATCH] pc-agents: pair names a missing T3, packages Node needs, minimum T3; desk keeps a raised memory cap pc-agents (#278, #269): - pair: when the t3Version's t3 is not installed yet (an upgrade whose download failed), say so and how to fix it instead of env's "No such file or directory" (exit 127). - t3Version must be 0.1.7 or newer, the first T3 with the managed policy: an older one would run with none of the kit's locks. The README and machine.example.json examples move from 0.0.30 to 0.1.9. - setup installs libatomic1 (Node does not start without it, and the agent has no sudo) and unzip with nftables, by dpkg's status, finishing a dpkg run stopped half-way first; no T3 restart for a package. - README: step 10's commands are whole PowerShell lines, the token's scrollback is named; step 8 sets the agent's git identity (placeholders); step 7 says the agents share one home, so a toolchain installed once through as-agent is every agent's. - tests: how T3 ended by signal and on a clean exit, pair's own root check, the half-installed pair, the packages (fresh, again, stopped half-way), the minimum version, runnable owner-step commands. desk: start-desk.ps1's -MemoryGB is the least [wsl2] memory cap. A cap raised by hand is kept: not lowered, not a FAIL in the final check, and not a `wsl --shutdown` on every run from the live check. Co-Authored-By: Claude Opus 5.5 --- fork-kit/common/machine.example.json | 2 +- fork-kit/desk/README.md | 2 +- fork-kit/desk/tests/windows.test.py | 41 +++++++++++++ fork-kit/desk/windows/start-desk.ps1 | 17 +++++- fork-kit/pc-agents/README.md | 41 +++++++++---- fork-kit/pc-agents/lib/pc_agents.py | 10 +++- fork-kit/pc-agents/sbin/pc-agents | 39 ++++++++---- fork-kit/pc-agents/tests/fake_distro.py | 31 +++++++--- fork-kit/pc-agents/tests/setup.test.py | 80 ++++++++++++++++++++++++- 9 files changed, 226 insertions(+), 37 deletions(-) diff --git a/fork-kit/common/machine.example.json b/fork-kit/common/machine.example.json index 0f52fe14fad6a..4217316b97608 100644 --- a/fork-kit/common/machine.example.json +++ b/fork-kit/common/machine.example.json @@ -33,7 +33,7 @@ }, "pc-agents": { "organization": "Example home lab", - "t3Version": "0.0.30", + "t3Version": "0.1.9", "t3ReleaseBaseUrl": "https://github.com/example/t3code/releases/download", "port": 3773, "maxRuntimeMode": "full-access", diff --git a/fork-kit/desk/README.md b/fork-kit/desk/README.md index 25890a6b5a86c..575d23b507ea0 100644 --- a/fork-kit/desk/README.md +++ b/fork-kit/desk/README.md @@ -115,7 +115,7 @@ distro (`-Distro`, default `fork-desk`, Ubuntu 24.04, installed with `--version leaves a mark in `%LOCALAPPDATA%\fork-desk`, so the next run asks no takeover question, and a broken one names `wsl --unregister DISTRO`); `.wslconfig`'s `[wsl2]` memory cap (`-MemoryGB`, default three quarters of the RAM, at most the RAM less 6 GB, never under 4 GB; one that leaves Windows under 2 GB is -refused), swap (`-SwapGB`, 4), NAT and DNS tunnelling, for every WSL distro (read and written as UTF-8 without a +refused; it is the least cap: a higher one already there, raised by hand, is kept), swap (`-SwapGB`, 4), NAT and DNS tunnelling, for every WSL distro (read and written as UTF-8 without a BOM; a dated copy of the old file is kept, other keys and sections stay; an old `networkingMode` or `dnsTunneling` line under `[experimental]`, the form before WSL 2.0 that can still win over `[wsl2]`, is removed, and the check FAILs while one is there; the question lists each change, old -> new, and the file is written only when it lists one, diff --git a/fork-kit/desk/tests/windows.test.py b/fork-kit/desk/tests/windows.test.py index 1863e6b59b3bc..30ec03eec48da 100644 --- a/fork-kit/desk/tests/windows.test.py +++ b/fork-kit/desk/tests/windows.test.py @@ -362,6 +362,47 @@ def test_wslconfig_merge_removes_old_experimental_networking_keys(self): '[experimental] dnsTunneling=false: removed', 'changed=True', 'left=sparseVhd', 'after=0'): self.assertIn(line, r.stdout) + @unittest.skipUnless(shutil.which('pwsh'), 'pwsh is not installed') + def test_a_memory_cap_at_or_above_the_minimum_is_kept(self): + """-MemoryGB is the least cap: one a person raised (more agents or jobs in WSL) is neither lowered nor a FAIL, + nor a `wsl --shutdown` on every run (the live check's cap is the one kept).""" + d = tempfile.mkdtemp(prefix='desk-wslconfig-test-') + self.addCleanup(shutil.rmtree, d, True) + path = os.path.join(d, '.wslconfig') + script = os.path.join(d, 'memory.ps1') + with open(script, 'w', encoding='ascii') as f: + f.write(wslconfig_part() + '\n$want = [ordered]@{ memory = (WantMemory $args[0] 8); swap = "4GB" }\n' + '"want=$($want.memory) kb=$(CapKb $want.memory)"\n' + '"notes=$(@(Changes (Read-WslConfig $args[0]) $want) -join \'|\')"\n' + '$null = Merge-WslConfig $args[0] $want\n$cfg = Wsl2Keys (Read-WslConfig $args[0])\n' + '"check=$(@($want.Keys | Where-Object { $cfg[$_] -ne $want[$_] }).Count)"\n') + for old, want, kb, note in (('memory=26GB', '26GB', 27262976, ''), # raised: kept, no change, no FAIL + ('memory = 30720mb', '30720mb', 31457280, ''), + ('memory=8GB', '8GB', 8388608, ''), + ('memory=9G', '9G', 9437184, ''), + ('memory=4GB', '8GB', 8388608, '[wsl2] memory: 4GB -> 8GB'), # below: raised + ('memory=8191MB', '8GB', 8388608, '[wsl2] memory: 8191MB -> 8GB'), + ('memory=lots', '8GB', 8388608, '[wsl2] memory: lots -> 8GB'), + ('', '8GB', 8388608, '[wsl2] memory: (not set) -> 8GB')): + with self.subTest(old): + with open(path, 'w', encoding='utf-8', newline='\n') as f: + f.write(f'[wsl2]\n{old}\nswap=4GB\n') + r = subprocess.run(['pwsh', '-NoProfile', '-NonInteractive', '-File', script, path], + capture_output=True, text=True, timeout=120, stdin=subprocess.DEVNULL) + self.assertEqual(r.returncode, 0, r.stdout + r.stderr) + self.assertIn(f'want={want} kb={kb}\n', r.stdout) + self.assertIn(f'notes={note and " " + note}\n', r.stdout) # a note is indented + self.assertIn('check=0\n', r.stdout) + if not note: + self.assertEqual(slurp(path), f'[wsl2]\n{old}\nswap=4GB\n') # left alone + + def test_the_minimum_memory_cap_decides_through_wantmemory(self): + src = text().decode('ascii') + body = src[src.index('try {'):] + self.assertIn('$want = [ordered]@{ memory = (WantMemory $WslConfig $MemoryGB);', body) + self.assertIn('("WANT_KB=$(CapKb $want.memory)`n" + $Live)', body) # the cap kept, not -MemoryGB + self.assertNotIn('$MemoryGB * 1048576', body) + def test_wslconfig_is_utf8_without_a_bom_never_ascii(self): src = text().decode('ascii') self.assertNotRegex(src, r'(?i)-Encoding\s+ascii') diff --git a/fork-kit/desk/windows/start-desk.ps1 b/fork-kit/desk/windows/start-desk.ps1 index 47bce128bf26a..a303b775316bd 100644 --- a/fork-kit/desk/windows/start-desk.ps1 +++ b/fork-kit/desk/windows/start-desk.ps1 @@ -2,6 +2,7 @@ # (fork-kit/desk/README.md, "Windows"). Run it in a normal Windows PowerShell window (not as administrator): # powershell -ExecutionPolicy Bypass -File start-desk.ps1 -Repo OWNER/REPO -Sha RELEASE_SHA -MachineFile machine.json # [-FleetConfig fork-fleet.json] [-Distro fork-desk] [-MemoryGB N] [-SwapGB 4] [-Uninstall] +# -MemoryGB is the least [wsl2] memory cap: a higher one already in .wslconfig is kept. # It prints this PC's facts and asks before it changes anything. Safe to run again: every step checks what is there. # Steps: the distro (Ubuntu 24.04); .wslconfig's [wsl2] memory cap and NAT (a dated copy of the old file is kept; # other keys stay); the distro's own settings (the WSL walls: no interop, no Windows PATH or drives, its own @@ -161,6 +162,18 @@ function Merge-WslConfig([string]$path, $want, [scriptblock]$before = {}) { # Move-Item -LiteralPath "$path.new" $path -Force $true } +# A [wsl2] memory= value in kB (8GB, 8192MB, 8G; no unit: bytes), or -1 when it is not a size +function CapKb([string]$v) { + if ($v -notmatch '^\s*([0-9]{1,13})\s*([KMGT]?)B?\s*$') { return [long]-1 } + [long][math]::Min(1e15, [math]::Floor([double]$Matches[1] * [math]::Pow(1024, ' KMGT'.IndexOf($Matches[2].ToUpper())) / 1024)) +} +# The memory cap to want: at least $gb GB. A higher one already in .wslconfig (a person raised it) is kept as it is +# written, so it is neither lowered nor a FAIL, and the live check holds WSL to it. +function WantMemory([string]$path, [int]$gb) { + $have = (Wsl2Keys (Read-WslConfig $path))['memory'] + if ($have -and (CapKb $have) -ge [long]$gb * 1048576) { return $have } + "${gb}GB" +} function WslVersion([string[]]$lines, [string]$name) { # the WSL version of one distro in `wsl -l -v`; 0: not there foreach ($l in $lines) { $f = @(($l.Trim([char]0, ' ', '*', "`t") -replace [char]0, '') -split '\s+') @@ -211,7 +224,7 @@ try { $ours = Test-Path -LiteralPath $Made if ($have -and -not $ours) { wsl.exe -d $Distro -u root --cd / -- test -e /etc/fork-kit/desk-distro; $ours = $LASTEXITCODE -eq 0 } - $want = [ordered]@{ memory = "${MemoryGB}GB"; swap = "${SwapGB}GB"; networkingMode = 'nat'; dnsTunneling = 'true'; guiApplications = 'false' } + $want = [ordered]@{ memory = (WantMemory $WslConfig $MemoryGB); swap = "${SwapGB}GB"; networkingMode = 'nat'; dnsTunneling = 'true'; guiApplications = 'false' } $changes = @(Changes (Read-WslConfig $WslConfig) $want) Write-Host '' Write-Host "Next: the distro $Distro; .wslconfig (for ALL your WSL distros; a dated copy is kept):" -ForegroundColor Yellow @@ -250,7 +263,7 @@ try { $changed Remove-Item -LiteralPath $Made -ErrorAction SilentlyContinue # the distro's own mark is there now # The live state decides, not only what this run changed: a run stopped before its shutdown restarts next time - $live = @(InDistro 'the running settings' ("WANT_KB=$([long]$MemoryGB * 1048576)`n" + $Live)) + $live = @(InDistro 'the running settings' ("WANT_KB=$(CapKb $want.memory)`n" + $Live)) $up = [double]((wsl.exe -d $Distro -u root --cd / -- cat /proc/uptime) -split ' ')[0] if ((Test-Path $WslConfig) -and ((Get-Date) - (Get-Item -LiteralPath $WslConfig).LastWriteTime).TotalSeconds -lt $up) { $live += 'restart: .wslconfig is newer than the running WSL' diff --git a/fork-kit/pc-agents/README.md b/fork-kit/pc-agents/README.md index db8e827140706..6bba40102d7bf 100644 --- a/fork-kit/pc-agents/README.md +++ b/fork-kit/pc-agents/README.md @@ -55,7 +55,7 @@ The kit reads the `pc-agents` section of the machine file `/etc/fork-kit/machine "version": 1, "pc-agents": { "organization": "Example home lab", - "t3Version": "0.0.30", + "t3Version": "0.1.9", "t3ReleaseBaseUrl": "https://github.com/example/t3code/releases/download", "port": 3773, "maxRuntimeMode": "full-access", @@ -72,7 +72,7 @@ The kit reads the `pc-agents` section of the machine file `/etc/fork-kit/machine | Key | What | | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | | `organization` | the name the managed policy shows in T3's settings | -| `t3Version` | the exact T3 version to run (the same as the T3 that links to this PC); installed with `scripts/install.sh` | +| `t3Version` | the exact T3 version (the linking T3's), 0.1.7 or newer (see below); installed with `scripts/install.sh` | | `t3ReleaseBaseUrl` | where that version's release files are (`T3CODE_RELEASE_BASE_URL` of `scripts/install.sh`) | | `port` | T3's port (`T3CODE_PORT`); the Tailscale ACL opens it to the linking T3 only | | `agentUid` | the `agent` user's uid (default 1100; not 1000, the first user of every other distro, see Limits) | @@ -85,6 +85,9 @@ The kit reads the `pc-agents` section of the machine file `/etc/fork-kit/machine | `peers` | the linking T3's Tailscale address(es) (CIDR list, 1 to 16): the only private addresses the unit talks to | | `tailscaleTag` | the tag this PC's Tailscale node gets (`tag:name`) | +`t3Version` must be 0.1.7 or newer: older releases have no managed policy, so they would run with none of the kit's +locks and with updates on. Setup and `check` refuse them, naming the key. (`t3 pair`, step 10, came earlier.) + Every T3 setting can be locked through `lockedSettings`, the fork's own settings (`agentSlots`, `usagePacingGate`, `usagePacing`, `waitFor`, ...) too: the managed policy locks any key of the server settings, upstream's or the fork's (`apps/server/src/policy/managedSettings.ts`), and a test proves it for the fork's keys. Lock one field per dotted @@ -143,10 +146,19 @@ Commands are for Windows PowerShell unless a step says otherwise. `` is If Claude says it cannot read its managed settings on `/mnt/c` (`EACCES`), choose "Continue without these settings": that is Windows' folder, which the walls hide on purpose. Then restart T3, which looks for providers only when it starts: `wsl -d -u root -- systemctl restart t3code-agents` (its start runs the check first). + Every agent of this T3 runs as `agent`, in the one home, so a tool installed there once is every agent's: install a + project's toolchain (Node, its package manager) the same way, through `as-agent`, before the first agent needs it. + Setup installs the system libraries they need (`libatomic1`, without which Node does not start, and `unzip`). 8. **Log in to GitHub as the agent:** install `gh` (as root, from GitHub CLI's docs), then `wsl -d -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- gh auth login --with-token` and paste a fine-grained token for the agents' repos into that window only. It waits without a prompt: paste the token, - press Enter, then Ctrl+D. + press Enter, then Ctrl+D. Then give the agent a git identity (its commits fail without one): + `wsl -d -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- git config --global user.name ''` + and + `wsl -d -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- git config --global user.email ''`, + with a name of your choice and an address that is no one's private one, for example the token account's noreply + address (`+@users.noreply.github.com`, shown in its GitHub email settings). Run again, they only set + the same values again. 9. **Keep the distro running:** WSL stops a distro soon after its last window closes, and does not start one when Windows starts. A logon task of your own (no administrator needed) keeps this one running while you are logged in. In PowerShell, as yourself (the same task as the desk starter's, `fork-kit/desk/windows/start-desk.ps1`): @@ -161,14 +173,18 @@ Commands are for Windows PowerShell unless a step says otherwise. `` is 10. **Pair, then link from the other T3:** this PC's T3 is walled from the Windows host on purpose, so a browser on this PC cannot open it, nor make a pairing code there. Make the code from the command line (PowerShell): `wsl -d -u root -- /opt/pc-agents/current/sbin/pc-agents pair`. It runs T3's own `t3 pair` as the - agent under the walls, the T3 the unit runs (`/opt/pc-agents/t3/runtime/versions//t3`), and prints a - token that expires in 5 minutes (`pc-agents pair --ttl 15m` for longer); the address it prints is the distro's - own, not one to link. A kit without `pair` (older than this step): the same through - `pc-agents as-agent -- /opt/pc-agents/t3/runtime/versions//t3 pair` (an upgrade leaves the old - version's folder there, so name yours). In the other T3: Settings → Environments → Linked environments → Link, - with this PC's tailnet DNS name (MagicDNS: `http://..ts.net:`; `tailscale status` there - shows the name), the token, and **Full access**. Not its tailnet IP address: T3 refuses to link a plain-http IP - address. + agent under the walls, the T3 of `t3Version` that the unit starts + (`/opt/pc-agents/t3/runtime/versions//t3`; when setup has not installed that one yet, it says so: run + step 3 again), and prints a token that expires in 5 minutes; for longer: + `wsl -d -u root -- /opt/pc-agents/current/sbin/pc-agents pair --ttl 15m`. The token stays in this + PowerShell window's scrollback, usable by anyone who sees it until it is used or expires: give a long `--ttl` only + knowingly, and close the window once linked. The address it prints is the distro's own, not one to link. A kit + without `pair` (older than this step): + `wsl -d -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- /opt/pc-agents/t3/runtime/versions//t3 pair` + (an upgrade leaves the old version's folder there, so name yours). In the other T3: Settings → Environments → + Linked environments → Link, with this PC's tailnet DNS name (MagicDNS: `http://..ts.net:`; + `tailscale status` there shows the name), the token, and **Full access**. Not its tailnet IP address: T3 refuses + to link a plain-http IP address. Run step 3 again for a new release or a changed machine file (and steps 4 and 5 if it asks); T3 restarts only when something changed. To remove everything: `wsl --unregister `. @@ -213,6 +229,9 @@ allowed (connection tracking). `SIGHUP` (a closed window) stop setup the same way, the running download's whole group too. - **Start limit:** a rerun within 10 minutes of five failed starts still starts T3 (`systemctl reset-failed` first). - **An older kit's distro:** an `agent` made with a login shell gets `/usr/sbin/nologin` (`usermod`), once. +- **Packages:** setup installs `nftables`, `libatomic1` and `unzip` when `dpkg` does not list one as installed (a + distro set up by an older kit gets the two new ones at its next run; no T3 restart for them). A package install + stopped half-way is finished first (`dpkg --configure -a`); a failed one stops setup, naming the command to run. - **A distro that is not fresh:** refused before anything is written, with the reasons: another login user, an `agent` with another uid or in another group, a file the kit would write that it did not write (or that was edited since, for example a hand-written `wsl.conf` or `policy.json`), a cron, at or ssh unit where the kit masks diff --git a/fork-kit/pc-agents/lib/pc_agents.py b/fork-kit/pc-agents/lib/pc_agents.py index 9c4e5005e752f..c4e7e1c93c2ed 100644 --- a/fork-kit/pc-agents/lib/pc_agents.py +++ b/fork-kit/pc-agents/lib/pc_agents.py @@ -44,6 +44,12 @@ # off through limits.updates (all versions; the server's self-update refuses), not the newer automaticUpdates. KIT_SETTINGS = {'linkedEnvironmentsEnabled': True} VERSION = re.compile(r'(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?') +# The oldest T3 that applies a managed policy (0.1.7; `t3 pair` is older): an older one would run with none of the +# kit's locks, updates on, and quietly. Its pre-releases count as it. +OLDEST_T3 = (0, 1, 7) +# Debian packages setup installs when missing: the agent firewall's nft; libatomic1, which Node (and so most agent +# tools) needs to start, while the agent has no sudo to install it; unzip, which install steps of packages use. +PACKAGES = ('nftables', 'libatomic1', 'unzip') HEAD = '# pc-agents kit: written by `pc-agents setup`; an edit is refused at its next run and fails the walls check\n' # What the kit runs from a release: source path -> (path in the version folder, mode). The walls are the merged @@ -72,7 +78,9 @@ def is_ip_list(value, net, glob=False, most=64): SPEC = { 'organization': (str, machine_file.REQUIRED, lambda v: None if v.strip() and len(v) <= 80 else '1 to 80 characters, not blank'), - 't3Version': (str, machine_file.REQUIRED, lambda v: None if VERSION.fullmatch(v) else 'an exact version, no v'), + 't3Version': (str, machine_file.REQUIRED, lambda v: 'an exact version, no v' if not VERSION.fullmatch(v) else + None if tuple(map(int, VERSION.fullmatch(v).groups()[:3])) >= OLDEST_T3 else + '%d.%d.%d or newer (the first T3 with the managed policy)' % OLDEST_T3), 't3ReleaseBaseUrl': (str, machine_file.REQUIRED, lambda v: None if re.fullmatch(r'https://[A-Za-z0-9./_-]+', v) else 'an https URL'), 'port': (int, machine_file.REQUIRED, lambda v: None if 1024 <= v <= 65535 else '1024 to 65535'), diff --git a/fork-kit/pc-agents/sbin/pc-agents b/fork-kit/pc-agents/sbin/pc-agents index 6e1d21149f5fb..6445aab948902 100755 --- a/fork-kit/pc-agents/sbin/pc-agents +++ b/fork-kit/pc-agents/sbin/pc-agents @@ -192,6 +192,26 @@ def install_t3(c, version, done): return None +def install_packages(): + """Install the k.PACKAGES that are not (fully) installed. A dpkg run stopped half-way is finished first (apt-get + refuses until it is). Returns why not, or None.""" + r = k.run(['/usr/bin/dpkg-query', '-W', '-f=${Package}\t${Status}\n', *k.PACKAGES]) + have = {p for p, _, status in (line.partition('\t') for line in r.stdout.splitlines()) + if status == 'install ok installed'} + missing = [p for p in k.PACKAGES if p not in have] + if not missing: + return None + say('installing ' + ' '.join(missing)) + for argv in (['/usr/bin/dpkg', '--configure', '-a'], ['/usr/bin/apt-get', 'update'], + ['/usr/bin/apt-get', 'install', '-y', *missing]): + r = k.run(argv, timeout=900) + if r.returncode: + return (f'cannot install {" ".join(missing)}: {" ".join(argv)} failed ({r.stderr.strip()[-300:]}). Fix ' + 'the distro\'s network or package sources, run `apt-get update && apt-get install -y ' + f'{" ".join(missing)}` as root, then setup again') + return None + + def setup(source, sha): if not re.fullmatch(r'[0-9a-f]{40}', sha) or not os.path.isdir(source): return say('usage: pc-agents setup --source DIR --sha 40-HEX-SHA') or 2 @@ -215,13 +235,8 @@ def setup(source, sha): r = k.run(['/usr/sbin/usermod', '--shell', k.NOLOGIN, k.USER]) if r.returncode: return say(f'usermod failed: {r.stderr.strip()[-300:]}') or 1 - if k.lstat('/usr/sbin/nft') is None: - for argv in (['/usr/bin/apt-get', 'update'], ['/usr/bin/apt-get', 'install', '-y', 'nftables']): - r = k.run(argv, timeout=900) - if r.returncode: - return say(f'cannot install nftables: {" ".join(argv)} failed ({r.stderr.strip()[-300:]}). Fix the ' - 'distro\'s network or package sources, run `apt-get update && apt-get install -y ' - 'nftables` as root, then setup again') or 1 + if why := install_packages(): + return say(why) or 1 version = f'{k.OPT}/{sha}' for src, (dst, mode) in k.CODE.items(): with open(os.path.join(source, src), 'rb') as f: @@ -319,15 +334,19 @@ def stays_up(): def pair(args): - """T3's own `t3 pair` for the T3 the unit runs (this t3Version's, not a glob over the versions folder, where an - older version stays), as the agent with the unit's T3 home, so it finds that running server.""" + """T3's own `t3 pair` of the machine file's t3Version, the one the unit starts (not a glob over the versions + folder, where an older version stays), as the agent with the unit's T3 home, so it finds that running server. + An upgrade stopped half-way (the new t3Version written, its download failed) has no such t3 yet: said so.""" if not k.ROOT and os.geteuid() != 0: return say('run this as root') or 2 try: c = k.config() except machine_file.MachineFileError as e: return say(str(e)) or 2 - return as_agent([k.runtime(c) + '/t3', 'pair'] + args) + t3 = k.runtime(c) + '/t3' + if k.lstat(t3) is None: + return say(f'T3 {c["t3Version"]} is not installed yet: run pc-agents setup again (README step 3)') or 1 + return as_agent([t3, 'pair'] + args) def as_agent(cmd): diff --git a/fork-kit/pc-agents/tests/fake_distro.py b/fork-kit/pc-agents/tests/fake_distro.py index 2f1288ca60a54..2ab5fbc4f1cc2 100644 --- a/fork-kit/pc-agents/tests/fake_distro.py +++ b/fork-kit/pc-agents/tests/fake_distro.py @@ -1,8 +1,8 @@ """A fake WSL2 distro in a temporary folder for the pc-agents tests: every fixed path under PC_AGENTS_ROOT, the -current user as root, fake useradd, usermod, env (T3's installer), apt-get, systemctl, systemd-run and nft (each logs -to /log in the fake root; systemctl keeps which units are enabled, and the ExecStart and policy a started one runs -with, its main PID and its start time (CLOCK_MONOTONIC, as systemd's) in /log/units). No root, no systemd, no network, -no real /etc. Fresh as `wsl --install` leaves one, from the fleet's wsl2 walls fixture.""" +current user as root, fake useradd, usermod, env (T3's installer), apt-get, dpkg-query, dpkg, systemctl, systemd-run +and nft (each logs to /log in the fake root; systemctl keeps which units are enabled, and the ExecStart and policy a +started one runs with, its main PID and its start time (CLOCK_MONOTONIC, as systemd's) in /log/units). No root, no +systemd, no network, no real /etc. Fresh as `wsl --install` leaves one, from the fleet's wsl2 walls fixture.""" import contextlib, importlib.machinery, importlib.util, io, json, os, shutil, stat, sys, tempfile, unittest from unittest import mock @@ -48,9 +48,11 @@ # a start: refused while the start limit is hit ($S/U.limit, until reset-failed); with # /log/t3-crash T3 exits at once, with /log/t3-dies after the first look (show) at it 'run() { [ -e "$S/$1.limit" ] && { echo "$1: start request repeated too quickly" >&2; ' - 'return 1; }\nrm -f "$S/$1.seen" "$S/$1.status"\n' + 'return 1; }\nrm -f "$S/$1.seen" "$S/$1.status" "$S/$1.code"\n' + # /log/t3-crash: T3's exit status (empty: 1), or "CODE STATUS" (2 9: killed by signal 9) '[ "$1" = t3code-agents.service ] && [ -e "$R/log/t3-crash" ] && { rm -f "$S/$1.active"; ' - 'c=$(cat "$R/log/t3-crash"); echo "${c:-1}" >"$S/$1.status"; return; }\n' + 'c=$(cat "$R/log/t3-crash"); case "$c" in *" "*) echo "${c%% *}" >"$S/$1.code"; c=${c#* };; ' + '*) echo 1 >"$S/$1.code";; esac; echo "${c:-1}" >"$S/$1.status"; return; }\n' '{ grep "^ExecStart=" "$R/etc/systemd/system/$1"; ' 'cat "$R/etc/t3code/policy.json"; } >"$S/$1.active" 2>/dev/null || :\n' 'echo $$ >"$S/$1.pid"; python3 -I -c "import time; print(time.monotonic_ns() // 1000)" ' @@ -74,13 +76,23 @@ ' [ -e "$S/reload" ] && echo NeedDaemonReload=yes || echo NeedDaemonReload=no\n' ' if [ -e "$S/$u.active" ]; then echo ActiveState=active; echo "MainPID=$(cat "$S/$u.pid")"\n' ' else echo ActiveState=inactive; echo MainPID=0; fi; echo NRestarts=0\n' - ' [ -e "$S/$u.status" ] && { echo ExecMainCode=1; echo "ExecMainStatus=$(cat "$S/$u.status")"; }\n' + ' [ -e "$S/$u.status" ] && { echo "ExecMainCode=$(cat "$S/$u.code")"; echo "ExecMainStatus=$(cat "$S/$u.status")"; }\n' ' echo "ExecMainStartTimestampMonotonic=$(cat "$S/$u.start" 2>/dev/null || echo 0)";;\n' 'esac\n', - # apt-get: update, or install nftables (the fake nft kept in /log/nft-package); /log/apt-fail makes it fail + # apt-get: update, or install packages (each then installed in /log/packages; nftables brings the fake nft kept + # in /log/nft-package); /log/apt-fail makes it fail 'usr/bin/apt-get': 'R="${0%/usr/bin/apt-get}"; echo "$*" >>"$R/log/apt-get"\n' '[ -e "$R/log/apt-fail" ] && { echo "E: no network (test)" >&2; exit 100; }\n' - '[ "$1" = install ] && cp "$R/log/nft-package" "$R/usr/sbin/nft"; exit 0\n', + '[ "$1" = install ] || exit 0; shift 2\n' + 'for p; do echo "install ok installed" >"$R/log/packages/$p"\n' + ' [ "$p" != nftables ] || cp "$R/log/nft-package" "$R/usr/sbin/nft"; done\n', + # dpkg-query -W -f=FORMAT PKG...: "PKGits status" for each package in /log/packages (the status inside) + 'usr/bin/dpkg-query': 'R="${0%/usr/bin/dpkg-query}"; echo "$*" >>"$R/log/dpkg-query"; shift 2; rc=0\n' + 'for p; do if [ -e "$R/log/packages/$p" ]; then printf "%s\\t%s\\n" "$p" "$(cat "$R/log/packages/$p")"\n' + ' else echo "dpkg-query: no packages found matching $p" >&2; rc=1; fi; done; exit $rc\n', + # dpkg --configure -a: finishes what an apt-get stopped half-way left unpacked + 'usr/bin/dpkg': 'R="${0%/usr/bin/dpkg}"; echo "$*" >>"$R/log/dpkg"\n' + 'for f in "$R"/log/packages/*; do [ ! -e "$f" ] || sed -i "s/unpacked/installed/" "$f"; done\n', 'usr/sbin/nft': 'R="${0%/usr/sbin/nft}"\ncase "$1" in -f) cp "$R$2" "$R/log/nft-loaded";;\n' 'list) cat "$R/log/nft-loaded" 2>/dev/null || exit 1;; esac\n', } @@ -130,6 +142,7 @@ def setUp(self): files['proc/sys/kernel/random/boot_id'] = '0f8e4f9c-1b6a-4d2e-9a57-3c1d2e4f5a6b\n' files['proc/net/route'] = 'Iface\tDestination\tGateway\tFlags\nboth\t00000000\t011014AC\t0003\n' files['log/'] = files['opt/'] = files['etc/systemd/system/'] = '' # as in a fresh Ubuntu + files['log/packages/nftables'] = 'install ok installed' # and no libatomic1 or unzip, as in a fresh Ubuntu files.update({rel: {'text': '#!/bin/sh\n' + text, 'mode': '755'} for rel, text in TOOLS.items()}) for rel, value in files.items(): self.write('/' + rel, value) diff --git a/fork-kit/pc-agents/tests/setup.test.py b/fork-kit/pc-agents/tests/setup.test.py index 3297a2d116ab6..80408cc24c8b1 100644 --- a/fork-kit/pc-agents/tests/setup.test.py +++ b/fork-kit/pc-agents/tests/setup.test.py @@ -6,6 +6,7 @@ python3 -I -B fork-kit/pc-agents/tests/setup.test.py """ import json, os, re, shutil, signal, stat, subprocess, sys, time, unittest +from unittest import mock sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) from fake_distro import CONFIG, KIT, REPO, SHA1, SHA2, Case, blob, cli, k # noqa: E402 @@ -309,15 +310,35 @@ def test_killed_at_a_write_then_the_machine_file_edited(self): def test_nftables_installed_after_a_package_list_update(self): os.replace(self.path('/usr/sbin/nft'), self.path('/log/nft-package')) + os.unlink(self.path('/log/packages/nftables')) self.terminate() self.write('/log/apt-fail', '') code, out = self.setup_run() self.assertEqual(code, 1, out) - self.assertIn('apt-get update && apt-get install -y nftables', out) + self.assertIn('apt-get update && apt-get install -y nftables libatomic1 unzip', out) os.unlink(self.path('/log/apt-fail')) code, out = self.setup_run() self.assertEqual(code, 0, out) - self.assertEqual(self.log('apt-get'), ['update', 'update', 'install -y nftables']) + self.assertEqual(self.log('apt-get'), ['update', 'update', 'install -y nftables libatomic1 unzip']) + + def test_libatomic1_and_unzip_are_installed_once(self): + """Node (the agents' tool) does not start without libatomic.so.1 and the agent has no sudo; unzip is for + postinstall steps. A fresh Ubuntu has neither (#269).""" + self.ready() + self.assertEqual(self.log('apt-get'), ['update', 'install -y libatomic1 unzip']) + for p in ('libatomic1', 'unzip'): + self.assertEqual(self.read('/log/packages/' + p), 'install ok installed\n') + for log in ('apt-get', 'dpkg', 'systemctl'): + os.unlink(self.path('/log/' + log)) + self.assertEqual(self.setup_run()[0], 0) # runs again: nothing to install + self.assertEqual(self.log('apt-get'), []) + self.assertEqual(self.log('dpkg'), []) + self.write('/log/packages/unzip', 'install ok unpacked') # an apt-get stopped half-way + code, out = self.setup_run() + self.assertEqual(code, 0, out) + self.assertEqual(self.log('dpkg'), ['--configure -a']) # first: apt-get refuses while dpkg was interrupted + self.assertEqual(self.log('apt-get'), ['update', 'install -y unzip']) + self.assertFalse([line for line in self.log() if line.startswith('restart')]) # no T3 restart for a package def test_t3_that_does_not_start_is_reported(self): self.ready() @@ -349,6 +370,20 @@ def test_t3_that_does_not_start_is_reported(self): self.assertFalse(os.path.lexists(self.path(k.PENDING))) + def test_how_t3_ended_is_said_only_when_not_cleanly(self): + self.ready() + self.machine({**CONFIG, 'memoryMax': '4G'}) + for crash, said in (('2 9', 'killed by signal 9'), ('3 6', 'killed by signal 6'), ('1 0', None)): + self.write('/log/t3-crash', crash) # ExecMainCode ExecMainStatus: CLD_KILLED, CLD_DUMPED, a clean exit + code, out = self.setup_run() + self.assertEqual(code, 1, out) + self.assertIn('T3 did not start or stay up', out) + if said: + self.assertIn(said, out) + else: + self.assertNotIn('exit status', out) + self.assertNotIn('killed', out) + def test_t3_that_dies_a_moment_after_the_restart_is_reported(self): self.ready() self.write('/log/t3-dies', '') # T3 starts, then exits on something it cannot apply @@ -576,6 +611,29 @@ def test_refused_when_a_wall_does_not_hold(self): self.assertIn('not running anything as the agent', out) self.assertEqual(self.log('systemd-run'), []) + def test_pair_before_its_t3_is_installed_says_so(self): + """An upgrade stopped half-way (the new t3Version written, its download failed): no env error, the cause.""" + self.ready() + self.machine({**CONFIG, 't3Version': '1.2.4'}) + self.write('/log/install-fail', '') + self.assertEqual(self.setup_run()[0], 1) + for stopped in (False, True): # the old T3 still runs, or the 2-minute check stopped it (a restart is due) + if stopped: + k.run(['/usr/bin/systemctl', 'stop', k.UNIT]) + code, out = self.call(cli.main, ['pair']) + self.assertEqual(code, 1, out) + self.assertIn('T3 1.2.4 is not installed yet: run pc-agents setup again (README step 3)', out) + self.assertEqual(self.log('systemd-run'), []) + + def test_pair_and_as_agent_are_for_root_only(self): + for argv in (['pair'], ['pair', '--ttl', '1m'], ['as-agent', '--', 'claude']): + with mock.patch.object(k, 'ROOT', ''), mock.patch.object(os, 'geteuid', lambda: 1100), \ + mock.patch.object(k, 'config', mock.Mock(side_effect=AssertionError('read the machine file'))): + code, out = self.call(cli.main, argv) + self.assertEqual(code, 2, out) + self.assertIn('run this as root', out) + self.assertEqual(self.log('systemd-run'), []) + def test_pair_runs_the_installed_t3_pair_as_the_agent(self): self.ready() self.machine({**CONFIG, 't3Version': '1.2.4'}) @@ -663,6 +721,8 @@ def test_bad_config(self): ({'lockedSettings': {'agentSlots.maxPerMachine.x': {'y': 2}}}, 'one field per dotted path'), ({'nameservers': ['192.168.1.1']}, 'only public addresses'), ({'t3Version': 'latest'}, 'an exact version'), + ({'t3Version': '0.1.6'}, '0.1.7 or newer'), # no managed policy: no locks at all + ({'t3Version': '0.0.30-fork.1'}, '0.1.7 or newer'), ({'maxRuntimeMode': 'root'}, 'one of')): self.machine({**CONFIG, **change}) code, out = self.setup_run() @@ -671,6 +731,22 @@ def test_bad_config(self): self.assertFalse(os.path.lexists(self.path('/etc/t3code/policy.json'))) +class Readme(unittest.TestCase): + def test_owner_steps_run_as_written_in_powershell(self): + """Every kit command of the owner steps is a whole PowerShell line: `pc-agents ...` alone is not found there.""" + with open(os.path.join(KIT, 'README.md'), encoding='utf-8') as f: + readme = f.read() + steps = readme[readme.index('## Owner steps'):readme.index('## Tailscale tag')] + spans = re.findall(r'`([^`]*pc-agents (?:pair|as-agent)\b[^`]*)`', steps) + self.assertGreaterEqual(len(spans), 5, spans) + for span in spans: + self.assertTrue(span.startswith('wsl -d -u root -- /opt/pc-agents/current/sbin/pc-agents '), span) + self.assertIn('pc-agents pair --ttl 15m`', steps) + for key in ('user.name', 'user.email'): # the agent's git identity: placeholders the owner fills in + line = next(s for s in spans if f'git config --global {key} ' in s) + self.assertRegex(line, rf"git config --global {key} '<[^>]+>'$") + + class ReleaseHolds(unittest.TestCase): """Setup copies k.CODE out of the release commit the bootstrap downloads, and a release commit holds only the paths of .github/fork-ci-release.json: every source must be in one of them (setup crashed on a real distro