unredacted · lunarthegrey · May 5, 2026 · May 5, 2026 · May 5, 2026 · May 5, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -23,7 +23,7 @@ exclude = [
 # detach pacing for bridge members, integrity-check Total-line parse
 # fix). See SPEC.md §11.14 for the rollout history and
 # `docs/runbooks/custom-fib.md` for operations.
-version = "0.2.3"
+version = "0.2.4"
 edition = "2021"
 # MSRV. Deliberately behind the rust-toolchain.toml pin (which is the
 # latest stable) so a contributor with a slightly older toolchain still

diff --git a/README.md b/README.md
@@ -71,8 +71,13 @@ PacketFrame complements existing routing daemons rather than replacing them. The
 | Connected-destination fast-path (`local-prefix`) | Production (v0.2.1+) |
 | `fallback-default` synthesis | Production (v0.2.1+) |
 | `block-prefix` XDP-time drop | Production (v0.2.1+) |
+| `mss-clamp` directive (fast-path) | Production (v0.2.4+) |
+| `packetframe reconfigure` / `systemctl reload packetframe` | Production (v0.2.4+) |
 | `probe` module — diagnostic XDP | Production |
-| `randomizer` / `ddos` / `sampler` modules | Future — sketched in SPEC, not implemented |
+| `ddos` module — XDP-time SYN-flood + amplification filter | Future — sketched in SPEC §5.2 (priority 0–999, security/admission) |
+| `sampler` module — per-flow ringbuf observability | Future — sketched in SPEC §5.3 (priority 2000–2999, observation) |
+| `randomizer` module — TC egress jitter for NoiseNet anti-correlation | Future — sketched in SPEC §5.1 (priority ~3000, egress) |
+| Multi-module dispatcher (prerequisite for any second module on the same hook) | Future — module trait already shaped for it (SPEC §3.2 / §3.4) |
 
 ## Install
 
@@ -81,7 +86,7 @@ Releases are published on the [GitHub releases page](https://github.com/unredact
 ### Debian / Ubuntu (.deb)
 
 ```sh
-VERSION=v0.2.3
+VERSION=v0.2.4
 ARCH=$(dpkg --print-architecture)   # amd64 or arm64
 
 curl -LO "https://github.com/unredacted/packetframe/releases/download/${VERSION}/packetframe_${VERSION#v}_${ARCH}.deb"
@@ -98,7 +103,7 @@ Installs `/usr/bin/packetframe`, the systemd unit at `/lib/systemd/system/packet
 For musl-static deployments, non-Debian distros, or anything else:
 
 ```sh
-VERSION=v0.2.3
+VERSION=v0.2.4
 TARGET=aarch64-unknown-linux-gnu     # or: x86_64-unknown-linux-{gnu,musl}, aarch64-unknown-linux-musl
 
 curl -LO "https://github.com/unredacted/packetframe/releases/download/${VERSION}/packetframe-${VERSION}-${TARGET}.tar.gz"
@@ -140,6 +145,9 @@ module fast-path
   allow-prefix6 2001:db8::/48
   dry-run on                       # observe-only — no redirects yet
   circuit-breaker drop-ratio 0.01 of matched window 5s threshold 5
+  # mss-clamp via eth0 1360       # optional — clamp TCP MSS for fast-pathed
+                                   # traffic egressing eth0 (closes the
+                                   # iptables-bypass MSS gap; v0.2.4+)
 ```
 
 `dry-run on` makes the program count matched packets but always return `XDP_PASS` — the kernel handles forwarding as if PacketFrame weren't there. Counters tell you whether your allowlist matches the right traffic before you flip the switch.
@@ -161,7 +169,14 @@ sudo packetframe status              # in another shell — live counters
 
 ### 5. Flip dry-run off when match ratios look right
 
-Edit the config, change `dry-run on` to `dry-run off`, then `sudo systemctl reload packetframe` (if running under systemd) or `kill -HUP <pid>` (foreground). The change is delta-only; no detach.
+Edit the config, change `dry-run on` to `dry-run off`, then trigger a reload (v0.2.4+):
+
+```sh
+sudo packetframe reconfigure                # synchronous; exits non-zero on parse error
+sudo systemctl reload packetframe           # equivalent under systemd — both end up sending SIGHUP
+```
+
+What's hot-reloadable: `allow-prefix*`, `block-prefix`, `dry-run`, `forwarding-mode`, `mss-clamp`, VLAN-subif resolution, and the redirect devmap. Attach-set changes (interfaces added/removed), `route-source` config, `circuit-breaker` thresholds, and `local-prefix` still require a full restart. See [docs/runbooks/reconfigure.md](docs/runbooks/reconfigure.md).
 
 ### 6. Tear down
 
@@ -249,10 +264,16 @@ Quick directive index:
 - `block-prefix <cidr>` — XDP-time drop for unrouteable destinations
 - `ecmp-default-hash-mode {3|4|5}` — tuple width for ECMP hashing
 
+**Module fast-path — TCP transforms (v0.2.4+)**
+- `mss-clamp <mtu>` — global clamp ceiling for matched TCP SYN/SYN-ACK
+- `mss-clamp via <iface> <mtu>` — per-egress-iface
+- `mss-clamp <cidr> <mtu>` — per-src-or-dst-prefix (any egress)
+- `mss-clamp <cidr> via <iface> <mtu>` — most specific (precedence: prefix+iface > prefix > iface > global)
+
 **Module fast-path — driver opt-ins**
 - `driver-workaround rvu-nicpf-head-shift {auto|on|off}`
 
-`SIGHUP` reloads the config and applies delta-only changes to allowlists, VLAN-resolve, and devmap. Adding or removing an `attach` directive requires a restart.
+`SIGHUP` (or `packetframe reconfigure` / `systemctl reload packetframe`) applies delta-only changes to allowlists, block-prefix, VLAN-resolve, devmap, mss-clamp, dry-run, and forwarding-mode bits. Adding or removing an `attach`, changing `route-source`, mutating `circuit-breaker` thresholds, or editing `local-prefix` requires a restart.
 
 ## Operator tools
 

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.2.3
+0.2.4
diff --git a/conf/example.conf b/conf/example.conf
@@ -45,6 +45,28 @@ module fast-path
   # 1% of matched over 5 consecutive 5-second samples.
   circuit-breaker drop-ratio 0.01 of matched window 5s threshold 5
 
+  # MSS clamping for fast-pathed TCP SYN/SYN-ACK packets (v0.2.4+,
+  # SPEC.md §4.x — closes the §11.4 iptables-bypass gap). Standard
+  # iptables `-A FORWARD ... TCPMSS --set-mss N` rules don't fire on
+  # XDP-redirected traffic because bpf_redirect_map skips netfilter;
+  # this directive runs the equivalent mutation inline before the
+  # redirect.
+  #
+  # Lookup precedence (most specific wins, lower-if-higher policy):
+  #   1. mss-clamp <cidr> via <iface> <mtu>   (prefix + egress iface)
+  #   2. mss-clamp <cidr> <mtu>                (prefix, any egress)
+  #   3. mss-clamp via <iface> <mtu>           (egress iface, any prefix)
+  #   4. mss-clamp <mtu>                       (global default)
+  #
+  # Prefix matches src OR dst (mirrors allow-prefix semantics) so a
+  # single rule covers both directions of a flow. Clamped on both SYN
+  # and SYN-ACK so each end's announced MSS is constrained per-direction.
+  # See docs/runbooks/mss-clamp.md for MSS vs MTU math + troubleshooting.
+  #
+  # mss-clamp via eth2 1360                  # outbound: leaving WAN
+  # mss-clamp 23.191.201.0/24 via eth2 1360  # outbound, scoped to one customer
+  # mss-clamp 1360                           # global fallback for all matched
+
   # Driver workaround for the pre-Linux-v6.8 rvu-nicpf native XDP bug
   # (SPEC.md §11.1(c); upstream fix is commit 04f647c8e456). Values:
   #   auto — detect rvu-nicpf via /sys and apply only on native attaches

diff --git a/crates/cli/debian/packetframe.service b/crates/cli/debian/packetframe.service
@@ -7,6 +7,8 @@ Wants=network-online.target
 [Service]
 Type=simple
 ExecStart=/usr/bin/packetframe run
+ExecReload=/bin/kill -HUP $MAINPID
+PIDFile=/var/lib/packetframe/state/packetframe.pid
 Restart=on-failure
 RestartSec=5
 User=root