SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

Gluetun network: how container fit reach host

Container wey dey behind Gluetun no get im own interface. Publish ports on Gluetun, then allow only the subnets e need reach outside the VPN tunnel.

Wetin happen when container join gluetun network

Container wey set network_mode: service:gluetun no get network interfaces of im own. E join gluetun network namespace, so port publishing and firewall rules no longer belong to that container; dem become properties of the gluetun service. Every answer below come from this one fact.

Network namespace na kernel private copy of network stack. E get im own interfaces, routing table, firewall rules, and listening sockets. Docker dey give each container one by default. When you write network_mode: service:gluetun, Docker skip that step and put the new container inside the namespace wey gluetun already dey use. The container still get im own filesystem, but e no get im own /etc/hosts or /etc/resolv.conf. Docker give am the same files wey gluetun dey use, and this matter later.

You fit see am directly.

docker inspect -f '{{.HostConfig.NetworkMode}}' qbittorrent

That command print container: followed by the gluetun container ID, while normal container for print bridge. This guide continue from where routing Docker traffic through VPN with gluetun stop: the tunnel dey work, but now nothing fit talk to the container.

Publish port for gluetun, no be for application

Leave one ports: block for the service wey set network_mode, and Docker go refuse to create the container:

Error response from daemon: conflicting options: port publishing and the container type network mode

The reason clear. To publish port mean say you add one NAT (network address translation) rule wey go forward host port enter the container own network namespace. But this container no get its own network namespace. Move the mapping go gluetun service. The port number no change, because the application still dey listen on that port inside the shared namespace.

services:
  gluetun:
    ports:
      - "8080:8080/tcp"   # qBittorrent web UI

  qbittorrent:
    network_mode: "service:gluetun"
    # no ports: block here

If you put expose: block for the dependent service, e go fail the same way with conflicting options: port exposing and the container type network mode. networks: block for there na hard stop too. Compose go report say the service declare mutually exclusive network_mode and networks, and e no go load the file at all.

One problem fit show later. Every container for the namespace share one port space. So, two applications wey both use 8080 by default go collide. The second one wey start go fail with address already in use error. Change one of dem for the application own configuration. For example, change the WEBUI_PORT variable for the LinuxServer qBittorrent image. Then publish the new number on gluetun.

Container wey dey behind gluetun dey reach each other how?

Inside the namespace, dem already share one loopback interface. Container wey dey behind gluetun fit reach im sibling for 127.0.0.1:<port> without Docker network.

From outside the namespace, the container no get name. Docker embedded DNS dey resolve service name to the service address for user defined network, but this container no get address for any network. So normal container like Sonarr no go reach torrent client for http://qbittorrent:8080. E go reach am for http://gluetun:8080, because socket dey listen inside gluetun namespace, for gluetun address. This one fit surprise people wey sabi how Docker Compose networks and service names dey work and expect the normal naming to apply. E still work without publishing anything to the host, because both containers dey for the same Compose network.

Check DNS before you debug anything else. Gluetun dey run im own DNS server inside the namespace, and Docker dey give every container wey dey behind gluetun the same /etc/resolv.conf file wey gluetun get. So lookups from your application dey pass through gluetun resolver instead of the host resolver. By default, that resolver still dey reject answers wey point to private addresses. Na why name wey dey resolve for the host fit fail inside the container. Gluetun documentation talk say you must list such hostnames for DNS_REBINDING_PROTECTION_EXEMPT_HOSTNAMES.

docker exec qbittorrent cat /etc/resolv.conf

How I fit reach service wey dey run for Docker host?

Use host.docker.internal. E need two settings, and both dey for gluetun service, because two different things spoil.

The name dey come first. Container wey dey behind gluetun dey read gluetun's /etc/hosts, and Docker go reject extra_hosts entry for service wey set network_mode with conflicting options: custom host-to-IP mapping and the network mode. So na gluetun the entry suppose dey, and every container for the namespace go see am.

  gluetun:
    extra_hosts:
      - "host.docker.internal:host-gateway"

host-gateway na special value wey Docker dey replace with internal address of the host itself. For plain Linux Docker installation, na address of docker0 bridge, commonly 172.17.0.1. Confirm your own with ip -4 addr show docker0 for the VPS. Docker Desktop dey resolve this name by itself. Na why guides wey dem write for laptop dey skip extra_hosts line, and the same file go then fail for server.

