Frank
93d1181fee
- Migrate all 127 non-reserved docs to OKF v0.1 frontmatter (type/description/tags/timestamp); fix 13 YAML issues, 2 duplicate-FM blocks, strip reserved-page FM - Restructure log.md to OKF (## YYYY-MM-DD, newest-first) - Fact-check against scripts/AGENTS.md ground truth: fix 6 false 'Active' banners on retired runbooks, 96->114 GiB GTT, deployment.md vs deploy-plan.py/deploy-remote.sh, Deployment Flow frank-medium=Quadlet, Calibre 9.9.0->9.15.0 + CVE-2025-7404 conflation, Copyparty v1.20.24, RomM 5.3.0 breaking change - Move *arr docs to new FrankBook-Pro/ section (git mv, link-safe) - Write active runbook bodies from ground truth (frank-large, frank-small) - Add 3 research briefs + HTML report: Local TTS and Voice Cloning, AI Job Search and Resume Tools, Most Popular Self-Hosted AI Apps (Jun-Sep 2026) - Add upstream-version rows to ComfyUI/OpenWebUI/Hermes app docs - All 336 tests pass; 136 pages, 0 unresolved wikilinks
84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
---
|
|
type: reference
|
|
description: "Gluetun is a lightweight VPN client container."
|
|
tags:
|
|
- dankclaw
|
|
- gluetun
|
|
timestamp: 2026-08-28
|
|
---
|
|
|
|
# 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]]
|