gluetun/README.md

Gluetun VPN client

Lightweight swiss-knife-like VPN client to tunnel to Private Internet Access, Mullvad, Windscribe and Surfshark VPN servers, using Go, OpenVPN, iptables, DNS over TLS, ShadowSocks and Tinyproxy

ANNOUNCEMENT: New wiki available here

Click to show base components

• Alpine 3.11 for a tiny image (37MB of packages, 6.7MB of Go binary and 5.6MB for Alpine)
• OpenVPN 2.4.8 to tunnel to your VPN provider servers
• IPtables 1.8.3 enforces the container to communicate only through the VPN or with other containers in its virtual network (acts as a killswitch)
• Unbound 1.9.6 configured with Cloudflare's 1.1.1.1 DNS over TLS (configurable with 5 different providers)
• Files and blocking lists built periodically used with Unbound (see BLOCK_MALICIOUS, BLOCK_SURVEILLANCE and BLOCK_ADS environment variables)
• TinyProxy 1.10.0
• Shadowsocks 3.3.4

Features

• Based on Alpine 3.11 for a small Docker image below 50MB
• Supports Private Internet Access, Mullvad, Windscribe and Surfshark servers
• DNS over TLS baked in with service provider(s) of your choice
• DNS fine blocking of malicious/ads/surveillance hostnames and IP addresses, with live update every 24 hours
• Choose the vpn network protocol, udp or tcp
• Built in firewall kill switch to allow traffic only with needed the VPN servers and LAN devices
• Built in SOCKS5 proxy (Shadowsocks, tunnels TCP+UDP)
• Built in HTTP proxy (Tinyproxy, tunnels TCP)
• Connect other containers to it
• Connect LAN devices to it
• Compatible with amd64, i686 (32 bit), ARM 64 bit, ARM 32 bit v6 and v7 🎆

Private Internet Access

• Pick the region
• Pick the level of encryption
• Enable port forwarding

Mullvad

• Pick the country, city and ISP
• Pick the port to use (i.e. 53 (udp) or 80 (tcp))

Windscribe

• Pick the region
• Pick the port to use

Surfshark

• Pick the region or a multi hop region name

Extra niche features

• Possibility of split horizon DNS by selecting multiple DNS over TLS providers
• Subprograms all drop root privileges once launched
• Subprograms output streams are all merged together
• Can work as a Kubernetes sidecar container, thanks @rorph

Setup

1. Requirements

   • A VPN account with one of the service providers:

     • Private Internet Access: username and password (sign up)

     • Mullvad: user ID (sign up)

     • Windscribe: username and password | Signup up using my affiliate link below

       

     • Surfshark: username and password (sign up)

   • If you have a host or router firewall, please refer to the firewall documentation

2. On some devices such as Synology or Qnap machines, it's required to setup your tunnel device /dev/net/tun on your host:

   insmod /lib/modules/tun.ko
   # or
   modprobe tun
   

   You can verify it's here with ls /dev/net

3. Launch the container with:

   docker run -d --name gluetun --cap-add=NET_ADMIN \
   -e REGION="CA Montreal" -e USER=js89ds7 -e PASSWORD=8fd9s239G \
   qmcgaw/private-internet-access
   

   or use docker-compose.yml with:

   docker-compose up -d
   

   Note that you can:

   • Change the many environment variables available
   • Use -p 8888:8888/tcp to access the HTTP web proxy (and put your LAN in EXTRA_SUBNETS environment variable, in example 192.168.1.0/24)
   • Use -p 8388:8388/tcp -p 8388:8388/udp to access the SOCKS5 proxy (and put your LAN in EXTRA_SUBNETS environment variable, in example 192.168.1.0/24)
   • Use -p 8000:8000/tcp to access the HTTP control server built-in
   • Pass additional arguments to openvpn using Docker's command function (commands after the image name)

   If you encounter an issue with the tun device not being available, see the FAQ

4. You can update the image with docker pull qmcgaw/private-internet-access:latest. See the wiki for more information on other tags available.

Testing

Check the VPN IP address matches your expectations

docker run --rm --network=container:gluetun alpine:3.11 wget -qO- https://ipinfo.io

Want more testing? ▶ see the Wiki

Environment variables

TLDR; only set the 🏁 marked environment variables to get started.

VPN

Variable	Default	Choices	Description
🏁 VPNSP	private internet access	private internet access, mullvad, windscribe, surfshark	VPN Service Provider
IP_STATUS_FILE	/ip	Any filepath	Filepath to store the public IP address assigned
PROTOCOL	udp	udp or tcp	Network protocol to use
OPENVPN_VERBOSITY	1	0 to 6	Openvpn verbosity level
OPENVPN_ROOT	no	yes or no	Run OpenVPN as root
OPENVPN_TARGET_IP		Valid IP address	Specify a target VPN server IP address to use
OPENVPN_CIPHER		i.e. aes-256-gcm	Specify a custom cipher to use. It will also set ncp-disable if using AES GCM for PIA
OPENVPN_AUTH		i.e. sha256	Specify a custom auth algorithm to use

