Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,15 @@ jobs:
- name: Run validate.py
run: python3 scripts/validate.py

host-ids:
runs-on: ubuntu-latest
steps:
- name: Check out repo
uses: actions/checkout@v5

- name: No machine or owner identifiers in tracked files
run: python3 scripts/host_ids.py check

smoke-go:
runs-on: ubuntu-latest
steps:
Expand Down
12 changes: 12 additions & 0 deletions .host-scrub.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Host-scrub configuration. Holds public values and patterns only, never a host value.
# See CLAUDE.md "Publishing rule".

# The disposable lab guests (systems-target, systems-peer) are Fedora VMs whose own
# values are book content: the cloud image's default account home and the pinned
# guest kernel. Each regex matches that public value wherever it appears, so a host
# value in the same file is still found. The second kernel-build value is the Fedora
# kernel-devel package build shipped in the guest image (_docs/30 discusses the mismatch).
[allow_match]
home-path = ['^/home/fedora$']
kernel-build = ['6[.]19[.]10-300[.]fc44', '^7[.]1[.]3-201[.]fc44$']
kernel-version = ['^#1 SMP PREEMPT_DYNAMIC Wed Mar 25 18:23:49 UTC 2026$']
24 changes: 24 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,3 +87,27 @@ Ruby), examples in `examples/NN-slug/{cpp,go,rust}/`, chapters in
rename it without fixing both links. **Internal working plans and capture
dumps must set `published: false` in their front matter** so they stay in git
for resumability without shipping to the site.

## Publishing rule: nothing identifies the machine or its owner

The repo is public, so no tracked file may name the development machine, its owner
or anything that helps locate or attack it later:

- No absolute home-directory path (under /home or /Users), no account name, no
hostname. Write `<repo>/...` or `~/...`. The lab guests' own `fedora` account and
its home directory are book content, not the host's.
- No laptop model (DMI `product_name` is `"redacted"`), no CPU model or model number.
The CPU is a class ("Intel 8-core/16-thread laptop CPU"); prose names its
properties (SMT, cache sizes, frequency driver), never the part.
- No host kernel build number or build date: give `major.minor` (for example
`7.1`) and the preempt model. The lab guests' pinned kernel (`systems-target`) is
book content and is allowed by value (`allow_match`) in `.host-scrub.toml`.
- No `/etc/machine-id`, DMI serial or UUID, host MAC or IP address (the lab guests' private libvirt
addresses are book content), `root=UUID=` or BOOT_IMAGE.
- Generated output is scrubbed before it is committed: `python3 scripts/host_ids.py
scrub <dir>` on a results directory, `scripts/host_ids.py filter` on a captured
transcript. `scripts/test-all-examples.py` scrubs `build-logs/` after each run.
- `python3 scripts/host_ids.py check` runs in CI (`host-ids` job) and fails the build
on a hit. Allow a legitimate hit by path and category (or by public value with
`allow_match`) in `.host-scrub.toml`; the file holds no host values (only public
guest values).
14 changes: 7 additions & 7 deletions _docs/01-prerequisites.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The book targets **Fedora 44** deliberately. Systems programming is the one
domain where "any recent Linux" is not good enough: chapters later in the book
read kernel tracepoints, load eBPF programs, and poke at cgroup files whose
layout shifts between kernel versions. Fedora ships close to upstream — the
reference host here runs kernel `7.1.3-200.fc44` — so what you observe matches
reference host here runs kernel `7.1` — so what you observe matches
what current kernel documentation describes. It also ships **GCC 16.1.1** as
the system compiler, which matters immediately: the C++ examples use C++23's
`std::println` and `std::expected`, and those need GCC 14 or newer. On Fedora
Expand Down Expand Up @@ -318,7 +318,7 @@ run, `cargo` installs the pinned 1.97.1 toolchain if needed — and each binary
prints one line of the same shape:

