SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-11-12

Why Docker VPN Container Ports Vanish with Gluetun

Gluetun shared network dey make container ports and service name disappear. See the exact Docker error, correct compose setup, and why v3.41.3 matter.

Wetin make ports disappear when you route Docker containers through VPN

To route Docker containers through VPN, you go give one container the tunnel, then attach the other ones to its network namespace with network_mode: "service:gluetun". Na this attachment dey surprise people. The attached container no longer get its own network, so its published ports and Docker service name disappear together with am. Publish the ports for the VPN container instead, and other containers fit reach the app through the VPN container name.

If you leave ports: block for the attached container, Docker go refuse to create am at all:

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

The tool wey we use here na Gluetun, a container wey connects to commercial VPN (virtual private network) provider through WireGuard or OpenVPN and carries its own firewall. Release v3.41.3 na the current one as of October 2026. The examples use Mullvad with WireGuard, so you need account and key from your provider. If you prefer terminate the tunnel on hardware wey you own, run your own WireGuard server on a VPS go build the other end, while wg-easy for Docker go wrap am with web interface.

Wetín network_mode: "service:gluetun" really dey do

Every Docker container normally dey get im own network namespace: im own interfaces, routing table, firewall rules and listening sockets. service: mode dey skip that step and start the container inside gluetun namespace. One namespace mean one IP address, and this one change six things.

  • The app no get im own address. Na gluetun address be im address.
  • The app no attach to any Docker network, so dem no register im service name and e no go resolve. Other containers must use gluetun.
  • Containers wey dey inside the namespace fit reach each other through localhost.
  • Two containers for one namespace no fit listen on the same port. Gluetun documentation talk am clearly: no workaround dey.
  • Capabilities belong to container, not namespace. Gluetun get NET_ADMIN and /dev/net/tun because na im create the tunnel interface. The attached container no inherit dem.
  • Compose reject any file where one service set both network_mode and networks. Attach gluetun to your networks, and the app go follow am.

If you restart gluetun, e go disconnect everything wey attach to am. Na documented behaviour be this, and na why gluetun dey restart the VPN process inside the container instead of exiting when the connection fail. After you restart or recreate gluetun yourself, restart the containers wey attach to am.

Compose file wey dey work

services:
  gluetun:
    image: qmcgaw/gluetun:v3
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=mullvad
      - VPN_TYPE=wireguard
      - SERVER_CITIES=Amsterdam
      - TZ=Europe/Amsterdam
    env_file:
      - ./gluetun.env
    volumes:
      - ./gluetun:/gluetun
    ports:
      - 127.0.0.1:8080:8080/tcp
    restart: unless-stopped

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

The :v3 tag na the newest stable release for v3 series. The :latest tag point to the last commit for master branch, wey be the development edge, so pin :v3 for machine wey you no wan debug on Tuesday.

WEBUI_PORT=8080 gats match the published port, because qBittorrent dey bind inside gluetun namespace and the publish rule dey send host traffic go port 8080 there. If you change one number without changing the other, the port no go answer anything. 127.0.0.1:8080:8080 keep the web interface for host loopback address. Bare 8080:8080 go publish for every interface and write its own firewall rule, and na so Docker published ports dey bypass ufw directly.

Bring am up, then check am for this order:

docker compose up -d
docker compose ps
docker compose logs gluetun | tail -30

docker compose ps suppose show gluetun as healthy and qbittorrent as running. Then confirm the exit address from inside the namespace. Na this check dey decide everything else:

docker run --rm --network=container:gluetun alpine:3.22 sh -c "apk add wget && wget -qO- https://ipinfo.io"

The ip field for that JSON suppose be your VPN provider address. If na your server own address, the app no dey inside the tunnel, and nothing for down go behave as described.

Key dem no suppose dey inside compose file

gluetun.env dey hold the login details, and e no dey enter git:

WIREGUARD_PRIVATE_KEY=wOEI9rqqbDwnN8/Bpp22sVz48T71vJ4fYmFWujulwUU=
WIREGUARD_ADDRESSES=10.64.222.21/32

