azinchen/nordvpn

By azinchen

•Updated 9 days ago

NordVPN OpenVPN client in Docker: fail-closed kill switch, XOR obfuscation, gateway mode

Image

1M+

Overview Tags

azinchen/nordvpn repository overview

⁠NordVPN OpenVPN Docker Container

OpenVPN client docker container that routes other containers' traffic through NordVPN servers automatically.

Prefer WireGuard? This has a sibling project, azinchen/nordvpn-wg⁠ — the same auto-routing NordVPN container over WireGuard (NordLynx). Both share the same configuration model and feature set.

⁠✨ Key Features

🚀 Easy Setup — Route any container's traffic through VPN with --net=container:vpn
🌍 Server Selection — Auto-select servers by country, city, group, or specific hostname (details⁠)
⚖️ Load Balancing — Sorts by server load when multiple locations are given (details⁠)
🔑 Access Token — Pass TOKEN and the container fetches the service credentials itself (details⁠)
🔄 Automatic Reconnection — Periodic server switching and health monitoring (details⁠)
🕵️ XOR Obfuscation — Built-in XOR patches disguise OpenVPN traffic to bypass DPI (details⁠)
🛡️ Kill Switch — Default-deny firewall blocks all traffic when VPN is down (details⁠)
🏠 Local Network Access — Allow specific CIDRs with NETWORK=... (details⁠)
🧭 Custom DNS — Resolve through the tunnel; override with DNS=... (details⁠)
📵 IPv6 Configuration — Built-in chains default to DROP (details⁠)
🧱 Firewall Backends — Auto-selects nft or legacy backend (details⁠)
🚪 VPN Gateway Mode — Route downstream subnets through the tunnel with FORWARD_FROM (details⁠)
🪜 TTL Tuning — TTL_SET / TTL_INC hide cascade hops from client traceroutes (details⁠)
🩺 Docker Health Status — Opt-in HEALTHCHECK reports tunnel state to Docker (details⁠)
🔎 Network Diagnostics — Built-in network diagnostic tool and status.json status file (details⁠)

📖 Full documentation on the Wiki⁠ — configuration guides, examples, troubleshooting, FAQ, and architecture.

⁠🚀 Quick Start

docker run -d --cap-add=NET_ADMIN --device /dev/net/tun --name vpn \
           -e USER=service_username -e PASS=service_password \
           azinchen/nordvpn

Route other containers through VPN:

docker run --net=container:vpn -d your/application

Also available from GitHub Container Registry: ghcr.io/azinchen/nordvpn

⁠Getting Service Credentials

Log into your Nord Account Dashboard⁠
Click on NordVPN → Advanced Settings → Set up NordVPN manually
Go to the Service credentials tab
Copy the Username and Password shown there

Note: These are different from your regular NordVPN login credentials.

Alternative — access token: instead of copying the service credentials, generate an access token (Nord Account Dashboard → NordVPN → Advanced Settings → Generate new token) and pass it as TOKEN; the container then fetches the service credentials from the NordVPN API at startup. If USER/PASS are also set, they take priority over the token.

⁠🐳 Docker Compose Example

services:
  vpn:
    image: azinchen/nordvpn:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      - USER=service_username
      - PASS=service_password
      # - TOKEN=access_token       # alternative to USER/PASS
      - COUNTRY=United States;CA
      - RANDOM_TOP=10
      - RECREATE_VPN_CRON=0 */6 * * *
      - NETWORK=192.168.1.0/24
    ports:
      - "8080:80"                  # host:container — use your app's listening port
    restart: unless-stopped

  app:
    image: nginx:alpine
    network_mode: "service:vpn"
    depends_on:
      - vpn
    restart: unless-stopped

More examples: Docker Compose⁠ · Docker Run⁠

⁠⚙️ Environment Variables

Grouped by feature; every variable is one line here — the linked wiki pages have the full descriptions. List values (countries, cities, CIDRs, URLs, IPs) accept ; or , as separators; whitespace around separators is ignored.

⁠Credentials — details⁠

Variable	Default	Description
`USER`	—	NordVPN service credentials username (how to get them⁠). Required unless `TOKEN` is set.
`PASS`	—	NordVPN service credentials password. Required unless `TOKEN` is set.
`TOKEN`	—	NordVPN access token; the service credentials are fetched from the NordVPN API at startup. Ignored when `USER`/`PASS` are set.

⁠Server selection — details⁠

