DOCSEARCHbyAlgolia
Submit Docs

Gluetun VPN Client

repository·master·Indexed 10 days ago

https://github.com/passteque/gluetun

A lightweight, multi-provider VPN client designed to run as a Docker container. It supports OpenVPN and Wireguard, providing a centralized way to route container traffic with a built-in kill switch and proxy servers (Shadowsocks, Socks5, and HTTP). Includes a development helper called `devrun` for managing encrypted credentials and automating container launches with NET_ADMIN capabilities.

Tokens
8.5K
Snippets
28
Records
43
Agent score
96%

What's inside Gluetun

  1. Overview of Gluetun features

    master

    Gluetun is a lightweight VPN client designed to run in Docker. Key capabilities include:

    • Multi-provider support: Supports a wide range of providers including AirVPN, Mullvad, NordVPN, ProtonVPN, Surfshark, and more.
    • Protocol support: Supports OpenVPN and Wireguard (both kernelspace and userspace).
    • Built-in Proxies: Includes Shadowsocks, Socks5, and HTTP proxy servers.
    • Security: Features a built-in firewall kill switch and DNS over TLS support with malicious/ad hostname blocking.
    • Architecture: Small footprint (based on Alpine 3.23) and compatible with multiple architectures (amd64, ARM 64/32, ppc64le).

  2. Overview of devrun

    master

    devrun is a development helper designed to simplify starting local qmcgaw/gluetun Docker containers. It manages VPN provider credentials in an encrypted file named credentials, preventing sensitive information from appearing in shell history or plaintext files.

    It automates the process of decrypting credentials, mapping them to the correct Gluetun environment variables, and launching the container with necessary capabilities like NET_ADMIN.

  3. Credential mapping for OpenVPN and WireGuard

    master

    The devrun tool maps stored credentials to specific Gluetun environment variables at runtime.

    OpenVPN Mapping

    • username (required) $\rightarrow$ OPENVPN_USER
    • password (required) $\rightarrow$ OPENVPN_PASSWORD

    WireGuard Mapping

    • private_key (required) $\rightarrow$ WIREGUARD_PRIVATE_KEY
    • address (optional) $\rightarrow$ WIREGUARD_ADDRESSES
    • preshared_key (optional) $\rightarrow$ WIREGUARD_PRESHARED_KEY

  4. Quickstart with docker-compose.yml

    master

    You can deploy Gluetun using a docker-compose.yml file. Note that you must uncomment container_name: gluetun if you intend to connect other containers to the Gluetun network. The setup requires NET_ADMIN capabilities and access to the /dev/net/tun device.

    To configure your specific VPN, you must set VPN_SERVICE_PROVIDER and either VPN_TYPE=openvpn (with OPENVPN_USER and OPENVPN_PASSWORD) or use Wireguard credentials.

    services:
  gluetun:
    image: qmcgaw/gluetun
    # container_name: gluetun
    # line above must be uncommented to allow external containers to connect.
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8888:8888/tcp # HTTP proxy
      - 8388:8388/tcp # Shadowsocks
      - 8388:8388/udp # Shadowsocks
    volumes:
      - /yourpath:/gluetun
    environment:
      - VPN_SERVICE_PROVIDER=ivpn
      - VPN_TYPE=openvpn
      - OPENVPN_USER=
      - OPENVPN_PASSWORD=
      - TZ=
      - UPDATER_PERIOD=

  5. Delete credentials from the encrypted store

    master

    Use the delete-cred command to remove a specific provider and VPN type entry from the credentials file. You will be prompted for the credentials password to decrypt the store before removal.

    Usage:

    go run ./cmd/main.go delete-cred <provider> <vpn-type>

    Example:

    go run ./cmd/main.go delete-cred protonvpn openvpn
    go run ./cmd/main.go delete-cred protonvpn openvpn

  6. Install and prepare devrun

    master

    To use devrun, ensure you have the following prerequisites installed:

    • Go: To run the tool via go run.
    • Docker: A local installation with a running daemon.
    • Interactive Terminal: Required because the tool prompts for passwords without echoing them.

    The tool respects standard Docker environment variables, such as DOCKER_HOST.

  7. Add credentials to the encrypted store

    master

    Use the add-cred command to store or replace credentials for a specific provider and VPN type.

    • If the credentials file does not exist, you will be prompted to create a new password for the encrypted store.
    • If it exists, you will be prompted for the existing password to decrypt, update, and re-encrypt the store.
    • Sensitive fields are read from stdin without echoing.

    Usage:

    go run ./cmd/main.go add-cred <provider> <vpn-type>

    Example:

    go run ./cmd/main.go add-cred protonvpn openvpn
