SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

Gluetun: acceder al host y a otros contenedores

Un contenedor detrás de Gluetun no tiene interfaces propias: publica sus puertos en Gluetun y permite solo las subredes externas que necesita.

Qué ocurre cuando un contenedor se une a la red de gluetun

Un contenedor que establece network_mode: service:gluetun no tiene interfaces de red propias. Se une al espacio de nombres de red de gluetun, por lo que la publicación de puertos y las reglas del firewall dejan de ser propiedades de ese contenedor y pasan a ser propiedades del servicio gluetun. Todas las respuestas siguientes se derivan de ese hecho.

Un espacio de nombres de red es una copia privada de la pila de red del kernel: tiene sus propias interfaces, su propia tabla de enrutamiento, sus propias reglas del firewall y sus propios sockets en escucha. Docker asigna uno a cada contenedor de forma predeterminada. Cuando se escribe network_mode: service:gluetun, Docker omite ese paso y coloca el contenedor nuevo dentro del espacio de nombres que ya posee gluetun. El contenedor conserva su propio sistema de archivos, pero no sus propios /etc/hosts ni /etc/resolv.conf: Docker le proporciona los mismos archivos que usa gluetun, y eso será importante más adelante.

Puede verlo directamente.

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

Esto muestra container: seguido del ID del contenedor gluetun, mientras que un contenedor normal mostraría bridge. Esta guía continúa donde termina enrutar el tráfico de Docker a través de una VPN con gluetun: el túnel funciona y ahora nada puede comunicarse con el contenedor.

Publica el puerto en gluetun, no en la aplicación

Deja un bloque ports: en el servicio que establece network_mode y Docker rechaza crear el contenedor:

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

La causa es directa. Publicar un puerto significa añadir una regla NAT (traducción de direcciones de red) que reenvía un puerto del host al espacio de nombres de red propio de un contenedor, pero este contenedor no tiene uno. Mueve la asignación al servicio gluetun. El número de puerto no cambia, porque la aplicación sigue escuchando en ese puerto dentro del espacio de nombres compartido.

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

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

Un bloque expose: en el servicio dependiente falla de la misma forma, con conflicting options: port exposing and the container type network mode, y un bloque networks: también detiene el proceso: Compose informa de que el servicio declara network_mode y networks, que son mutuamente excluyentes, y se niega a cargar el archivo.

Esto provoca otro problema más adelante. Todos los contenedores del espacio de nombres comparten un único espacio de puertos. Por tanto, dos aplicaciones que usan 8080 de forma predeterminada entran en conflicto y la segunda que se inicia falla con un error de dirección ya en uso. Cambia una de ellas en su propia configuración. Por ejemplo, cambia la variable WEBUI_PORT en la imagen LinuxServer qBittorrent y publica el nuevo número en gluetun.

¿Cómo se comunican entre sí los contenedores detrás de gluetun?

Dentro del namespace ya comparten una interfaz de loopback. Un contenedor detrás de gluetun llega a su contenedor hermano en 127.0.0.1:<port> sin usar ninguna red de Docker.

Desde fuera del namespace, el contenedor no tiene nombre. El DNS integrado de Docker resuelve un nombre de servicio en la dirección de ese servicio dentro de una red definida por el usuario, pero este contenedor no tiene una dirección en ninguna red. Por tanto, un contenedor normal como Sonarr no llega al cliente torrent en http://qbittorrent:8080. Llega a él en http://gluetun:8080, porque el socket está escuchando en el namespace de gluetun, en la dirección de gluetun. Esto sorprende a quienes saben cómo funcionan las redes y los nombres de servicio de Docker Compose y esperan que se aplique el esquema de nombres habitual. También funciona sin publicar nada en el host, porque ambos contenedores están en la misma red de Compose.

Compruebe el DNS antes de depurar cualquier otra cosa. Gluetun ejecuta su propio servidor DNS dentro del namespace, y Docker proporciona a todos los contenedores detrás de gluetun el mismo archivo /etc/resolv.conf que a gluetun. Por tanto, las búsquedas de la aplicación pasan por el resolvedor de gluetun en lugar del host. De forma predeterminada, ese resolvedor también rechaza las respuestas que apuntan a direcciones privadas. Por eso un nombre que se resuelve en el host puede fallar dentro del contenedor. La documentación de gluetun indica que esos nombres de host deben incluirse en DNS_REBINDING_PROTECTION_EXEMPT_HOSTNAMES.