Both values come from one WireGuard configuration file wey you generate for your provider account area. Set the file mode to 600. Make you understand wetin this arrangement provide: the key no dey inside your repository, but docker inspect gluetun still dey print every environment variable to anybody wey fit reach the Docker socket. Environment files and secrets for Docker Compose explain the stronger options.

How container wey dey outside tunnel fit talk to one wey dey inside am

Both directions dey work, and each one dey use different name. The two containers need shared Docker network. Na gluetun network be this, because the attached container no get network of its own. How Docker Compose networks dey wired explain the default setup.

To connect from outside go inside, use gluetun name and the port wey the app dey listen on. A reverse proxy container fit reach the qBittorrent web interface for gluetun:8080. You no need any ports: entry for this, because traffic between containers dey remain for Docker network and e no dey pass through host port.

To connect from inside go outside, use the other container service name, like postgres:5432. Gluetun don dey resolve other container names from inside its namespace since v3.41. So pin that version or newer one if a name no gree resolve.

Gluetun firewall dey decide who fit open connection to am. Traffic from gluetun own Docker network dey allowed. But client wey dey another subnet, laptop for your LAN, or container for separate bridge network, needs return path wey gluetun firewall and routing allow:

FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24

The documented meaning dey exact: comma separated subnets wey Gluetun and the containers wey dey share its network stack fit access.

Inbound connections from internet na separate problem. Peers of torrent client dey enter through VPN side, so publishing port 6881 on the host no go do anything for dem. You need forwarded port from your provider, and you need list that port inside FIREWALL_VPN_INPUT_PORTS. This allows ports from VPN server side. Mullvad, wey this example use, no support port forwarding, so you need provider wey support am. Na this part most media stacks wey Docker Compose build leave broken.

The kill switch: wetin dey happen when the tunnel drop

This pattern show why the extra complexity dey useful when failure happen. The attached container share Gluetun interfaces and routing table. Gluetun firewall block ordinary internet traffic wey dey outside the tunnel, but e allow VPN server endpoint, local Docker traffic, and configured exceptions. Na this firewall dey prevent fallback to the plain interface when the tunnel drop. No time dey when packets fit leak through the plain interface while client dey reconnect.

Gluetun dey monitor its own connection. Every minute e send ICMP echo (a ping) go the addresses for HEALTH_ICMP_TARGET_IPS, wey default to 1.1.1.1,8.8.8.8. If ICMP no dey allowed, that small check go use plaintext UDP DNS query instead. Every five minutes e make complete TCP and TLS (transport layer security) connection go HEALTH_TARGET_ADDRESSES, wey default to cloudflare.com:443,github.com:443. When these checks fail, e restart the VPN inside the container and log am:

WARN [vpn] restarting VPN because it failed to pass the healthcheck: periodic check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout

Read the attached container logs with this order for mind. Lines like connection refused, operation not permitted and i/o timeout inside the app na consequences of dead tunnel, no be the causes. Gluetun documentation talk this one clear, because people dey report the consequence and spend hours dey chase am.

HEALTH_RESTART_VPN=on na the default and e suppose remain on. Turn am off only when you dey debug one specific failure, because when e off, dead tunnel go remain dead.

Ordering: stop the stack from starting before the tunnel is up

The image get one Docker healthcheck:

HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=3 CMD /gluetun-entrypoint healthcheck

That command dey run one second, short-lived copy of gluetun. E dey query the health server of the running one for http://127.0.0.1:9999/. Tunnel wey dey work go answer 200 OK. Broken tunnel go answer 500 Internal server error with error string, and Docker go mark the container as unhealthy after three checks fail one after another.

condition: service_healthy na wetin dey wait for that. Plain depends_on: [gluetun] dey wait only for the container to start. This one happen some seconds before the handshake complete, so the app go start with dead network and often give up on the first connection attempt. Healthchecks for Docker Compose explain the syntax and the timing fields.

One limit fit catch people. Compose dey evaluate this condition when e start the stack. E no go stop or restart the app later if gluetun turn unhealthy. Gluetun internal auto-healing dey handle that case instead. Na why e dey restart the VPN process, not the container.

Check weda DNS leak dey before you trust the setup

