sni-router: review fixups (concise comments, accurate v6only note, narrow Caddy allow)

- Caddy allow: 127.0.0.0/8 → 127.0.0.1/32 (only loopback peer is HAProxy).
- haproxy.cfg: rewrite v6only comment to describe what it actually does
  (suppresses v4-mapped accept, preventing conflict with the v4 bind),
  not the symptom.
- docker-compose.yml: trim the 8-line haproxy comment to 3 lines and
  defer the rationale to README.  Add one-line note explaining why web
  uses host port 8080 (HAProxy owns :80).
- README: condense the "Why network_mode: host" subsection.  Spell out
  trade-offs as a list: own-the-host-ports, Linux-only (Docker Desktop
  doesn't make this layout reachable), userns-remap incompatibility.
  Note that mtg-config.toml stays as-is because mtg/web remain on the
  compose bridge.

contrib/sni-router/Caddyfile

@@ -11,7 +11,7 @@
 	# is terminated on the unwrapped connection.
 	#
 	# `allow` lists the networks permitted to send PROXY headers.
-	# 127.0.0.0/8 covers HAProxy reaching Caddy over host loopback (HAProxy
+	# 127.0.0.1/32 covers HAProxy reaching Caddy over host loopback (HAProxy
 	# runs in network_mode: host and connects to the published 127.0.0.1
 	# port).  The RFC1918 ranges cover mtg → Caddy on the compose bridge
 	# (fronting path; see "Fronting loop" in README.md).
@@ -19,7 +19,7 @@
 		listener_wrappers {
 			proxy_protocol {
 				timeout 5s
-				allow 127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
+				allow 127.0.0.1/32 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
 			}
 			tls
 		}

contrib/sni-router/README.md

@@ -65,23 +65,26 @@ to parse the connection.
 
 ### Why HAProxy uses `network_mode: host`
 
-When a container is on a bridge network and a port is published with
-`ports: "443:443"`, the source IP of inbound connections is rewritten
-to the bridge gateway before HAProxy sees it — Docker's `docker-proxy`
-userland forwarder accepts on the host and re-opens the connection
-from the gateway; Podman's `slirp4netns` / `pasta` does the same in
-rootless mode.  The PROXY v2 header HAProxy then sends downstream
-carries that gateway address (e.g. `172.x.x.1`), not the real client.
-
-`network_mode: host` puts HAProxy in the host network namespace, so it
-binds `:443` / `:80` directly with no NAT in the path and observes the
-true source address of every connection.  mtg and Caddy stay on the
-compose bridge and are published only on `127.0.0.1` — HAProxy reaches
-them via host loopback, and the PROXY v2 header carries the real
-client IP (v4 or v6) end-to-end.
-
-Trade-off: HAProxy occupies the host's `:443` and `:80`.  Don't run
-anything else on those ports on the same host.
+A published port on a bridge network rewrites the source IP of inbound
+connections to the bridge gateway before HAProxy sees it (Docker's
+`docker-proxy`, Podman's `slirp4netns`/`pasta`), so the PROXY v2 header
+HAProxy forwards downstream carries that gateway address, not the real
+client.  Host-mode HAProxy binds in the host netns directly, no NAT in
+the path, and the rewrite never happens.  mtg and Caddy stay on the
+compose bridge and are published on `127.0.0.1` only — HAProxy reaches
+them over host loopback.  `mtg-config.toml` does not need to change;
+fronting still uses `host = "web"` over compose-network DNS.
+
+**Trade-offs.**
+- HAProxy owns the host's `:443` and `:80` — don't run anything else
+  on those ports.
+- Linux host only.  On Docker Desktop (macOS/Windows), "host" means
+  the Linux VM, not the user's machine, so external clients can't
+  reach the proxy.
+- If you run Docker with `userns-remap`, the in-container "root"
+  loses the privilege to bind `<1024` on the host; either disable
+  `userns-remap` for this stack or lower `net.ipv4.ip_unprivileged_port_start`
+  on the host.
 
 ## Fronting loop (why `[domain-fronting]` is set explicitly)
 

contrib/sni-router/docker-compose.yml

@@ -27,15 +27,9 @@ x-domain-env: &domain-env
 services:
   haproxy:
     image: haproxy:lts-alpine
-    # network_mode: host lets HAProxy see real client source IPs (v4 and v6)
-    # instead of the docker/podman bridge gateway.  Bridge ingress (docker-proxy
-    # userland forwarder, podman slirp4netns/pasta) rewrites the source address
-    # of inbound connections to the gateway; with host networking HAProxy binds
-    # in the host netns directly and the rewrite never happens.  See the
-    # "Real client IPs" section of README.md.
-    #
-    # Trade-off: HAProxy occupies host :443 and :80.  Don't run anything else
-    # on those ports.
+    # Host netns so HAProxy sees real client IPs (v4/v6) instead of the
+    # bridge gateway address.  Linux host only; see README → "Why HAProxy
+    # uses network_mode: host" for the rationale and trade-off.
     network_mode: host
     volumes:
       - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro,Z
@@ -52,7 +46,7 @@ services:
     volumes:
       - ./mtg-config.toml:/config/config.toml:ro,Z
     # Published on host loopback only — HAProxy (host netns) reaches it via
-    # 127.0.0.1:3128.  Not exposed on any public interface.
+    # 127.0.0.1.
     ports:
       - "127.0.0.1:3128:3128"
     restart: unless-stopped
@@ -66,6 +60,7 @@ services:
       - caddy_data:/data
       - ./www:/srv:ro,Z
     # Published on host loopback only — HAProxy reaches Caddy on 127.0.0.1.
+    # Port 8080 (not 80) on the host because HAProxy already owns host :80.
     ports:
       - "127.0.0.1:8080:80"
       - "127.0.0.1:8443:8443"

contrib/sni-router/haproxy.cfg

@@ -24,8 +24,9 @@ defaults
 
 frontend http
     # Explicit v4 + v6 binds so IPv6 clients are accepted regardless of the
-    # host's IPV6_V6ONLY sysctl.  v6only on the v6 bind avoids the
-    # "address in use" overlap on dual-stack hosts.
+    # host's net.ipv6.bindv6only sysctl.  `v6only` on the v6 bind prevents it
+    # from also accepting v4-mapped connections, which would otherwise
+    # conflict with the explicit v4 bind on the same port.
     bind 0.0.0.0:80
     bind [::]:80 v6only
     mode http