docker exec qbittorrent cat /etc/resolv.conf

¿Cómo accedo a un servicio que se ejecuta en el host de Docker?

Use host.docker.internal. Requiere dos configuraciones, ambas en el servicio gluetun, porque hay dos problemas distintos.

El nombre va primero. Un contenedor situado detrás de gluetun lee el /etc/hosts de gluetun, y Docker rechaza una entrada extra_hosts en un servicio que define network_mode con conflicting options: custom host-to-IP mapping and the network mode. Por tanto, la entrada debe estar en gluetun y todos los contenedores del espacio de nombres pueden verla.

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

host-gateway es un valor especial que Docker sustituye por una dirección interna del propio host. En una instalación normal de Docker en Linux, es la dirección del puente docker0, normalmente 172.17.0.1. Confirme cuál usa su sistema con ip -4 addr show docker0 en el VPS. Docker Desktop resuelve este nombre automáticamente. Por eso las guías escritas para un equipo portátil omiten la línea extra_hosts y el mismo archivo falla después en un servidor.

La ruta va después. Añadir el nombre sólo indica al contenedor qué dirección debe usar. El paquete sigue saliendo por la ruta predeterminada de gluetun, que es el túnel, y el firewall de gluetun lo descarta. El síntoma es una conexión que espera y finalmente agota el tiempo de espera, no una conexión rechazada. Un rechazo significa que el paquete llegó y algo respondió negativamente. Un tiempo de espera agotado significa que nunca llegó.

  gluetun:
    environment:
      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32

Después, compruebe que el servicio del host realmente está escuchando en esa dirección. Un servidor PostgreSQL enlazado sólo a 127.0.0.1 no es accesible desde ningún contenedor que tenga su propio espacio de nombres de red. Esto incluye todos los contenedores situados detrás de gluetun, independientemente de si usan el túnel, porque 127.0.0.1 dentro del espacio de nombres es el bucle local de ese espacio de nombres. Sólo un contenedor que use la red del host comparte el bucle local del host, y un contenedor situado detrás de gluetun ya ha utilizado su network_mode en gluetun. Enlace PostgreSQL a 172.17.0.1 en su lugar: aceptará conexiones de los contenedores sin exponerse a la interfaz pública. Verifíquelo con ss -lntp | grep 5432 en el host.

Qué cambia realmente FIREWALL_OUTBOUND_SUBNETS

La documentación de gluetun lo describe como las subredes separadas por comas a las que gluetun y los contenedores que comparten su pila de red pueden acceder, y señala que implica cambios en el firewall y en el enrutamiento. Ambas partes son importantes. Gluetun añade una ruta para cada subred indicada a través de la puerta de enlace del puente de Docker, por lo que los paquetes destinados a esas direcciones salen por eth0 en lugar de hacerlo por el túnel. También abre el firewall para esas subredes, porque gluetun descarta de lo contrario el tráfico saliente que no está dirigido al servidor VPN.

Escriba el valor sin espacios después de las comas.

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

Hay dos propiedades fáciles de pasar por alto. Esta configuración se aplica en el ámbito del espacio de nombres, por lo que afecta a todos los contenedores que están detrás de gluetun, no sólo al que tenía en mente. Además, sólo se aplica al tráfico saliente: controla las conexiones que inicia un contenedor. Las conexiones que llegan a un puerto publicado siguen una ruta diferente y no necesitan ninguna entrada aquí.

Acceder a la interfaz web desde un par de Tailscale

Tailscale asigna a cada máquina una dirección de 100.64.0.0/10, el rango reservado para NAT de nivel de operador. En un tailnet personal, esto no tiene ningún coste, aunque el límite de seis usuarios del plan gratuito determina si esto sigue siendo así cuando otras personas necesitan acceder a las mismas interfaces. Los dispositivos de usuario son ilimitados en todos los planes. Los servidores y otros dispositivos etiquetados se cuentan por separado: la página de precios de Tailscale indica que se incluyen 50 recursos etiquetados, y que los adicionales cuestan $1 al mes cada uno. Como la facturación cuenta principalmente usuarios y no máquinas, el coste real de un tailnet de pago depende sobre todo del número de personas que invite, no del número de contenedores que les exponga. Cada dirección requiere una configuración distinta.

