DOCSEARCHbyAlgolia
Submit Docs

Gluetun Wiki

repository·main·Indexed 20 days ago

https://github.com/qdm12/gluetun-wiki

Comprehensive documentation for Gluetun, featuring setup instructions, configuration options, and provider details. Includes detailed troubleshooting guides for TUN device errors, firewall issues, OpenVPN connectivity, and routing problems, as well as environment-specific prerequisites for 32-bit systems, Synology, and Proxmox LXC.

Tokens
45.6K
Snippets
134
Records
200
Agent score
77%

What's inside gluetun-wiki

  1. Overview of Gluetun Wiki

    main

    The Gluetun Wiki is a documentation repository designed to provide setup guides, provider information, and troubleshooting for Gluetun. It is organized into several key sections:

    • Setup: The starting point for new users, covering Providers, Options, Advanced setup, and Popular apps.
    • Common errors: A guide for troubleshooting known issues.
    • FAQ: Frequently asked questions.
    • Contributing: Information on how to contribute to the wiki.

    To support the Gluetun community and combat AI-generated scam websites, users can set the environment variable BORINGPOLL_GLUETUNCOM=on on the latest image.

  2. Understand what files are downloaded after tunneling

    main

    Once the VPN tunnel is established, Gluetun downloads blocklists at startup. If DNS_UPDATE_PERIOD is set to a non-zero value, these lists are also downloaded periodically. The specific files downloaded depend on your configuration:

    • If BLOCK_MALICIOUS=on: Downloads malicious hostnames and IP addresses block lists.
    • If BLOCK_SURVEILLANCE=on: Downloads surveillance hostnames and IP addresses block lists.
    • If BLOCK_ADS=on: Downloads ads hostnames and IP addresses block lists.

  3. Match Wiki documentation to Gluetun release tags

    main

    The Gluetun Wiki is versioned to mirror the release tags of Gluetun. When using a specific version of Gluetun, you should refer to the corresponding tag in the Wiki to ensure the documentation matches your software version.

    Note that the Wiki bugfix version number (the last digit) refers specifically to Wiki fixes and may not match the Gluetun software version exactly.

    | Gluetun release tag | Corresponding wiki |