The route dey come second. Adding the name only tell container which address to use. The packet still go out through gluetun default route, wey be the tunnel, and gluetun firewall go drop am. The sign na connection wey hang, then timeout, instead of connection wey dem refuse. Refusal mean say packet arrive and something answer no. Timeout mean say packet never arrive.

  gluetun:
    environment:
      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32

Then check say host service dey actually listen on that address. PostgreSQL server wey bind only to 127.0.0.1 no fit reachable from any container wey get its own network namespace. This include every container wey dey behind gluetun, whether tunnel dey or not, because 127.0.0.1 inside the namespace na loopback for that namespace itself. Na only container wey dey use host networking share host loopback, and container wey dey behind gluetun don already use its network_mode for gluetun. Bind PostgreSQL to 172.17.0.1 instead: e go accept connections from containers, but e no go dey on public interface. Verify am with ss -lntp | grep 5432 for the host.

Wetin FIREWALL_OUTBOUND_SUBNETS really dey change

gluetun documentation describe am as the subnets wey gluetun and containers wey dey share im network stack get permission to access. E also talk say e involve firewall and routing changes. Both parts dey important. Gluetun add route for each subnet wey you list through Docker bridge gateway, so packets wey go those addresses go comot through eth0 instead of the tunnel. E still open firewall for dem, because gluetun normally dey drop outbound traffic wey no dey go VPN server.

Write the value without space after the commas.

      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32,192.168.1.0/24,100.64.7.9/32

Two things easy to miss. This setting dey apply for the whole namespace, so e affect every container wey dey behind gluetun, no be only the one wey you get for mind. And e only affect outbound traffic: e control connections wey container start. Connections wey enter through published port dey follow another path, so you no need add dem here.

Wetin a Tailscale peer fit use reach the web UI

Tailscale dey give every machine address for 100.64.0.0/10, wey be range wey dem reserve for carrier grade NAT. None of this dey cost anything for personal tailnet, though the free plan cap of six users go decide whether this one still free when other people need access to the same UIs. User devices no get limit for every plan. Servers and other tagged devices dey count separately: Tailscale pricing page list 50 tagged resources wey dey included, then extra ones cost $1 per month each. Since billing dey count users instead of machines, how much paid tailnet really cost mostly depend on how many people you invite, no be how many containers you expose to dem. The two directions need different work.

Inbound na the simple one. Publishing 8080:8080 on gluetun binds that port to all the host addresses, and the host's tailscale0 interface na one of dem, so peer fit open http://<machine-name>:8080 and reach the container. Gluetun no dey part of that path, because Docker NAT rule dey for the host, outside the namespace.

To make the UI reachable only through the tailnet, bind the published port to the host's Tailscale address instead of every address.

    ports:
      - "100.101.102.103:8080:8080/tcp"

Use tailscale ip -4 for the host to find that address. Binding na stronger control here pass firewall rule, because the port no ever open for the public interface at all. If you prefer reach the UI with HTTPS name instead of host and port, tailscale serve fit front that published port, though serve and funnel no get the same reachability and na only one of dem keep the UI on the tailnet. E also avoid the problem for Docker publishing ports directly past ufw. The Tailscale sidecar pattern for Compose go further and remove the host port completely, but e work by putting the app inside the sidecar network namespace, and container wey dey behind gluetun don already use its one network_mode on gluetun.

Outbound na where FIREWALL_OUTBOUND_SUBNETS come back. If container need call peer, add that peer address, and prefer one /32 per peer instead of the whole /10. If the machine wey you dey call dey for private network reached through VPS wey advertise that subnet to your tailnet, list the advertised range instead of the router own 100.x address, and confirm say the host itself accept those routes. MagicDNS names no resolve inside the container by default, because the container dey use gluetun DNS server instead of the host resolver, so use the numeric 100.x address or pin the name with extra_hosts line for the gluetun service. Gluetun DNS_UPSTREAM_PLAIN_ADDRESSES option fit forward queries to another resolver instead, but e send every query as plaintext, and gluetun documentation advise against am because queries to private address fit leak outside the VPN tunnel. The same thing apply when you run your own Tailscale control server with Headscale.

Complete compose file for the common shape