La entrada es sencilla. Publicar 8080:8080 en gluetun enlaza ese puerto en todas las direcciones del host, y la interfaz tailscale0 del host es una de ellas. Por tanto, un par puede abrir http://<machine-name>:8080 y acceder al contenedor. Docker aplica NAT en el host, y el firewall de gluetun permite el tráfico entrante hacia su subred de Docker.

Para que la interfaz solo sea accesible a través del tailnet, enlace el puerto publicado con la dirección de Tailscale del host, en lugar de enlazarlo con todas las direcciones.

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

Obtenga esa dirección con tailscale ip -4 en el host. En este caso, el enlace proporciona un control más estricto que una regla de firewall, porque el puerto nunca se abre en la interfaz pública. Si prefiere acceder a la interfaz mediante un nombre HTTPS en lugar de mediante un host y un puerto, tailscale serve puede situarse delante de ese puerto publicado, aunque serve y funnel se diferencian en quién puede acceder finalmente y solo uno de los dos mantiene la interfaz dentro del tailnet. Esto también evita el problema descrito en Publicar puertos de Docker directamente, fuera de ufw. El patrón de sidecar de Tailscale para Compose va más lejos y elimina por completo el puerto del host, pero funciona colocando la aplicación en el espacio de nombres de red del sidecar, y un contenedor situado detrás de gluetun ya ha utilizado su único network_mode en gluetun.

La salida es donde vuelve a intervenir FIREWALL_OUTBOUND_SUBNETS. Si un contenedor debe conectarse a un par, añada la dirección de ese par y prefiera un /32 por par en lugar de utilizar todo /10. Si la máquina a la que se conecta está en una red privada accesible mediante un VPS que anuncia esa subred a su tailnet, indique el rango anunciado en lugar de la dirección 100.x del router y confirme que el propio host ha aceptado esas rutas. Los nombres de MagicDNS no se resuelven dentro del contenedor de forma predeterminada, porque el contenedor utiliza el servidor DNS de gluetun en lugar del resolvedor del host. Por tanto, use la dirección numérica 100.x o fije el nombre mediante una línea extra_hosts en el servicio de gluetun. La opción DNS_UPSTREAM_PLAIN_ADDRESSES de gluetun puede reenviar las consultas a otro resolvedor, pero envía todas las consultas en texto plano. La documentación de gluetun desaconseja esta opción porque las consultas dirigidas a una dirección privada salen del túnel VPN. Lo mismo se aplica cuando ejecuta su propio servidor de control de Tailscale con Headscale.

Un archivo Compose completo para esta estructura habitual

Un cliente de descargas detrás de la VPN, dos interfaces web que responden sólo en la tailnet y un contenedor que lee una base de datos PostgreSQL que se ejecuta en el 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

Lea el archivo para entender el patrón, no los nombres de los productos. Ambas interfaces se publican en gluetun y se vinculan a la dirección tailnet del host, por lo que responden mediante Tailscale y en ningún otro lugar. La línea extra_hosts también se ejecuta en gluetun, porque Prowlarr lee el /etc/hosts de gluetun cuando resuelve host.docker.internal, y Docker rechazaría esa línea en el propio Prowlarr. FIREWALL_OUTBOUND_SUBNETS especifica dos direcciones individuales: la dirección del puente Docker del host, para que Prowlarr pueda abrir una conexión con la base de datos, y un par de la tailnet.

El servidor PostgreSQL se omite deliberadamente del archivo. Se ejecuta en el VPS como un servicio normal del sistema y escucha en 172.17.0.1:5432. Es la misma separación por capas que una pila de aplicaciones arr en Docker Compose, con la base de datos fuera de Docker.

Mantenga la clave privada de WireGuard fuera del archivo Compose. ${WIREGUARD_PRIVATE_KEY} lee un archivo .env situado junto a él, según el patrón descrito en archivos env y secretos para Docker Compose. La cláusula condition: service_healthy usa el healthcheck que la imagen gluetun ya incluye, por lo que nada se inicia hasta que el túnel indica que está activo. Los healthchecks de Compose explican la estructura general.

