Frank
5829a0bfe8
All in-repo path references (AGENTS.md, README, old scripts, report artifacts,
test code paths) rewritten in the same commit; focused-test map extended for
.gitignore, old/scripts/*, dankclaw/comfyui/*, and report/* per this repo's
own convention ('add one before committing'). Obsidian wikilinks are
title-based and unaffected.
75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# Gluetun
|
|
|
|
Gluetun is a lightweight VPN client container. It connects to a VPN provider (WireGuard or OpenVPN) and shares that tunnel with other containers that attach to its network namespace.
|
|
|
|
**Host:** Dankclaw — **Docs:** https://github.com/qdm12/gluetun
|
|
|
|
## Facts (from research, primary source)
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Image | `qmcgaw/gluetun:latest` |
|
|
| Capabilities | `NET_ADMIN` required |
|
|
| Device | `/dev/net/tun:/dev/net/tun` |
|
|
| Ports published | searxng's 8081 → 8080 lives here |
|
|
| Tunnel check | the `tun0` interface exists (the `:8000` server 404s on all paths) |
|
|
|
|
## Required Environment
|
|
|
|
```yaml
|
|
environment:
|
|
VPN_SERVICE_PROVIDER: "${VPN_SERVICE_PROVIDER}" # e.g. mullvad, protonvpn
|
|
VPN_TYPE: wireguard
|
|
WIREGUARD_PRIVATE_KEY: "${WIREGUARD_PRIVATE_KEY}" # from .env, never committed
|
|
```
|
|
|
|
- `VPN_TYPE` default is `openvpn`; WireGuard preferred when the provider supports it.
|
|
- Provider-specific variables come from the Gluetun wiki; set them in `.env`.
|
|
|
|
## Optional DNS (from research)
|
|
|
|
| Variable | Default | Purpose |
|
|
|----------|---------|---------|
|
|
| `DNS_UPSTREAM_RESOLVER_TYPE` | `dot` | DNS over TLS |
|
|
| `DNS_UPSTREAM_RESOLVERS` | `cloudflare` | upstream DoT providers |
|
|
| `DNS_CACHING` | `on` | cache queries |
|
|
| `BLOCK_MALICIOUS` | `on` | block malicious hostnames |
|
|
|
|
Warning from the wiki: do NOT set `DNS_UPSTREAM_PLAIN_ADDRESSES` to a LAN/bridge address — DNS queries leak out of the tunnel.
|
|
|
|
## Attaching a Container
|
|
|
|
The searxng unit reuses gluetun's network namespace:
|
|
|
|
```ini
|
|
[Container]
|
|
ContainerName=searxng
|
|
Network=gluetun.container
|
|
```
|
|
|
|
`Network=gluetun.container` also adds a systemd dependency on gluetun, so searxng starts after the tunnel.
|
|
|
|
## Boot Persistence
|
|
|
|
gluetun runs as the `gluetun` quadlet unit (see [[SearXNG]] for the full trio). It sets `WantedBy=default.target` and user linger is on, so the tunnel starts at boot. The WireGuard credentials live in `/opt/searxng/.env` (mode 0600). Deploy with `scripts/deploy-searxng-quadlet.sh dankclaw`.
|
|
|
|
## Verify the Tunnel
|
|
|
|
```bash
|
|
podman exec gluetun curl -s ifconfig.me
|
|
```
|
|
|
|
The returned IP must differ from the host IP.
|
|
|
|
## Gotchas
|
|
|
|
- The container that holds the published port must be the one with the ports mapping (gluetun).
|
|
- `restart: always` on gluetun so the tunnel reconnects after VPN drops.
|
|
- When gluetun restarts, attached containers inherit the new network state; searxng may need a restart to re-resolve DNS.
|
|
|
|
## See Also
|
|
|
|
- [[SearXNG]] — the consumer of the tunnel
|
|
- [[Dankclaw Stack]]
|
|
- Knowledge base: [[SearXNG]]
|