A download client wey dey behind VPN, two web UIs wey dey answer only on the tailnet, and one container wey dey read PostgreSQL database wey dey run for the host.

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - "127.0.0.1:8000:8000/tcp"        # gluetun control server, host only
      - "100.101.102.103:8080:8080/tcp"  # qBittorrent UI, tailnet only
      - "100.101.102.103:9696:9696/tcp"  # Prowlarr UI, tailnet only
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - ./gluetun:/gluetun
    environment:
      - VPN_SERVICE_PROVIDER=mullvad
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}
      - WIREGUARD_ADDRESSES=${WIREGUARD_ADDRESSES}
      - SERVER_CITIES=Amsterdam
      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32,100.64.7.9/32
      - TZ=Europe/Amsterdam
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Amsterdam
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent:/config
      - /srv/downloads:/downloads
    depends_on:
      gluetun:
        condition: service_healthy
    restart: unless-stopped

  prowlarr:
    image: lscr.io/linuxserver/prowlarr:latest
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Amsterdam
      - PROWLARR__POSTGRES__HOST=host.docker.internal
      - PROWLARR__POSTGRES__PORT=5432
      - PROWLARR__POSTGRES__USER=prowlarr
      - PROWLARR__POSTGRES__PASSWORD=${PROWLARR_DB_PASSWORD}
      - PROWLARR__POSTGRES__MAINDB=prowlarr-main
      - PROWLARR__POSTGRES__LOGDB=prowlarr-log
    volumes:
      - ./prowlarr:/config
    depends_on:
      gluetun:
        condition: service_healthy
    restart: unless-stopped

Read the file to understand the pattern, no be the product names. Both UIs dey publish through gluetun and bind to the host tailnet address, so dem dey answer on Tailscale and nowhere else. The extra_hosts line dey also inside gluetun, because Prowlarr dey read gluetun /etc/hosts when e dey resolve host.docker.internal, and Docker go reject the line if you put am for Prowlarr itself. FIREWALL_OUTBOUND_SUBNETS dey name two single addresses: the Docker bridge address of the host, so Prowlarr fit open database connection, and one tailnet peer.

The PostgreSQL server no dey inside the file on purpose. E dey run for the VPS as normal system service wey dey listen on 172.17.0.1:5432. Na the same layering as an arr stack for Docker Compose, but the database don move outside Docker.

Keep the WireGuard private key outside the compose file. ${WIREGUARD_PRIVATE_KEY} dey read from a .env file wey dey beside am, as the pattern for env files and secrets for Docker Compose explain. The condition: service_healthy clause dey use the healthcheck wey the gluetun image already ship with, so nothing go start until the tunnel report say e don come up. Compose healthchecks explain the general form.

Publishing for every address instead of only the tailnet

Remove the address prefix and the port binds for 0.0.0.0, wey include the VPS public IP. Do this only behind firewall wey you control, and read the ufw note above first.

    ports:
      - "8080:8080/tcp"

Confirm say the tunnel still dey carry traffic

Run the same request two times: one time from inside the namespace, and one time from the host. Then compare the results.

docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org
curl -s https://api.ipify.org

The first one suppose print your VPN provider exit address. The second one suppose print the VPS address. If dem match, e mean say the container traffic no dey pass through the tunnel. Until you correct this, every other fix for this guide no go matter.

The routing rules and tables show which traffic dey avoid the tunnel and which one no dey.

docker run --rm --network=container:gluetun alpine:3.22 sh -c 'ip rule show; ip route show table 51820; ip route show table 199'

For the WireGuard setup wey dey this guide, gluetun name the tunnel interface wg0. The name tun0 na only the default for OpenVPN. Gluetun also keep the tunnel default route outside the main routing table. ip rule show suppose get one rule wey sends all traffic wey WireGuard itself no mark to table 51820. That table suppose get one default route on wg0. Table 199 get one route for every entry inside FIREWALL_OUTBOUND_SUBNETS. Each route point to the Docker bridge gateway on eth0, and the system checks its rule just before the tunnel rule. A plain ip route show still lists Docker own default route on eth0. This one dey expected and e no be leak, because the system checks both gluetun rules before the main table. Any route for table 199 wey you no list na traffic wey dey bypass the VPN.