```
pid 2520094 on Linux 7.1.3-200.fc44.x86_64 (x86_64)
pid 2520094 on Linux 7.1 (x86_64)
```

Three lines, three different PIDs, identical formatting: that is the whole
Expand All @@ -335,8 +335,8 @@ C++ binary, trimmed to the `uname` call:

```bash
[host]$ strace -f -e trace=uname ./cpp/build/release/app
uname({sysname="Linux", nodename="Lemuria", ...}) = 0
pid 2520274 on Linux 7.1.3-200.fc44.x86_64 (x86_64)
uname({sysname="Linux", nodename="host", ...}) = 0
pid 2520274 on Linux 7.1 (x86_64)
+++ exited with 0 +++
```

Expand All @@ -348,8 +348,8 @@ strace: Process 2520268 attached
strace: Process 2520269 attached
strace: Process 2520270 attached
strace: Process 2520271 attached
[pid 2520267] uname({sysname="Linux", nodename="Lemuria", ...}) = 0
pid 2520267 on Linux 7.1.3-200.fc44.x86_64 (x86_64)
[pid 2520267] uname({sysname="Linux", nodename="host", ...}) = 0
pid 2520267 on Linux 7.1 (x86_64)
+++ exited with 0 +++
```

Expand Down Expand Up @@ -392,4 +392,4 @@ snapshotted kernel instead of yours.

---

<p><span class="status status--verified">verified</span> — runner table PASS for cpp, go, and rust on the Fedora 44 host (kernel 7.1.3-200.fc44, GCC 16.1.1, go1.26.5, rustc 1.97.1): each binary printed <code>pid &lt;PID&gt; on Linux 7.1.3-200.fc44.x86_64 (x86_64)</code>, and the strace excerpts above are real trimmed output from those binaries. The CLion section remains unverified as noted.</p>
<p><span class="status status--verified">verified</span> — runner table PASS for cpp, go, and rust on the Fedora 44 host (kernel 7.1, GCC 16.1.1, go1.26.5, rustc 1.97.1): each binary printed <code>pid &lt;PID&gt; on Linux 7.1 (x86_64)</code>, and the strace excerpts above are real trimmed output from those binaries. The CLion section remains unverified as noted.</p>
8 changes: 4 additions & 4 deletions _docs/02-lab-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ A VM answers all three at once, and adds the property no container gives you:
**its own kernel**. Namespaces share the host kernel, so a container can't show
you kernel-version drift, can't be probed as an isolated kernel, and can't be
snapshot-reverted with its kernel state. The lab guests run their own
`6.19.10-300.fc44` kernel while the host runs `7.1.3-200.fc44` — a visible
`6.19.10-300.fc44` kernel while the host runs `7.1` — a visible
difference this chapter turns into its cross-check.

That said, the VM is not the default. The book's decision rule, applied at the
Expand Down Expand Up @@ -298,14 +298,14 @@ than, say, quietly running the local binary. Run it both ways:
```bash
[host]$ cd examples/01-hello-syscalls
[host]$ ./demo.sh cpp
pid <PID> on Linux 7.1.3-200.fc44.x86_64 (x86_64)
pid <PID> on Linux 7.1 (x86_64)
[host]$ TARGET=systems-target ./demo.sh cpp
→ copying app to fedora@192.168.124.7:/home/fedora/app
→ running on systems-target (Ctrl-C to stop):
pid <PID> on Linux 6.19.10-300.fc44.x86_64 (x86_64)
```

Same binary, two different kernel strings: `7.1.3-200.fc44` is your host,
Same binary, two different kernel strings: `7.1` is your host,
`6.19.10-300.fc44` is the guest. The example's per-language `demo.sh` wires
this up — with `TARGET` set, its `run` step calls
`scripts/lab/deploy-to-vm.sh "$TARGET" <binary>` instead of executing locally,
Expand Down Expand Up @@ -339,4 +339,4 @@ stack**, so every later demo has somewhere to send its telemetry.

---

<p><span class="status status--verified">verified</span> — both guests were provisioned from Fedora-Cloud-Base-Generic-44-1.7 on this host (target 4 GB at 192.168.124.7, peer 2 GB at 192.168.124.95); <code>/var/log/lab-ready</code> read back <code>bpftrace v0.24.2</code> and kernel <code>6.19.10-300.fc44</code> on both; <code>lab-ready</code> snapshots exist on both; and <code>deploy-to-vm.sh</code> ran the host-built C++ and Go binaries on <code>systems-target</code>, printing the guest kernel string <code>6.19.10-300.fc44.x86_64</code> versus <code>7.1.3-200.fc44.x86_64</code> locally. The <strong>&ldquo;When the guest falls behind the host&rdquo;</strong> section was added later and is verified separately, on the same lab: the host&rsquo;s <code>libstdc++</code> reached <code>16.2.1-2.fc44</code> (<code>libstdc++.so.6.0.36</code>, max <code>GLIBCXX_3.4.36</code>) while both guests sat at <code>16.1.1-2.fc44</code> (<code>libstdc++.so.6.0.35</code>, max <code>GLIBCXX_3.4.35</code>) behind snapshots taken before the update, and every host-built C++ binary then failed on the guest with the quoted <code>version `GLIBCXX_3.4.36&#39; not found</code>. A full-matrix run reproduced the asymmetry the section describes — six VM examples failing in C++ while Go and Rust passed on the same guest in the same run — and the quoted diagnostic commands, the <code>dnf</code> fix, and the re-snapshot were all run here: after <code>revert-vm.sh systems-target lab-ready</code> the guest reported <code>GLIBCXX_3.4.36</code> and <code>test-all-examples.py --mode vm --lang cpp</code> reported the quoted <code>8 passed, 0 failed, 0 skipped</code>, including the two-guest <code>41-capstone-fleet</code>. <code>systems-peer</code> was confirmed to carry the same drift while showing no symptom. Not exercised: <span class="status status--unverified">unverified</span> — the <code>GLIBC_</code> form of the symbol check is stated by analogy and was not the failure encountered here, which was <code>GLIBCXX_</code> only; and building inside the guest with the in-VM toolchains is named as the standing fallback but is not exercised by any example in this book.</p>
<p><span class="status status--verified">verified</span> — both guests were provisioned from Fedora-Cloud-Base-Generic-44-1.7 on this host (target 4 GB at 192.168.124.7, peer 2 GB at 192.168.124.95); <code>/var/log/lab-ready</code> read back <code>bpftrace v0.24.2</code> and kernel <code>6.19.10-300.fc44</code> on both; <code>lab-ready</code> snapshots exist on both; and <code>deploy-to-vm.sh</code> ran the host-built C++ and Go binaries on <code>systems-target</code>, printing the guest kernel string <code>6.19.10-300.fc44.x86_64</code> versus <code>7.1</code> locally. The <strong>&ldquo;When the guest falls behind the host&rdquo;</strong> section was added later and is verified separately, on the same lab: the host&rsquo;s <code>libstdc++</code> reached <code>16.2.1-2.fc44</code> (<code>libstdc++.so.6.0.36</code>, max <code>GLIBCXX_3.4.36</code>) while both guests sat at <code>16.1.1-2.fc44</code> (<code>libstdc++.so.6.0.35</code>, max <code>GLIBCXX_3.4.35</code>) behind snapshots taken before the update, and every host-built C++ binary then failed on the guest with the quoted <code>version `GLIBCXX_3.4.36&#39; not found</code>. A full-matrix run reproduced the asymmetry the section describes — six VM examples failing in C++ while Go and Rust passed on the same guest in the same run — and the quoted diagnostic commands, the <code>dnf</code> fix, and the re-snapshot were all run here: after <code>revert-vm.sh systems-target lab-ready</code> the guest reported <code>GLIBCXX_3.4.36</code> and <code>test-all-examples.py --mode vm --lang cpp</code> reported the quoted <code>8 passed, 0 failed, 0 skipped</code>, including the two-guest <code>41-capstone-fleet</code>. <code>systems-peer</code> was confirmed to carry the same drift while showing no symptom. Not exercised: <span class="status status--unverified">unverified</span> — the <code>GLIBC_</code> form of the symbol check is stated by analogy and was not the failure encountered here, which was <code>GLIBCXX_</code> only; and building inside the guest with the in-VM toolchains is named as the standing fallback but is not exercised by any example in this book.</p>
2 changes: 1 addition & 1 deletion _docs/04-syscalls-and-the-abi.md
Original file line number Diff line number Diff line change
Expand Up @@ -388,4 +388,4 @@ Rust — that every later example in the book obeys.

---

<p><span class="status status--verified">verified</span> — all numbers in this chapter are from this session's runs on the Fedora 44 reference host (kernel <code>7.1.3-200.fc44</code>, glibc 2.43, strace 7.1): the harness reported <code>PASS</code> for cpp/go/rust and each binary printed the five-line block ending <code>sysprobe: 4 steps ok</code>; <code>strace -c</code> totaled 70 (cpp), 283 (go, <code>-cf</code>), and 73 (rust); the vdso-probe run showed 0 <code>clock_gettime</code> and 2 <code>getrandom</code> syscalls for 1000 calls each, including <code>getrandom("…", 32, 0) = 32</code>; the quoted sequence traces (<code>O_TMPFILE</code> openat, 25-byte write, <code>clock_nanosleep</code> vs raw <code>nanosleep</code>, Go's 20 µs-doubling monitor sleeps) are trimmed real output; <code>objdump</code> counted 0/511/32 <code>syscall</code> instructions; and <code>/proc/self/maps</code> showed the quoted <code>[vdso]</code>/<code>[vvar_vclock]</code> mappings. Not run here: the bpftrace kernel-side count (lab-VM callout above).</p>
<p><span class="status status--verified">verified</span> — all numbers in this chapter are from this session's runs on the Fedora 44 reference host (kernel <code>7.1</code>, glibc 2.43, strace 7.1): the harness reported <code>PASS</code> for cpp/go/rust and each binary printed the five-line block ending <code>sysprobe: 4 steps ok</code>; <code>strace -c</code> totaled 70 (cpp), 283 (go, <code>-cf</code>), and 73 (rust); the vdso-probe run showed 0 <code>clock_gettime</code> and 2 <code>getrandom</code> syscalls for 1000 calls each, including <code>getrandom("…", 32, 0) = 32</code>; the quoted sequence traces (<code>O_TMPFILE</code> openat, 25-byte write, <code>clock_nanosleep</code> vs raw <code>nanosleep</code>, Go's 20 µs-doubling monitor sleeps) are trimmed real output; <code>objdump</code> counted 0/511/32 <code>syscall</code> instructions; and <code>/proc/self/maps</code> showed the quoted <code>[vdso]</code>/<code>[vvar_vclock]</code> mappings. Not run here: the bpftrace kernel-side count (lab-VM callout above).</p>
2 changes: 1 addition & 1 deletion _docs/06-concurrency-three-ways.md
Original file line number Diff line number Diff line change
Expand Up @@ -407,7 +407,7 @@ of `fwatch`, where the question stops being "who runs the code" and becomes
---

<p><span class="status status--verified">verified</span> — every number above
comes from runs on the Fedora 44 reference host (kernel 7.1.3-200.fc44) this
comes from runs on the Fedora 44 reference host (kernel 7.1) this
session: the runner reported <code>06-concurrency-three-ways PASS PASS
PASS</code> (3 passed, 0 failed, Go built with <code>-race</code>); the
fixture outputs of the three binaries were <code>cmp</code>-identical,
Expand Down
14 changes: 7 additions & 7 deletions _docs/07-fds-raii-and-the-vfs.md
Original file line number Diff line number Diff line change
Expand Up @@ -432,9 +432,9 @@ inodes agree, field for field:

```bash
[host]$ ls -li tree
68626 -rw-r--r-- 1 rsedor rsedor 5 Sep 8 2001 a.txt
68627 -rw-r--r-- 1 rsedor rsedor 3 Sep 8 2001 gone.txt
68624 drwxr-xr-x 3 rsedor rsedor 80 Jul 18 23:02 sub
68626 -rw-r--r-- 1 user user 5 Sep 8 2001 a.txt
68627 -rw-r--r-- 1 user user 3 Sep 8 2001 gone.txt
68624 drwxr-xr-x 3 user user 80 Jul 18 23:02 sub
[host]$ stat --format='%i %s %Y %n' tree/a.txt tree/sub/b.txt
68626 5 1000000000 tree/a.txt
68628 9 1000000100 tree/sub/b.txt
Expand Down Expand Up @@ -480,10 +480,10 @@ files, delaying each stat by 20 ms leaves minutes to inspect:
[host]$ strace -o /dev/null -e trace=newfstatat -e inject=newfstatat:delay_enter=20000 \
./cpp/build/release/app snapshot big > /dev/null &
[host]$ ls -l /proc/<pid>/fd
lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 3 -> …/fixture/big
lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 4 -> …/fixture/big/l1
lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 5 -> …/fixture/big/l1/l2
lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 6 -> …/fixture/big/l1/l2/l3
lr-x------ 1 user user 64 Jul 18 23:03 3 -> …/fixture/big
lr-x------ 1 user user 64 Jul 18 23:03 4 -> …/fixture/big/l1
lr-x------ 1 user user 64 Jul 18 23:03 5 -> …/fixture/big/l1/l2
lr-x------ 1 user user 64 Jul 18 23:03 6 -> …/fixture/big/l1/l2/l3
[host]$ cat /proc/<pid>/fdinfo/6
pos: 1980
flags: 02700000
Expand Down
2 changes: 1 addition & 1 deletion _docs/08-page-cache-and-durability.md
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,7 @@ Next, **event loops**: `epoll` and `inotify`, where the question stops being