DNS (domain name system) na the leak wey fit still dey even if your tunnel correct. Gluetun dey run im own resolver inside the namespace and e dey forward queries via DoT (DNS over TLS) go Cloudflare by default: DNS_UPSTREAM_RESOLVER_TYPE=dot and DNS_UPSTREAM_RESOLVERS=cloudflare. No touch any of dem so your lookups go dey encrypted and dem go pass through the tunnel.

The setting wey dey spoil this one if you point am go local resolver na DNS_UPSTREAM_PLAIN_ADDRESSES. People dey use am if name no gree resolve and dem want make dia router or dia provider resolver answer dem instead. The Gluetun documentation warn say queries wey you send go resolver for your Docker bridge or LAN go leak outside the VPN tunnel. Public plaintext resolver still go receive queries through the tunnel, but the VPN provider fit read and change dem. The WireGuard version of this same mistake dey inside DNS wey stop to resolve over a WireGuard tunnel.

To test am, set SHADOWSOCKS=on and SHADOWSOCKS_PASSWORD for gluetun, publish 8388:8388/tcp and 8388:8388/udp, then connect with one Shadowsocks client wey you don configure to tunnel UDP DNS, then load one DNS leak test. The result suppose show your provider or Cloudflare, e no suppose show your home router. Gluetun own documentation warn say some leak tests fit give funny result, because the resolver inside the namespace na local caching intermediary, e no be the server wey finally answer the query. If you see wrong country or your own ISP resolver, na sign say something no correct.

Adding Tailscale beside the VPN sidecar, and which one go win

Tailscale na overlay network wey dem build on WireGuard to reach your own machines, and people dey run am beside provider VPN to keep admin path enter the stack. Sharing namespace also mean say dem dey share firewall rules, so both settings need work well together for firewall and routing. Tailscale documentation talk the default clearly: e dey act as overlay network, e only route traffic between devices wey dey run Tailscale, and e no touch your public internet traffic.

So, the answer depend on one setting.

  • Tailscale for im own container, default configuration: e no ever see the app outbound traffic. Gluetun carry all of am. Process for Tailscale container fit reach the app for gluetun:8080 through shared Docker network; to expose that connection to tailnet clients, forwarding or proxy dey needed.
  • Tailscale attached to gluetun namespace with network_mode: "service:gluetun": for default userspace networking mode, TS_USERSPACE dey on. tailscaled no create any interface at all, and e work as SOCKS5 or HTTP proxy, so e no fit change routing. Gluetun still carry ordinary outbound traffic unless app explicitly use that proxy.
  • The same setup with TS_USERSPACE=false: Tailscale need im own /dev/net/tun device and capabilities because namespace no provide dem. tailscaled create tunnel device and, for Linux, e normally install individual IPv4 peer /32 routes instead of one route for 100.64.0.0/10. Setting TS_USERSPACE=false alone no enable the aggregate route. E install other nodes' subnet routes only if you pass --accept-routes through TS_EXTRA_ARGS. TS_ROUTES work for the other direction: e advertise subnets wey this container fit reach to the rest of your tailnet, the equivalent of tailscale set --advertise-routes=, and e no add any route here. Public traffic still comot through gluetun.
  • Kernel networking for gluetun namespace with exit node selected, sudo tailscale set --exit-node=<exit-node-ip>: Tailscale install default routes for that namespace, but Gluetun firewall fit block that path. Selecting exit node for separate container no change the app routes, and userspace mode only carry traffic wey dem explicitly send through im proxy. No combine competing default routes for gluetun namespace. One default route, one owner.

If na those advertised routes you need, and you want the whole private network behind the box reachable instead of only the box, running Tailscale subnet router on a VPS cover route approval, IP forwarding, and the client-side flag wey TS_ROUTES leave undone by itself.

If Tailscale dey there to give you admin URL instead of route, tailscale serve and tailscale funnel put HTTPS in front of local HTTP service, while only funnel open am to public internet. Tailscale Serve documentation support only http://127.0.0.1 as HTTP proxy target. Shared Docker network no make http://gluetun:8080 supported target. Share gluetun network namespace with network_mode: "service:gluetun" and target http://127.0.0.1:8080.