• Private Internet Access

  Variable	Default	Choices	Description
  🏁 USER			Your username
  🏁 PASSWORD			Your password
  REGION	Austria	One of the PIA regions	VPN server region
  PIA_ENCRYPTION	strong	normal, strong	Encryption preset
  PORT_FORWARDING	off	on, off	Enable port forwarding on the VPN server
  PORT_FORWARDING_STATUS_FILE	/forwarded_port	Any filepath	Filepath to store the forwarded port number

• Mullvad

  Variable	Default	Choices	Description
  🏁 USER			Your user ID
  COUNTRY	Sweden	One of the Mullvad countries	VPN server country
  CITY		One of the Mullvad cities	VPN server city
  ISP		One of the Mullvad ISP	VPN server ISP
  PORT		80 or 443 for TCP; or 53 for UDP. Leave blank for default Mullvad server port	Custom VPN port to use

• Windscribe

  Variable	Default	Choices	Description
  🏁 USER			Your username
  🏁 PASSWORD			Your password
  REGION	Austria	One of the Windscribe regions	VPN server region
  PORT		One from the this list of ports	Custom VPN port to use

• Surfshark

  Variable	Default	Choices	Description
  🏁 USER			Your username
  🏁 PASSWORD			Your password
  REGION	Austria	One of the Surfshark regions (subdomains)	VPN server region

DNS over TLS

None of the following values are required.

Variable	Default	Choices	Description
DOT	on	on, off	Activate DNS over TLS with Unbound
DOT_PROVIDERS	cloudflare	cloudflare, google, quad9, quadrant, cleanbrowsing, securedns, libredns	Comma delimited list of DNS over TLS providers
DOT_CACHING	on	on, off	Unbound caching
DOT_IPV6	off	on, off	DNS IPv6 resolution
DOT_PRIVATE_ADDRESS	All private CIDRs ranges		Comma separated list of CIDRs or single IP addresses Unbound won't resolve to. Note that the default setting prevents DNS rebinding
DOT_VERBOSITY	1	0 to 5	Unbound verbosity level
DOT_VERBOSITY_DETAILS	0	0 to 4	Unbound details verbosity level
DOT_VALIDATION_LOGLEVEL	0	0 to 2	Unbound validation log level
DNS_UPDATE_PERIOD	24h	i.e. 0, 30s, 5m, 24h	Period to update block lists and cryptographic files and restart Unbound. Set to 0 to deactivate updates
BLOCK_MALICIOUS	on	on, off	Block malicious hostnames and IPs with Unbound
BLOCK_SURVEILLANCE	off	on, off	Block surveillance hostnames and IPs with Unbound
BLOCK_ADS	off	on, off	Block ads hostnames and IPs with Unbound
UNBLOCK		i.e. domain1.com,x.domain2.co.uk	Comma separated list of domain names to leave unblocked with Unbound

Firewall

That one is important if you want to connect to the container from your LAN for example, using Shadowsocks or Tinyproxy.

Variable	Default	Choices	Description
EXTRA_SUBNETS		i.e. 192.168.1.0/24,192.168.10.121,10.0.0.5/28	Comma separated subnets allowed in the container firewall

Shadowsocks

Variable	Default	Choices	Description
SHADOWSOCKS	on	on, off	Enable the internal SOCKS5 proxy Shadowsocks
SHADOWSOCKS_LOG	off	on, off	Enable logging
SHADOWSOCKS_PORT	8388	1024 to 65535	Internal port number for Shadowsocks to listen on
SHADOWSOCKS_PASSWORD	8388	1024 to 65535	Password to use to connect to Shadowsocks
SHADOWSOCKS_METHOD	chacha20-ietf-poly1305	One of these ciphers	Method to use for Shadowsocks

Tinyproxy

Variable	Default	Choices	Description
TINYPROXY	on	on, off	Enable the internal HTTP proxy tinyproxy
TINYPROXY_LOG	Info	Info, Connect, Notice, Warning, Error, Critical	Tinyproxy log level
TINYPROXY_PORT	8888	1024 to 65535	Internal port number for Tinyproxy to listen on
TINYPROXY_USER	8388	1024 to 65535	Username to use to connect to Tinyproxy
TINYPROXY_PASSWORD	8388	1024 to 65535	Password to use to connect to Tinyproxy

System

Variable	Default	Choices	Description
TZ		i.e. Europe/London	Specify a timezone to use to have correct log times
UID	1000		User ID to run as non root and for ownership of files written
GID	1000		Group ID to run as non root and for ownership of files written