<p><span class="status status--verified">verified</span> — all numbers above
are from runs performed on the reference host (btrfs on NVMe, Fedora 44,
kernel 7.1.3-200.fc44) while writing this chapter: the mode reports
kernel 7.1) while writing this chapter: the mode reports
(<code>ms=21 / fsync_ms=17</code>, <code>ms=138</code>, <code>ms=81</code> at
64 MiB; Go/Rust buffered parity), the <code>strace -c</code> table (16
<code>fdatasync</code>, 65 <code>write</code>), the <code>Dirty:</code>
Expand Down
10 changes: 5 additions & 5 deletions _docs/09-event-loops-epoll-inotify.md
Original file line number Diff line number Diff line change
Expand Up @@ -480,10 +480,10 @@ list is inspectable. With a watcher running (PID via `$!`):

```bash
[host]$ ls -l /proc/$PID/fd | tail -4
lr-x------ 1 rsedor rsedor 64 Jul 18 23:06 3 -> anon_inode:inotify
lrwx------ 1 rsedor rsedor 64 Jul 18 23:06 4 -> anon_inode:[timerfd]
lrwx------ 1 rsedor rsedor 64 Jul 18 23:06 5 -> anon_inode:[signalfd]
lrwx------ 1 rsedor rsedor 64 Jul 18 23:06 6 -> anon_inode:[eventpoll]
lr-x------ 1 user user 64 Jul 18 23:06 3 -> anon_inode:inotify
lrwx------ 1 user user 64 Jul 18 23:06 4 -> anon_inode:[timerfd]
lrwx------ 1 user user 64 Jul 18 23:06 5 -> anon_inode:[signalfd]
lrwx------ 1 user user 64 Jul 18 23:06 6 -> anon_inode:[eventpoll]
[host]$ cat /proc/$PID/fdinfo/6
tfd: 3 events: 19 data: 0 pos:0 ino:426 sdev:11
tfd: 4 events: 19 data: 1 pos:0 ino:426 sdev:11
Expand Down Expand Up @@ -564,7 +564,7 @@ tells you it is *done*.

<p><span class="status status--verified">verified</span> — all evidence in
this chapter was produced on the Fedora 44 reference host (kernel
7.1.3-200.fc44, strace 7.1) this session: the runner reported
7.1, strace 7.1) this session: the runner reported
<code>PASS</code> for cpp, go, and rust (3 passed, 0 failed, 0 skipped); the
create/append/delete session printed exactly <code>event: created
a.txt</code>, <code>event: deleted a.txt</code>, <code>fwatch: exiting
Expand Down
4 changes: 2 additions & 2 deletions _docs/10-io-uring.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ languages, three answers to the same question: *who owns the event loop?*

> **Research note — io_uring on this kernel, from primary sources.** Claims
> about io_uring age fast, so this chapter cites only what this host shows.
> Kernel `7.1.3-200.fc44` reported 18 `IORING_FEAT_*` flags in the
> Kernel `7.1` reported 18 `IORING_FEAT_*` flags in the
> `io_uring_setup` params during our traced run — from `SINGLE_MMAP` and
> `NODROP` through `RECVSEND_BUNDLE`, `MIN_TIMEOUT`, `RW_ATTR`, and
> `NO_IOWAIT` — and the shipped `io_uring(7)`, `io_uring_setup(2)`, and
Expand Down Expand Up @@ -520,4 +520,4 @@ us to the capstone.

---

<p><span class="status status--verified">verified</span> — all numbers above are from this session's runs on the Fedora 44 host (kernel 7.1.3-200.fc44): the runner table passed 3/3 (cpp, go, rust); the 403-file/19,507,360-byte tree synced with <code>engine=rw</code> in 11–12 ms (C++) and 12–13 ms (Rust) versus 129–137 ms and 105–107 ms with <code>engine=uring</code>; <code>strace -c</code> counted 850 read + 444 write (rw) against 407 io_uring_enter + 1 io_uring_setup (uring, loader-only read/write 4/1); the fixture uring sync used 5 enters and printed <code>synced 5 files 1348634 bytes engine=uring ms=3</code>; the io_uring_setup/mmap trace, the <code>diff -r</code>/<code>cmp</code> byte-equality, the Go refusal (<code>engine=uring: unsupported in Go (see chapter 10)</code>, exit 64), and the empty <code>grep -c io_uring</code> against podman's seccomp profile were all reproduced as quoted. Unverified: the bpftrace probe in the lab-VM callout, as marked.</p>
<p><span class="status status--verified">verified</span> — all numbers above are from this session's runs on the Fedora 44 host (kernel 7.1): the runner table passed 3/3 (cpp, go, rust); the 403-file/19,507,360-byte tree synced with <code>engine=rw</code> in 11–12 ms (C++) and 12–13 ms (Rust) versus 129–137 ms and 105–107 ms with <code>engine=uring</code>; <code>strace -c</code> counted 850 read + 444 write (rw) against 407 io_uring_enter + 1 io_uring_setup (uring, loader-only read/write 4/1); the fixture uring sync used 5 enters and printed <code>synced 5 files 1348634 bytes engine=uring ms=3</code>; the io_uring_setup/mmap trace, the <code>diff -r</code>/<code>cmp</code> byte-equality, the Go refusal (<code>engine=uring: unsupported in Go (see chapter 10)</code>, exit 64), and the empty <code>grep -c io_uring</code> against podman's seccomp profile were all reproduced as quoted. Unverified: the bpftrace probe in the lab-VM callout, as marked.</p>
Loading
Loading