One side effect dey show when Tailscale run inside the tunnel. Im peers see VPN provider address, so expect am to fall back to relays more often. tailscale status show relay "..." beside peer instead of direct when that happen. Connection dey work, but e slower. If na overlay alone you really need, the difference between plain WireGuard and Tailscale na better place to start.

Wetin dey spoil, and the message wey you go see

Docker no gree create the app container. Error response from daemon: conflicting options: port publishing and the container type network mode mean say one ports: block still dey sit down for the service wey you attach. Move am go gluetun.

Compose no gree take the whole file. One service no fit set both network_mode and networks. Put the networks for gluetun.

Another container no fit resolve the app. curl: (6) Could not resolve host: qbittorrent na correct behaviour, because the container wey you attach no join any network and no register any name. Use gluetun and the port.

The second container wey you attach no go start. Two processes for one namespace no fit bind the same port, and the one wey lose go report say the address don already dey use. Change the internal port of the app, or run second gluetun.

The app no get network after you touch gluetun. If you restart or recreate gluetun, e go cut connection for everything wey attach to am. Restart those containers.

Small pages dey load but big ones dey hang. That one na MTU (maximum transmission unit). The tunnel dey add overhead, and something for the path dey drop the packets wey too big without send error back. Check WIREGUARD_MTU, wey e default for v3.41.3 na 1320, and reduce am if the path need smaller packets. The development image dey use path MTU discovery when this setting no dey set.

Gluetun no dey ever healthy. The startup check dey call the first suspects: WARN [vpn] restarting VPN because it failed to pass the healthcheck: startup check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout. Check whether the key don expire, then check whether the server list don old, then check whether your host firewall dey block outbound UDP.

FAQ

Why my container published ports stop working behind Gluetun?

Because network_mode: "service:gluetun" dey put the container inside gluetun network namespace, and one namespace get one IP address and one set of listening ports. The app still dey listen, but the publish rule must dey on the container wey own the namespace. Move the ports: list go the gluetun service. If you leave am on the attached service, Docker no go even create am: Error response from daemon: conflicting options: port publishing and the container type network mode.

How I fit reach container wey dey inside VPN tunnel from container wey dey outside am?

Use gluetun service name and the port wey the app dey listen on, for example gluetun:8080. The attached container no get Docker network of its own, so its own name no go resolve. You no need publish anything for container-to-container traffic. The other way round, container wey dey inside the namespace fit reach outside container with the service name, like postgres:5432, for Gluetun v3.41 and newer. Client wey dey another subnet, like laptop for your LAN, need return path wey gluetun firewall and routing allow; add that subnet to FIREWALL_OUTBOUND_SUBNETS.

Gluetun dey work as kill switch when VPN disconnect?

Yes, if you enable its firewall. The attached container dey share Gluetun interfaces and routes, and the firewall blocks normal internet traffic wey dey try pass outside the tunnel, while e still allows VPN server endpoint, local Docker traffic, and configured exceptions. Gluetun then restart the VPN internally and log WARN [vpn] restarting VPN because it failed to pass the healthcheck, instead of exiting, because every attached container go lose network when gluetun itself restart.

Tailscale and Gluetun for the same stack: which one dey carry outbound traffic?

Gluetun dey carry normal outbound traffic unless you deliberately send am through Tailscale. By default, Tailscale only route traffic between devices for your tailnet and leave public traffic alone. For the container image default userspace mode, e no create any interface, so e no fit affect routing. With TS_USERSPACE=false, Linux normally get separate IPv4 peer /32 routes instead of one aggregate 100.64.0.0/10 route, plus subnet routes for other nodes only if you add --accept-routes through TS_EXTRA_ARGS. TS_ROUTES advertise this container subnets to your tailnet and no add local routes. If you select an exit node with sudo tailscale set --exit-node=<exit-node-ip>, e install default routes only inside the namespace wey use Tailscale kernel networking; separate container no change the app routes, and userspace mode only carry traffic wey pass through its proxy. Choose one product to own the default route instead of stacking both.

Dis article help you?