# 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: [[VPN Routing for SearXNG]]