go run ./cmd/main.go add-cred mullvad wireguard
    go run ./cmd/main.go add-cred protonvpn openvpn
go run ./cmd/main.go add-cred mullvad wireguard

  8. Run a Gluetun container with devrun

    master

    The run command decrypts credentials in memory, builds the required Gluetun environment variables, and starts a qmcgaw/gluetun container.

    Automatic Environment Variables:

    • VPN_SERVICE_PROVIDER=<provider>
    • VPN_TYPE=<vpn-type>
    • LOG_LEVEL=debug
    • The container is granted NET_ADMIN capabilities by default.

    Usage:

    go run ./cmd/main.go run <provider> <vpn-type> [extra-docker-flags]

    Examples:

    go run ./cmd/main.go run mullvad wireguard
go run ./cmd/main.go run protonvpn wireguard -e PORT_FORWARDING=on -p 8000:8000/tcp
    go run ./cmd/main.go run mullvad wireguard
go run ./cmd/main.go run protonvpn wireguard -e PORT_FORWARDING=on -p 8000:8000/tcp

  9. Dump credentials for inspection

    master

    Use the dump-cred command to print the decrypted values of a specific provider and VPN type to the terminal. You will be prompted for the credentials password first.

    Usage:

    go run ./cmd/main.go dump-cred <provider> <vpn-type>

    Example:

    go run ./cmd/main.go dump-cred protonvpn openvpn
    go run ./cmd/main.go dump-cred protonvpn openvpn

  10. Connect other containers to Gluetun

    master

    Gluetun can act as a network gateway for other Docker containers. To allow an external container to use Gluetun's VPN connection, you must:

    1. Uncomment container_name: gluetun in your Gluetun service definition.
    2. Set the target container's network mode to use the Gluetun container (e.g., network_mode: "container:gluetun" in Docker Compose).

  11. Migrate to Gluetun V4 configuration

    master

    When upgrading to Gluetun V4, several environment variables and functionalities have been removed or changed. Ensure your configuration is updated to avoid errors.

    Removed Environment Variables

    Do not use the following 'retro' variables in V4:

    • PORT
    • UNBLOCK
    • PROTOCOL
    • PIA_ENCRYPTION
    • PORT_FORWARDING
    • PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING
    • WIREGUARD_PORT
    • REGION (for PIA or Cyberghost)
    • WIREGUARD_ADDRESS
    • VPNSP
    • Any old location filters (e.g., REGION, COUNTRY, etc.)

    Removed Functionalities

    The following settings are no longer supported:

    • SERVER_NUMBER
    • SERVER_NAME
    • PUBLICIP_FILE
    • PORT_FORWARDING_STATUS_FILE
    • PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING_STATUS_FILE

    Required Changes

    • Compulsory Variable: You must now provide VPN_SERVICE_PROVIDER.
    • Pathing: Use relative paths instead of absolute paths for configuration files.
    • Custom OpenVPN Logic: The implicit logic where OPENVPN_CONFIG != "" sets VPNSP to custom has been removed. Use the explicit V4 configuration methods.

  12. Configure Gluetun via environment variables and files

    master

    Gluetun uses a multi-source configuration reader. It resolves settings by looking at sources in a specific order (typically secrets, then files, then environment variables).

    When configuring Gluetun, you can provide settings through:

    1. Secrets: Managed via the secrets source.
    2. Files: Configuration files loaded via the files source.
    3. Environment Variables: Standard environment variables loaded via the env source.

    If you use deprecated configuration keys, Gluetun will emit a warning in the logs suggesting the current replacement key.