azinchen/openconnect-client repository overview

⁠OpenConnect VPN Client Docker container

OpenConnect VPN client in a Docker container that routes other containers' traffic through an ocserv / Cisco AnyConnect-compatible server, with a dual-stack fail-closed kill switch. Built as the companion client for azinchen/ocserv-server⁠: same configuration style, and a "route other containers through network_mode: service:vpn" workflow. Since it runs the plain openconnect client it also connects to GlobalProtect, Pulse/Ivanti, Fortinet and other servers via PROTOCOL.

Full documentation lives in the project wiki⁠.

⁠✨ Features

• 🔗 Shared-netns forwarding — network_mode: service:vpn puts a container behind the tunnel (details⁠)
• 🚪 Gateway mode — NAT gateway for other containers and LAN hosts (macvlan / routed) (details⁠)
• 🧭 Daemon-free gateway DNS — client DNS intercepted by nftables DNAT, no resolver process (details⁠)
• 🌐 Full dual-stack — IPv4 and IPv6 for the connection, the tunnel and the firewall (details⁠)
• 🛡️ Fail-closed kill switch — one nftables table, up before openconnect starts, never removed (details⁠)
• 🔁 Ordered failover — ;-separated server list in URL, next entry after repeated failures (details⁠)
• 🕵️ Camouflage support — ocserv camouflage secret in the URL, redacted from logs (details⁠)
• 🔌 Multi-protocol — AnyConnect, GlobalProtect, Pulse, Fortinet, NC and Array via PROTOCOL (details⁠)
• 🔐 Flexible auth — password, secret file or client cert; trust by CA file or pin (details⁠)
• 🔄 Supervised reconnect — restarts with exponential backoff on top of openconnect's own (details⁠)
• 🩺 Opt-in health check — Docker HEALTHCHECK probes real egress through the tunnel (details⁠)
• 🏠 LAN access — NETWORK / NETWORK6 add return routes and firewall holes (details⁠)
• 🪜 TTL normalization — TTL_SET hides the hops behind the container from traceroutes (details⁠)
• 🔍 Network diagnostics — dump addresses, routes and the nftables ruleset (details⁠)
• 📦 Small multi-arch Alpine image — 386, amd64, arm/v6, arm/v7, arm64, riscv64 (details⁠)

⁠🚀 Quick start

services:
  vpn:
    image: azinchen/openconnect-client:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    sysctls:
      - net.ipv6.conf.all.disable_ipv6=0
    environment:
      - URL=https://vpn.example.com:8443/?mysecret
      - USER=alex
      - PASS=secret
      - CA_FILE=/openconnect-client/ca.pem
      - NETWORK=192.168.1.0/24
    volumes:
      - ./config:/openconnect-client:ro
    ports:
      - "8080:80"          # app UI published on the vpn service
  app:
    image: nginx:alpine
    network_mode: "service:vpn"
    depends_on:
      - vpn

Everything the app container sends now goes through the tunnel — or nowhere. See the wiki's Docker Compose Examples⁠ for complete compositions of both modes.

⁠🔗 Connection URL

A single URL variable carries host, port and camouflage secret, matching openconnect's own positional argument and ocserv's camouflage semantics:

URL=https://vpn.example.com                    # port 443, no camouflage
URL=https://vpn.example.com:8443/?mysecret     # custom port + camouflage
URL=vpn.example.com                            # bare host, https:// implied
URL=https://[2001:db8::1]:8443                 # IPv6 literal
URL=https://a.example.com;https://b.example.com:8443/?s2   # ordered failover

Only https is accepted; the port (default 443) applies to both TCP and DTLS; each list entry is a complete URL with its own port and secret. The query string is passed to openconnect verbatim and redacted in logs (note: like any environment variable it remains visible in docker inspect).

⁠⚙️ Environment variables

Grouped by feature; every variable is one line here — the Configuration Reference⁠ has the full descriptions.

⁠Connection — details⁠

⁠Authentication and server trust — details⁠

⁠Tunnel tuning

⁠IPv6 — details⁠

⁠Local network access — details⁠

⁠Gateway mode — details⁠

⁠DNS

⁠Reconnection and health — details⁠

⁠Diagnostics and miscellaneous — details⁠

⁠🔐 Authentication and server trust

Mirrors ocserv's auth modes: password (USER + PASS/PASS_FILE, piped via --passwd-on-stdin), certificate (CERT_FILE as .p12/.pfx with optional CERT_PASS, or PEM CERT_FILE + KEY_FILE), or both simultaneously (ocserv auth = certificate + enable-auth = plain). Mount cert material into /openconnect-client.

Server trust, in order of preference: CA_FILE (mount the ocserv-server CA), SERVERCERT (pin-sha256: pin for self-signed setups), a publicly valid certificate, or the INSECURE=true escape hatch.

⁠🔀 Traffic modes

⁠Mode A — shared network namespace

Co-located containers (network_mode: service:vpn) share the VPN container's network stack, so tunnel routes and the kill switch protect them identically. Publish the app's ports on the vpn service and list the LAN subnets that need to reach those ports in NETWORK/NETWORK6. This is the recommended mode for compose stacks.

⁠Mode B — gateway mode

GATEWAY_MODE=true turns the container into a NAT gateway for clients that keep their own network namespace: containers on the same Docker network and LAN hosts with a route (or macvlan default gateway) pointing at the container. Requires forwarding sysctls from the runtime:

sysctls:
  - net.ipv4.ip_forward=1
  - net.ipv6.conf.all.forwarding=1
  - net.ipv6.conf.all.disable_ipv6=0

FORWARD_FROM/FORWARD_FROM6 limit which sources may use the gateway (default: the container's own eth0 subnets). IPv6 is masqueraded (NAT66) by default because ocserv assigns a single client address; set GATEWAY_NAT6=false if your server routes the client subnet.

Gateway-client DNS is intercepted without any daemon in the image. GATEWAY_DNS picks the mode: redirect (default) sends client DNS to the tunnel-pushed resolvers, local to a co-located resolver such as AdGuard Home or Pi-hole, forward to an external resolver reached directly over eth0, and off leaves it alone. Containers using Docker's embedded DNS (127.0.0.11) bypass the gateway; give them an explicit dns:. See Gateway DNS⁠ for the details of each mode.

⁠🌐 IPv6

Both families are dropped by default in one nftables table, so an IPv6-enabled Docker network cannot leak around an IPv4-only firewall. The tunnel's IPv6 data plane requires the server to push an IPv6 address (the IPV6_* variables of azinchen/ocserv-server); IPV6_MODE controls what happens when it doesn't: auto runs IPv4-only and keeps IPv6 dropped, require treats it as a connection failure, off never asks for IPv6. Connectivity to the server over IPv6 additionally needs an IPv6-enabled Docker network (enable_ipv6: true); the tunnel's IPv6 works regardless once the session is up over IPv4.

⁠🩺 Health check

The image ships a Docker HEALTHCHECK (60s interval) that is neutral until HEALTH_CHECK_ENABLED=true. When enabled it verifies the tun interface and its addresses, then probes CHECK_CONNECTION_URL through the tunnel (IPv4, plus IPv6 when IPV6_MODE=require). Combine with an autoheal-style restarter to recycle an unhealthy container.

⁠📋 Runtime requirements

• --cap-add=NET_ADMIN and /dev/net/tun
• a kernel with nftables support (any modern host)
• for gateway mode: the forwarding sysctls shown above

⁠📄 License

MIT⁠