Gluetun control server fit report the same public IP on port 8000, for /v1/publicip/ip. But by default, e fit only do this after you set authentication. Gluetun documentation talk say all control server routes dey private by default now, so plain request to that path go fail. Configure am with an auth file wey you bind mount at /gluetun/auth/config.toml, using the basic or apikey method. Then restart gluetun. The compose file above already mounts ./gluetun at /gluetun, so put the file for ./gluetun/auth/config.toml on the host. The HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE variable na the quicker option. If you set am to {"auth":"none"}, authentication go turn off completely. The docs strongly advise against this. For releases before v3.39.1, the server no get this restriction, and the docs warn say you suppose trust anything wey fit reach am.

One wrong subnet wey create leak

FIREWALL_OUTBOUND_SUBNETS na hole wey you intentionally open for firewall, so the size of the hole na the size of the risk. These four things fit make am too big:

  • 0.0.0.0/0 dey send everything outside the tunnel. The two IP checks above go catch this for the first run, because dem go return the same address.
  • Range wey pass the target size. Opening 10.0.0.0/8 to reach one machine for 10.0.1.7 also opens every address wey torrent peer fit advertise for that range. Write 10.0.1.7/32.
  • Range wey overlap with the tunnel own addresses. gluetun documentation warn say this go make gluetun send VPN traffic through the bridge instead, and that go break port forwarding. Check your WIREGUARD_ADDRESSES value before you open any private range.
  • 100.64.0.0/10 for Tailscale. That one open roughly four million addresses so one peer fit reach. List the peers wey you need as /32 entries.

Remember say this setting cover the whole namespace. If you open a subnet so indexer fit reach a host service, the same subnet go open for the torrent client wey dey share that namespace. Run the public IP check again after every change to this variable, because na only that test fit show whether the change do wetin you mean.

Wetin go break when you restart gluetun

gluetun own the namespace, so gluetun lifecycle na the namespace lifecycle. If you start a dependent container while gluetun dey down, e go fail immediately:

Error response from daemon: cannot join network namespace of a non running container: container <id> is exited

Restarting gluetun in place na the quieter failure. The dependent containers go continue running while dem dey rebuild the namespace wey dem attach to underneath dem, so docker ps go report say everything healthy, but nothing go answer. After any change to the gluetun service, recreate the whole group instead of restarting only one part.

docker compose up -d --force-recreate

Na the same thing for image updates. If you pull new gluetun image and recreate only that service, the other ones go still point to namespace wey no longer exist.

FAQ

Why Docker dey talk say “port publishing and the container type network mode”?

Because a ports: block still dey for a service wey also set network_mode: service:gluetun. Publishing port dey add NAT rule wey forward host port enter container own network namespace, and container wey dey this mode no get its own namespace. Delete ports: block from that service, then add the same mapping to gluetun service. Port number no change, because the application still dey listen on am inside the shared namespace.

How other containers dey reach service wey dey behind gluetun?

Containers wey dey inside the same namespace dey reach each other through 127.0.0.1. Containers wey dey outside am use gluetun service name, so http://gluetun:8080 go work where http://qbittorrent:8080 no go work. The application container no get address for any Docker network, so the embedded DNS server get nothing to resolve for its name. You no need publish port for this, as long as both containers share one Compose network.

Wetin I suppose put for FIREWALL_OUTBOUND_SUBNETS?

Na only addresses wey container behind gluetun must start connection to, and you suppose write dem as narrowly as possible. One machine na /32. The two common entries na Docker host for 172.17.0.1/32 and one /32 for every Tailscale peer wey you dey call. Never add 0.0.0.0/0, and never add range wey overlap with your VPN own tunnel addresses. Inbound connections to published port no need entry here.

Why the container no fit resolve my Tailscale MagicDNS names?

MagicDNS dey work by pointing host resolver to Tailscale DNS server, but container no dey use host resolver. E dey use /etc/resolv.conf wey e share with gluetun, and this one dey point to gluetun own DNS server. Confirm am with docker exec <container> cat /etc/resolv.conf. Use the peer numeric 100.x address, or pin the name with extra_hosts entry for gluetun service. Gluetun fit forward queries to another resolver with DNS_UPSTREAM_PLAIN_ADDRESSES, but that one dey send dem as plaintext and its documentation advise against am.

How I fit confirm say traffic still dey pass through VPN?

Run one request from inside the namespace and run the same request from host, then compare the answers. docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org suppose return your VPN provider exit address, while curl -s https://api.ipify.org for the VPS returns the VPS address. If both answers match, e mean say the tunnel no dey carry the container traffic. Run this check again after every change to FIREWALL_OUTBOUND_SUBNETS.

Dis article help you?