Publicar en todas las direcciones en lugar de sólo en la tailnet

Quite el prefijo de dirección y los enlaces de puertos en 0.0.0.0, que incluye la IP pública del VPS. Hágalo sólo detrás de un firewall que controle y lea primero la nota sobre ufw anterior.

    ports:
      - "8080:8080/tcp"

Confirme que el túnel sigue transportando tráfico

Ejecute la misma solicitud dos veces: una desde dentro del espacio de nombres y otra desde el host, y compare los resultados.

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

La primera debe mostrar la dirección de salida de su proveedor de VPN. La segunda debe mostrar la dirección del VPS. Si coinciden, el tráfico del contenedor no está pasando por el túnel. Hasta corregirlo, el resto de esta guía no es aplicable.

Las reglas y tablas de enrutamiento muestran qué tráfico pasa por el túnel y cuál no.

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

Con la configuración de WireGuard de esta guía, gluetun asigna el nombre wg0 a la interfaz del túnel. El nombre tun0 es sólo el valor predeterminado de OpenVPN. Gluetun también mantiene la ruta predeterminada del túnel fuera de la tabla de enrutamiento principal. ip rule show debe incluir una regla que envíe a la tabla 51820 todo el tráfico que no esté marcado por el propio WireGuard, y esa tabla debe contener una ruta predeterminada en wg0. La tabla 199 contiene una ruta por cada entrada de FIREWALL_OUTBOUND_SUBNETS. Cada ruta apunta a la puerta de enlace del puente de Docker en eth0, y su regla se comprueba justo antes que la del túnel. Un ip route show simple todavía muestra la ruta predeterminada propia de Docker en eth0. Esto es normal y no constituye una fuga, porque las dos reglas de gluetun se comprueban antes que la tabla principal. Cualquier ruta de la tabla 199 que no haya especificado corresponde a tráfico que omite la VPN.

El servidor de control de gluetun puede informar de la misma IP pública en el puerto 8000, en /v1/publicip/ip, pero de forma predeterminada sólo después de configurar la autenticación. La documentación de gluetun indica que todas las rutas del servidor de control son privadas de forma predeterminada, por lo que una solicitud simple a esa ruta falla. Configúrelo con un archivo de autenticación montado mediante bind en /gluetun/auth/config.toml usando el método basic o apikey y, después, reinicie gluetun. El archivo Compose anterior ya monta ./gluetun en /gluetun, por lo que el archivo debe estar en ./gluetun/auth/config.toml en el host. La variable HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE es la opción más rápida. Si la establece en {"auth":"none"}, desactiva por completo la autenticación, algo que la documentación desaconseja encarecidamente. En una versión anterior a v3.39.1, el servidor no está protegido de esta forma y la documentación advierte que debe confiar en cualquier cliente que pueda acceder a él.

La fuga que provoca una subred incorrecta

FIREWALL_OUTBOUND_SUBNETS es una abertura que se crea deliberadamente en el firewall, por lo que el tamaño de la abertura determina el tamaño del riesgo. Evite estos cuatro errores:

  • 0.0.0.0/0 no supera la validación de configuración con outbound subnet has an unspecified address: 0.0.0.0/0. Gluetun lo rechaza en lugar de enrutar todo el tráfico fuera del túnel.
  • Un rango más amplio que el destino. Abrir 10.0.0.0/8 para acceder a una máquina en 10.0.1.7 también abre todas las direcciones que un par de torrent podría anunciar dentro de ese rango. Escriba 10.0.1.7/32.
  • Un rango que se solapa con las direcciones del propio túnel. La documentación de gluetun advierte que esto hace que gluetun envíe el tráfico VPN a través del bridge, lo que rompe el reenvío de puertos. Compruebe el valor de WIREGUARD_ADDRESSES antes de abrir cualquier rango privado.
  • 100.64.0.0/10 para Tailscale. Esto abre aproximadamente cuatro millones de direcciones para que se pueda acceder a un solo par. Incluya los pares necesarios como entradas /32.

