summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorJames O'Doherty <james@theodohertyfamily.com>2026-05-29 20:35:31 -0400
committerJames O'Doherty <james@theodohertyfamily.com>2026-05-29 20:35:31 -0400
commitd4cec92f5690a60b3509ab718bdea72dc520110e (patch)
treeb29218a4fee4bbf3b2f4bf25a161f2a74bb98b85 /README.md
parent4ddd0d2ffc7073f2d55ffb6777e3a168af0051f0 (diff)
feat: implement robust namespace lifecycle and resilience suite
- Replace marker-file pinning with kernel bind-mount anchors for reliable namespace persistence. - Implement atomic "last-man-out" cleanup sequence using ProfileLock, preventing namespace leaks and race conditions. - Add comprehensive resilience test suite covering: - Crash recovery from stale runtime state. - Host network change stability. - Configuration hot-swap session persistence. - Resource exhaustion and high-churn lifecycle stress. - Align documentation and test expectations with rootless session-based persistence. - Fix argument integrity and isolation leaks. - Ensure 100% pass rate for all E2E and integration tests.
Diffstat (limited to 'README.md')
-rw-r--r--README.md2
1 files changed, 1 insertions, 1 deletions
diff --git a/README.md b/README.md
index 6de14d1..679c49e 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ To achieve rootless network isolation without interfering with the Go runtime's
6. **FDBind Tunnel Initialization**: The second instance of `wg-wrap` detects it is now isolated, extracts the `WG_WRAP_HOST_SOCKET_FD` descriptor, and wraps it inside a custom `FDBind` struct to initialize `wireguard-go`. Because sockets in Linux retain their creation-time network namespace, WireGuard's encrypted UDP transport communicates natively over the host interface, while decrypted process traffic is entirely locked inside the unprivileged sandbox's `tun0`.
### Persistent Namespaces & Shared Sessions
-To support multiple concurrent commands on the same WireGuard tunnel without re-establishing connections, `wg-wrap` employs persistent, unprivileged namespaces:
+To support multiple concurrent commands on the same WireGuard tunnel without re-establishing connections, `wg-wrap` employs session-based persistent, unprivileged namespaces:
- **Tracking**: Process usage is tracked using active PID files inside `/run/user/$UID/wg-wrap/profiles/<name>/pids/`.
- **Ref-Counting & Cleanup**: Active PIDs are regularly pruned. When the last active process exits, the namespace is unpinned via `UnpinNamespace` and resources are cleanly reclaimed.
- **Setns Join**: When a new process is executed on an active profile, it discovers an active PID and calls `syscall.Setns` (via `golang.org/x/sys/unix`) to attach itself to the existing User, Mount, and Network namespaces of the active tunnel in $\approx 10\text{ms}$.