Explain a missing tun device where the failure actually happens
Build App (Preview) / compute-version (pull_request) Successful in 3s
Build App (Preview) / create-release (pull_request) Successful in 1s
Build App (Preview) / build-macos (pull_request) Successful in 2m37s
Build App (Preview) / build-linux (pull_request) Successful in 5m30s
Build App (Preview) / build-windows (pull_request) Successful in 5m55s
Build App (Preview) / prune-previews (pull_request) Successful in 3s
Build App (Preview) / compute-version (pull_request) Successful in 3s
Build App (Preview) / create-release (pull_request) Successful in 1s
Build App (Preview) / build-macos (pull_request) Successful in 2m37s
Build App (Preview) / build-linux (pull_request) Successful in 5m30s
Build App (Preview) / build-windows (pull_request) Successful in 5m55s
Build App (Preview) / prune-previews (pull_request) Successful in 3s
Review caught that the device guard was wired to the wrong call. The
daemon does not resolve `--device` at create: verified against Docker
29.7, `docker create --device /dev/does-not-exist` succeeds and prints an
id, and runc only resolves the device — and validates sysctls — when it
builds the container. So on a host with no tun module the create returns
fine and `start` fails, which means the explanation never ran and the
user saw the raw daemon string naming a path they would go looking for on
the wrong machine. The unit tests fed the create-side string straight in,
so they confirmed a function no real failure could reach.
Move the guard onto `start_container`, covering create as well in case a
future daemon checks earlier. It no longer takes `vpn_support_enabled` —
`start_container` has a container id and no project, and nothing else in
Triple-C ever requests a device, so an error naming /dev/net/tun is
unambiguous on its own. The test now uses the daemon's verbatim message
via bollard's real Display format.
Also from review:
* Soften the security claim. Docker does not enable user-namespace
remapping by default, so this is a real CAP_NET_ADMIN in the initial
user namespace with only the network namespace confining it. It
cannot touch host interfaces, but "confers no authority outside the
container" was too strong: within its namespace it can set
promiscuous mode and add addresses, routes and NAT on the shared
docker0 segment, which puts sibling containers — the LiteLLM gateway
among them — within ARP-spoofing reach, and it can flush netfilter
rules sandbox mode may rely on. Said plainly in the code, CLAUDE.md
and HOW-TO-USE.
* Drop Tailscale from the list of clients needing this. Its
--tun=userspace-networking mode needs neither the capability nor the
device, and listing it invites granting NET_ADMIN for nothing.
* Say in the toggle's own hint that changing it recreates the
container, matching how every other recreation-triggering setting is
labelled. The tab's generic "stop the container first" chip does not
tell the user what is about to happen.
* Add RuntimeSection tests: saves on, saves off explicitly rather than
dropping the key, reflects state, is disabled while running, and
carries the recreation warning.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
+14
-9
@@ -477,19 +477,24 @@ When enabled, the container is given the three things a VPN client needs to buil
|
||||
the `NET_ADMIN` capability, the `/dev/net/tun` device, and the `net.ipv4.conf.all.src_valid_mark`
|
||||
sysctl that WireGuard requires. This is **off by default**.
|
||||
|
||||
Without it, a client such as PIA, WireGuard, OpenVPN or Tailscale installs and its daemon starts
|
||||
normally, but the connection attempt **hangs until it times out** — a default container has no tun
|
||||
device to open and no permission to add an interface or a route, and most clients report that as a
|
||||
generic timeout rather than a permissions error.
|
||||
Without it, a client such as PIA, WireGuard or OpenVPN installs and its daemon starts normally, but
|
||||
the connection attempt **hangs until it times out** — a default container has no tun device to open
|
||||
and no permission to add an interface or a route, and most clients report that as a generic timeout
|
||||
rather than a permissions error.
|
||||
|
||||
Things worth knowing:
|
||||
|
||||
- `NET_ADMIN` applies to the container's **own** network namespace. It confers no authority over
|
||||
the host's interfaces or over any other container. It does mean anything running in the
|
||||
container can reconfigure that namespace, which is why it is opt-in.
|
||||
- Tailscale is the exception: in its `--tun=userspace-networking` mode it needs neither the
|
||||
capability nor the device, so leave this off if that is all you want.
|
||||
|
||||
- `NET_ADMIN` applies to the container's **own** network namespace — it cannot touch the host's
|
||||
interfaces. It is not nothing, though: within that namespace anything in the container can set
|
||||
promiscuous mode and add arbitrary addresses, routes and firewall rules on the Docker bridge it
|
||||
shares with your other containers, and it can flush firewall rules that sandbox mode relies on.
|
||||
Grant it per project, to projects that need it.
|
||||
- The **Docker host's** kernel must have the `tun` module available. With Docker Desktop that is
|
||||
the Linux VM, not your own machine. If it is missing, the container fails to create with an
|
||||
error naming `/dev/net/tun` and pointing back at this setting.
|
||||
the Linux VM, not your own machine. If it is missing, the container is created but fails to
|
||||
**start**, with an error naming `/dev/net/tun` and pointing back at this setting.
|
||||
- A VPN client's kill switch applies to everything in the container, Claude Code included. If the
|
||||
tunnel drops, expect API calls to fail until it reconnects or the kill switch is turned off.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user