Connect to it

There are various ways to achieve this, depending on your use case.

• Connect containers in the same docker-compose.yml as Gluetun

  Add network_mode: "service:gluetun" to your docker-compose.yml (no need for depends_on)

• Connect other containers to Gluetun

  Add --network=container:gluetun when launching the container, provided Gluetun is already running

• Connect containers from another docker-compose.yml

  Add network_mode: "container:gluetun" to your docker-compose.yml, provided Gluetun is already running

• Connect LAN devices through the built-in HTTP proxy *Tinyproxy* (i.e. with Chrome, Kodi, etc.)

  You might want to use Shadowsocks instead which tunnels UDP as well as TCP, whereas Tinyproxy only tunnels TCP.

  1. Setup a HTTP proxy client, such as SwitchyOmega for Chrome
  2. Ensure the Gluetun container is launched with:
     • port 8888 published -p 8888:8888/tcp
     • your LAN subnet, i.e. 192.168.1.0/24, set as -e EXTRA_SUBNETS=192.168.1.0/24
  3. With your HTTP proxy client, connect to the Docker host (i.e. 192.168.1.10) on port 8888. You need to enter your credentials if you set them with TINYPROXY_USER and TINYPROXY_PASSWORD.
  4. If you set TINYPROXY_LOG to Info, more information will be logged in the Docker logs

• Connect LAN devices through the built-in SOCKS5 proxy *Shadowsocks* (per app, system wide, etc.)

  1. Setup a SOCKS5 proxy client, there is a list of ShadowSocks clients for all platforms
     • note some clients do not tunnel UDP so your DNS queries will be done locally and not through Gluetun and its built in DNS over TLS
     • Clients that support such UDP tunneling are, as far as I know:
       • iOS: Potatso Lite
       • OSX: ShadowsocksX
       • Android: Shadowsocks by Max Lv
  2. Ensure the Gluetun container is launched with:
     • port 8388 published -p 8388:8388/tcp -p 8388:8388/udp
     • your LAN subnet, i.e. 192.168.1.0/24, set as -e EXTRA_SUBNETS=192.168.1.0/24
  3. With your SOCKS5 proxy client
     • Enter the Docker host (i.e. 192.168.1.10) as the server IP
     • Enter port TCP (and UDP, if available) 8388 as the server port
     • Use the password you have set with SHADOWSOCKS_PASSWORD
     • Choose the encryption method/algorithm to the method you specified in SHADOWSOCKS_METHOD
  4. If you set SHADOWSOCKS_LOG to on, (a lot) more information will be logged in the Docker logs

• Access ports of containers connected to Gluetun

  In example, to access port 8000 of container xyz and 9000 of container abc connected to Gluetun, publish ports 8000 and 9000 for the Gluetun container and access them as you would with any other container

• Access ports of containers connected to Gluetun, all in the same docker-compose.yml

  In example, to access port 8000 of container xyz and 9000 of container abc connected to Gluetun, publish port 8000 and 9000 for the Gluetun container. The docker-compose.yml file would look like:

  version: '3.7'
  services:
    gluetun:
      image: qmcgaw/private-internet-access
      container_name: gluetun
      cap_add:
        - NET_ADMIN
      environment:
        - USER=js89ds7
        - PASSWORD=8fd9s239G
      ports:
        - 8000:8000/tcp
        - 9000:9000/tcp
    abc:
      image: abc
      container_name: abc
      network_mode: "service:gluetun"
    xyz:
      image: xyz
      container_name: xyz
      network_mode: "service:gluetun"
  

Private Internet Access port forwarding

Note that not all regions support port forwarding.

When PORT_FORWARDING=on, a port will be forwarded on the VPN server side and written to the file specified by PORT_FORWARDING_STATUS_FILE=/forwarded_port.

It can be useful to mount this file as a volume to read it from other containers, for example to configure a torrenting client.

HTTP control server

A built-in HTTP server listens on port 8000 to modify the state of the container. You have the following routes available:

• http://<your-docker-host-ip>:8000/openvpn/actions/restart restarts the openvpn process
• http://<your-docker-host-ip>:8000/unbound/actions/restart re-downloads the DNS files (crypto and block lists) and restarts the unbound process

Development and contributing

• Contribute with code: see the Wiki.
• The list of existing contributors 👍
• Github workflows to know what's building
• List of issues and feature requests

License

This repository is under an MIT license

Support

Sponsor me on Github, donate to paypal.me/qmcgaw or subscribe to a VPN provider through one of my affiliate links:

Feel also free to have a look at the Kanban board and contribute to the code or the issues discussion.

Many thanks to @Frepke and @Ralph521 for supporting me financially 🥇👍