| --- | --- |
| `:latest` | [`main` branch](https://github.com/qdm12/gluetun-wiki) |
| `:v3.40.2` | [`v3.40.2` tag](https://github.com/qdm12/gluetun-wiki/tree/v3.40.2) |
| `:v3.40.1` | [`v3.40.1` tag](https://github.com/qdm12/gluetun-wiki/tree/v3.40.1) |
| `:v3.40.0` | [`v3.40.0` tag](https://github.com/qdm12/gluetun-wiki/tree/v3.40.0) |
| `:v3.39.0` | [`v3.39.0` tag](https://github.com/qdm12/gluetun-wiki/tree/v3.39.0) |
| `:v3.38.0` | [`v3.38.0` tag](https://github.com/qdm12/gluetun-wiki/tree/v3.38.0) |
| `:v3.35.0` | [`v3.35.0` tag](https://github.com/qdm12/gluetun-wiki/tree/v3.35.0) |

  4. Identify Gluetun healthcheck failure types via logs

    main

    Gluetun uses three distinct types of checks to monitor connection health. Identifying which one failed helps diagnose the issue:

    1. Startup check failure: Occurs during initial connection. A TCP+TLS dial to the health target fails within 6 seconds. This is usually fatal and indicates the connection cannot be established.

      • Log pattern: WARN [vpn] restarting VPN because it failed to pass the healthcheck: startup check: ...

    2. Small periodic check failure: Occurs every minute. It uses 3 tries (10s, 20s, 30s timeouts) via ICMP echo (ping) if allowed, or a plaintext UDP DNS query. If all 3 fail, the VPN restarts.

      • Log pattern: WARN [vpn] restarting VPN because it failed to pass the healthcheck: periodic check: ...

    3. Full periodic check failure: Occurs every 5 minutes. It uses 2 retries (20s and 30s timeouts) via a TCP+TLS dial to the target. If both fail, the VPN restarts.

      • Log pattern: WARN [vpn] restarting VPN because it failed to pass the healthcheck: periodic full check: ...

  5. Understand the Gluetun Go implementation and supervisor role

    main

    Gluetun is implemented in Go and functions as a supervisor program with a built-in HTTP control server. This architecture replaces the previous shell-based entrypoint to provide:

    • Faster start times and asynchronous/parallel operations.
    • The ability to restart components like openvpn or dns without quitting the container.
    • Improved testing, maintainability, and feature implementation.

    The core logic resides in the internal directory and the cmd/main.go entry point.

  6. Firewall initialization timing and lifecycle

    main

    The firewall is initialized at container startup and takes approximately 15 milliseconds to set up. This timing is a fixed characteristic of the rule-setting process.

    Key lifecycle details:

    • Startup: The firewall is enabled before built-in proxies are started.
    • Persistence: The firewall is never de-activated during the container's lifecycle.

  7. Avoid port conflicts when running multiple containers through Gluetun

    main

    Because all containers connected to Gluetun share the same network namespace, they cannot all listen on the same internal port. If you attempt to run multiple instances of the same container image (e.g., two Deluge instances) through Gluetun, you must configure each instance to listen on a different internal port to avoid conflicts.

    Note: Some container images (like certain Transmission images) may not support changing their internal listening port via configuration. In such cases, the port mapping will fail due to the conflict.

  8. Understand Gluetun's default firewall behavior

    main

    The Gluetun firewall is designed to be strict and acts as a kill switch. If the VPN connection fails, the firewall blocks all traffic to prevent leaks. By default, it follows these rules:

    • Incoming traffic: All incoming traffic is dropped, except for traffic originating from your Docker network on the default (non-VPN) route.
    • Outgoing traffic: All outgoing traffic is dropped, except for traffic directed to the specific combination of the VPN network interface, the VPN server IP address, the VPN server port, and the VPN server protocol.
    • Forwarding traffic: All forwarding traffic is dropped.

  10. Understand Gluetun VPN auto-healing and healthchecks

    main

    Gluetun includes an auto-healing mechanism that monitors the VPN connection and automatically restarts the VPN internally if a failure is detected.

    Important Distinction: The internal Gluetun healthcheck is separate from the Docker healthcheck, although a connection failure will be reported to both.

    Common Misconception: Errors like connection refused, operation not permitted, i/o timeout, or context deadline exceeded are typically consequences of the VPN being down, not the cause of the failure.

  11. OpenVPN configuration behavior and overrides

    main

    When using a custom OpenVPN configuration, Gluetun applies several implicit behaviors and overrides:

    Automatic Options Added/Overridden

    Gluetun automatically injects or overrides these options:

    mute-replay-warnings
suppress-timestamps
auth-nocache
auth-retry nointeract
auth-user-pass /etc/openvpn/auth.conf
pull-filter ignore "auth-token"

    Environment Variable Overrides

    Certain environment variables will override specific OpenVPN options:

    • OPENVPN_VERBOSITY: Overrides verb (defaults to 1).
    • VPN_INTERFACE: Overrides dev (defaults to tun0).
    • OPENVPN_PROCESS_USER: If not root, adds/overrides the user option.
    • OPENVPN_CIPHERS: Overrides data-ciphers and data-ciphers-fallback.
    • OPENVPN_AUTH: Overrides auth.
    • OPENVPN_MSSFIX: Overrides mssfix.
    • OPENVPN_ENDPOINT_PORT: Overrides the port in the remote instruction.

    Important Limitations

    • Relative Paths: Relative file paths in your config will fail because the file is rewritten to /etc/openvpn/target.ovpn. Always use absolute paths.
    • Multiple Remotes: If your config has multiple remote lines, only the first one is used.
    • Ignored Variables: The following variables have no effect: OPENVPN_PROTOCOL, OPENVPN_CLIENTKEY_SECRETFILE, OPENVPN_CLIENTCRT_SECRETFILE, OPENVPN_ENCRYPTED_KEY_SECRETFILE, OPENVPN_KEY_PASSHPRASE_SECRETFILE, and OPENVPN_ENDPOINT_IP.

  12. Use a third-party tool to manage the servers list

    main

    If you use an external tool to maintain your server lists, you can force Gluetun to prioritize your local files:

    1. Force local file usage: In your /gluetun/servers/yourprovider.json file, set the top-level field "preferred": true. This tells Gluetun to use this file regardless of built-in data (unless there is a version mismatch).
    2. Custom file paths: You can modify the file path to your JSON files within /gluetun/servers/manifest.json.