Variable	Default	Description
`COUNTRY`	—	Countries to pick servers from: names, codes, IDs, or specific server hostnames (list⁠).
`CITY`	—	Cities: names, IDs, or specific server hostnames (list⁠).
`GROUP`	—	Server group, e.g. `legacy_p2p` or `legacy_obfuscated_servers` (list⁠, details⁠).
`RANDOM_TOP`	`0`	Shuffle the top N servers of the filtered pool before picking one.

⁠OpenVPN connection — details⁠

Variable	Default	Description
`TECHNOLOGY`	`openvpn_udp`	OpenVPN variant: `openvpn_udp` \| `openvpn_tcp` \| `openvpn_xor_udp` \| `openvpn_xor_tcp` \| `openvpn_dedicated_udp` \| `openvpn_dedicated_tcp`; API names and IDs also accepted (list⁠).
`PORT`	(auto)	Force a specific port for the VPN connection; must be one the server listens on.
`DNS`	server-pushed	DNS servers written to `resolv.conf`; resolution goes through the tunnel. `off` leaves `resolv.conf` untouched (details⁠).
`XOR_KEY`	NordVPN's built-in key	XOR scramble key for the `openvpn_xor_*` technologies (details⁠).
`OPENVPN_OPTS`	—	Extra OpenVPN options, e.g. `--mute-replay-warnings --ping-exit 180` (details⁠).

⁠Reconnection and health — details⁠

Variable	Default	Description
`RECREATE_VPN_CRON`	(disabled)	Cron schedule for switching to a new server, e.g. `0 /6 * *`.
`CHECK_CONNECTION_CRON`	(disabled)	Cron schedule for the connectivity check that reconnects on failure.
`CHECK_CONNECTION_URL`	`https://www.google.com`	URL(s) probed through the tunnel by the check and by the Docker `HEALTHCHECK`.
`CHECK_CONNECTION_ATTEMPTS`	`5`	Failed attempts before the check declares the tunnel dead and reconnects.
`CHECK_CONNECTION_ATTEMPT_INTERVAL`	`10`	Seconds between attempts.
`HEALTHCHECK_ENABLED`	`false`	`true` = the Docker `HEALTHCHECK` probes `tun0` and `CHECK_CONNECTION_URL` instead of always reporting healthy (details⁠).

⁠Local network access — details⁠

Variable	Default	Description
`NETWORK`	—	LAN / inter-container IPv4 CIDRs allowed to bypass the tunnel (routes + firewall), e.g. `192.168.1.0/24`.

⁠Gateway mode — details⁠

Variable	Default	Description
`FORWARD_FROM`	—	Downstream IPv4 CIDRs allowed to route out through the tunnel; traffic must arrive already SNATed into these nets.
`GATEWAY_DNS`	`off`	Client DNS interception for `FORWARD_FROM` sources: `redirect` (tunnel resolvers) \| `local` (co-located resolver) \| `forward` (`GATEWAY_DNS_SERVER`) \| `off` (details⁠).
`GATEWAY_DNS_SERVER`	—	External IPv4 resolver(s) for `GATEWAY_DNS=forward`, reached directly over the uplink, not through the tunnel; the first one answering a probe at startup is used.
`TTL_SET`	(unset)	Rewrite the TTL of traffic leaving through the tunnel (`1`–`255`, e.g. `64`); hides every hop behind this container from client traceroutes (details⁠).
`TTL_INC`	(unset)	Add to the TTL of traffic arriving on `eth0` (`1`–`255`, e.g. `1`) so this container disappears from client traceroutes; needs `FORWARD_FROM` (details⁠).

⁠Diagnostics and advanced — details⁠

Variable	Default	Description
`NETWORK_DIAGNOSTIC_ENABLED`	`false`	Run the built-in network diagnostic after every connect.
`NORDVPNAPI_IP`	`104.16.208.203;104.19.159.190`	IPs used for all NordVPN API access (no DNS involved).

⁠📋 Runtime Requirements

--cap-add=NET_ADMIN and --device /dev/net/tun
NordVPN service credentials or an access token, not regular account credentials — see Getting Service Credentials⁠
a kernel with iptables support; the nft or legacy backend is picked automatically (details⁠)
for gateway mode: net.ipv4.ip_forward=1 on this container and on the downstream one (details⁠)

⁠🐛 Issues

If you have any problems with or questions about this image, please open a GitHub issue⁠.

Check the Troubleshooting⁠ and FAQ⁠ wiki pages first. For how the container works under the hood, see Architecture and Internals⁠.

⁠📄 License

AGPL-3.0⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:2ffb9a40b…

Size

15 MB

Last updated

9 days ago

docker pull azinchen/nordvpn