Recuerde que esta configuración cubre todo el espacio de nombres. Abrir una subred para que un indexador pueda acceder a un servicio del host también abre esa misma subred para el cliente torrent que comparte ese espacio de nombres. Vuelva a ejecutar la comprobación de IP pública después de cada cambio en esta variable, porque es la única prueba que muestra si el cambio ha producido el resultado previsto.

Qué falla al reiniciar gluetun

gluetun controla el espacio de nombres, por lo que el ciclo de vida de gluetun es también el del espacio de nombres. Si inicia un contenedor dependiente mientras gluetun está detenido, el inicio falla inmediatamente:

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

Reiniciar gluetun en el mismo lugar provoca un fallo menos evidente. Los contenedores dependientes siguen ejecutándose mientras se reconstruye por debajo el espacio de nombres al que estaban conectados, por lo que docker ps informa que todo funciona correctamente, pero ningún servicio responde. Después de cualquier cambio en el servicio gluetun, vuelva a crear todo el grupo en lugar de reiniciar una sola parte.

docker compose up -d --force-recreate

Lo mismo se aplica a las actualizaciones de imágenes. Si descarga una imagen nueva de gluetun y vuelve a crear sólo ese servicio, los demás quedan apuntando a un espacio de nombres que ya no existe.

FAQ

¿Por qué Docker muestra "port publishing and the container type network mode"?

Porque todavía hay un bloque ports: en un servicio que también define network_mode: service:gluetun. Publicar un puerto añade una regla NAT que reenvía un puerto del host al espacio de nombres de red propio de un contenedor, pero un contenedor en este modo no tiene uno. Elimine el bloque ports: de ese servicio y añada el mismo mapeo al servicio gluetun. El número de puerto no cambia, porque la aplicación sigue escuchando en él dentro del espacio de nombres compartido.

¿Cómo acceden otros contenedores a un servicio que está detrás de gluetun?

Los contenedores que están dentro del mismo espacio de nombres se alcanzan mediante 127.0.0.1. Los contenedores que están fuera usan el nombre del servicio gluetun, por lo que http://gluetun:8080 funciona, pero http://qbittorrent:8080 no. El contenedor de la aplicación no tiene ninguna dirección en una red Docker, por lo que el servidor DNS integrado no tiene nada que resolver para su nombre. No es necesario publicar ningún puerto para esto, siempre que ambos contenedores compartan una red de Compose.

¿Qué debo incluir en FIREWALL_OUTBOUND_SUBNETS?

Sólo las direcciones a las que un contenedor detrás de gluetun debe iniciar una conexión, expresadas con la mayor precisión posible. Un único equipo se expresa como /32. Las dos entradas habituales son el host de Docker en 172.17.0.1/32 y un /32 por cada peer de Tailscale al que se conecte. No añada nunca 0.0.0.0/0 ni un rango que se solape con las direcciones del túnel propio de la VPN. Las conexiones entrantes a un puerto publicado no necesitan ninguna entrada aquí.

¿Por qué el contenedor no puede resolver mis nombres MagicDNS de Tailscale?

MagicDNS funciona configurando el resolver del host para que use el servidor DNS de Tailscale, pero el contenedor no usa el resolver del host. Usa el /etc/resolv.conf que comparte con gluetun, y que apunta al propio servidor DNS de gluetun. Confírmelo con docker exec <container> cat /etc/resolv.conf. Use la dirección numérica 100.x del peer o asocie el nombre mediante una entrada extra_hosts en el servicio gluetun. Gluetun puede reenviar las consultas a otro resolver mediante DNS_UPSTREAM_PLAIN_ADDRESSES, pero las envía en texto plano y su documentación desaconseja hacerlo.

¿Cómo confirmo que el tráfico sigue pasando por la VPN?

Ejecute una petición desde dentro del espacio de nombres y la misma petición desde el host; después, compare las respuestas. docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org debería devolver la dirección de salida de su proveedor de VPN, mientras que curl -s https://api.ipify.org en el VPS devuelve la dirección del VPS. Dos respuestas iguales indican que el túnel no está transportando el tráfico del contenedor. Repita esta comprobación después de cada cambio en FIREWALL_OUTBOUND_SUBNETS.

¿Te resultó útil este artículo?