SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor

Gluetun: як дістатися хоста й інших контейнерів

Контейнер за Gluetun не має власних інтерфейсів: публікуйте його порти на Gluetun і відкривайте лише потрібні підмережі поза VPN-тунелем.

Що відбувається, коли контейнер приєднується до мережі gluetun

Контейнер, у якому задано network_mode: service:gluetun, не має власних мережевих інтерфейсів. Він приєднується до мережевого простору імен gluetun, тому публікація портів і правила брандмауера більше не належать цьому контейнеру, а стають властивостями сервісу gluetun. Усі наведені нижче відповіді випливають із цього факту.

Мережевий простір імен — це приватна копія мережевого стека ядра: із власними інтерфейсами, таблицею маршрутизації, правилами брандмауера та сокетами, що прослуховують порти. Docker за замовчуванням створює окремий простір для кожного контейнера. Коли ви вказуєте network_mode: service:gluetun, Docker пропускає цей крок і розміщує новий контейнер у просторі імен, яким уже володіє gluetun. Контейнер зберігає власну файлову систему, але не власні /etc/hosts або /etc/resolv.conf: Docker передає йому ті самі файли, які використовує gluetun, і це стане важливим далі.

Це можна побачити безпосередньо.

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

Команда виводить container:, а потім ідентифікатор контейнера gluetun, тоді як для звичайного контейнера вона вивела б bridge. Цей посібник продовжує тему маршрутизації трафіку Docker через VPN за допомогою gluetun: тунель працює, але тепер контейнер недоступний.

Опублікуйте порт на gluetun, а не на застосунку

Залиште блок ports: у сервісі, який задає network_mode, і Docker відмовиться створювати контейнер:

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

Причина проста. Публікація порту додає правило NAT (network address translation), яке переспрямовує порт хоста в окремий мережевий простір імен контейнера. У цього контейнера власного мережевого простору імен немає. Перенесіть mapping до сервісу gluetun. Номер порту не змінюється, оскільки застосунок і далі прослуховує цей порт у спільному мережевому просторі імен.

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

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

Блок expose: у залежному сервісі завершується так само з conflicting options: port exposing and the container type network mode. Блок networks: там також спричиняє критичну помилку: Compose повідомляє, що сервіс оголошує взаємовиключні network_mode і networks, і взагалі відмовляється завантажувати файл.

Пізніше це спричиняє ще одну проблему. Усі контейнери в цьому просторі імен використовують один спільний простір портів. Тому два застосунки, які за замовчуванням використовують порт 8080, конфліктують. Другий застосунок не запускається з помилкою, що адреса вже використовується. Змініть порт для одного з них у його власній конфігурації, наприклад змініть змінну WEBUI_PORT в образі LinuxServer qBittorrent, а потім опублікуйте новий номер порту на gluetun.

Як контейнери за gluetun підключаються один до одного?

У межах namespace вони вже спільно використовують loopback-інтерфейс. Контейнер за gluetun підключається до сусіднього контейнера через 127.0.0.1:<port>, без використання Docker network.

Поза межами namespace контейнер не має власного імені. Вбудований DNS Docker зіставляє ім’я сервісу з адресою цього сервісу в user-defined network, а цей контейнер не має адреси в жодній мережі. Тому звичайний контейнер, наприклад Sonarr, не підключається до torrent-клієнта через http://qbittorrent:8080. Він підключається через http://gluetun:8080, оскільки сокет слухає в namespace gluetun за адресою gluetun. Це дивує користувачів, які знають як працюють мережі Docker Compose та імена сервісів і очікують стандартної схеми іменування. Це також працює без публікації порту на хості, оскільки обидва контейнери підключені до тієї самої Compose network.

Перед будь-якою іншою діагностикою перевірте DNS. Gluetun запускає власний DNS-сервер у межах namespace, а Docker надає кожному контейнеру за gluetun такий самий файл /etc/resolv.conf, як і gluetun. Тому запити вашого застосунку проходять через resolver gluetun, а не через resolver хоста. Типово цей resolver також відхиляє відповіді, які вказують на приватні адреси. Через це ім’я, яке успішно розв’язується на хості, може не розв’язуватися всередині контейнера. У документації gluetun зазначено, що такі імена хостів потрібно додати до DNS_REBINDING_PROTECTION_EXEMPT_HOSTNAMES.

docker exec qbittorrent cat /etc/resolv.conf

Як підключитися до сервісу, що працює на Docker host?

Скористайтеся host.docker.internal. Потрібні два налаштування, обидва для сервісу gluetun, оскільки порушено дві різні умови.

Спочатку вкажіть ім’я. Контейнер за gluetun читає /etc/hosts gluetun, а Docker відхиляє запис extra_hosts для сервісу, який задає network_mode за допомогою conflicting options: custom host-to-IP mapping and the network mode. Тому цей запис потрібно додати до gluetun, і його побачать усі контейнери в цьому network namespace.

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

host-gateway — це спеціальне значення, яке Docker замінює внутрішньою адресою самого host. У звичайній інсталяції Docker на Linux це адреса bridge docker0, зазвичай 172.17.0.1. Перевірте її командою ip -4 addr show docker0 на VPS. Docker Desktop визначає це ім’я самостійно. Тому в інструкціях для ноутбука часто немає рядка extra_hosts, а той самий файл потім не працює на сервері.

Потім додайте маршрут. Саме ім’я лише повідомляє контейнеру, яку адресу використовувати. Пакет усе одно виходить через маршрут за замовчуванням gluetun, тобто через tunnel, а firewall gluetun його відкидає. Ознака цього — з’єднання зависає, а потім завершується за timeout, а не одразу відхиляється. Відмова означає, що пакет надійшов і отримав негативну відповідь. Timeout означає, що пакет не дійшов.

  gluetun:
    environment:
      - FIREWALL_OUTBOUND_SUBNETS=172.17.0.1/32

Після цього перевірте, чи host service справді слухає цю адресу. PostgreSQL, прив’язаний лише до 127.0.0.1, недоступний із будь-якого контейнера, що має власний network namespace. Це стосується всіх контейнерів за gluetun, незалежно від наявності tunnel, оскільки 127.0.0.1 всередині namespace — це loopback самого namespace. Лише контейнер із host networking використовує loopback host. Контейнер за gluetun уже використав свій network_mode для gluetun. Натомість прив’яжіть PostgreSQL до 172.17.0.1: це дасть змогу приймати підключення від контейнерів і водночас не відкривати сервіс на публічному інтерфейсі. Перевірте результат командою ss -lntp | grep 5432 на host.

Що саме змінює FIREWALL_OUTBOUND_SUBNETS

Документація gluetun описує цей параметр як перелік підмереж, розділених комами, до яких gluetun і контейнери зі спільним мережевим стеком дозволено підключатися. Також зазначено, що параметр змінює правила firewall і маршрутизацію. Важливі обидві частини. Gluetun додає маршрут для кожної вказаної підмережі через шлюз Docker bridge, тому пакети до цих адрес виходять через eth0, а не через тунель. Також gluetun відкриває для них доступ у firewall, оскільки інакше він відкидає вихідний трафік, не призначений для VPN-сервера.

Указуйте значення без пробілів після ком.

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

Є дві властивості, які легко пропустити. Це налаштування рівня namespace, тому воно застосовується до кожного контейнера за gluetun, а не лише до потрібного вам контейнера. І воно діє лише для вихідного трафіку: параметр визначає з’єднання, які ініціює контейнер. З’єднання, що надходять на опублікований порт, проходять іншим шляхом, тому цей параметр для них не потрібен.

Доступ до вебінтерфейсу з вузла Tailscale

Tailscale надає кожній машині адресу в діапазоні 100.64.0.0/10, зарезервованому для carrier-grade NAT. У personal tailnet це не потребує оплати, хоча ліміт безкоштовного плану в шість користувачів визначає, чи залишиться це безкоштовним, якщо іншим людям знадобиться доступ до тих самих вебінтерфейсів. Кількість користувацьких пристроїв необмежена в усіх планах. Сервери та інші пристрої з тегами обліковуються окремо: на сторінці цін Tailscale зазначено 50 включених tagged resources, а кожен додатковий коштує $1 на місяць. Оскільки в інших випадках оплата залежить від кількості користувачів, а не машин, фактична вартість платного tailnet переважно визначається кількістю запрошених людей, а не кількістю контейнерів, до яких ви надаєте їм доступ. Для цих двох напрямків потрібні різні дії.

Вхідний доступ налаштувати простіше. Публікація 8080:8080 у gluetun прив’язує цей порт до всіх адрес хоста. Інтерфейс tailscale0 хоста є однією з них, тому вузол tailnet відкриває http://<machine-name>:8080 і отримує доступ до контейнера. Docker застосовує NAT на хості, а firewall gluetun дозволяє вхідний трафік до його Docker subnet.

Щоб вебінтерфейс був доступний лише через tailnet, прив’яжіть опублікований порт до Tailscale-адреси хоста, а не до всіх адрес.

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

Знайдіть цю адресу на хості за допомогою tailscale ip -4. У цьому випадку прив’язка є надійнішим обмеженням, ніж правило firewall, оскільки порт взагалі не відкривається на публічному інтерфейсі. Якщо ви хочете відкривати вебінтерфейс за HTTPS-іменем, а не за адресою хоста та портом, tailscale serve може проксувати цей опублікований порт. Однак serve і funnel відрізняються тим, хто зрештою може отримати до нього доступ, і лише один із них залишає вебінтерфейс у tailnet. Це також усуває проблему, описану в публікації Docker портів безпосередньо повз ufw. Підхід із Tailscale sidecar для Compose дає ще жорсткіше обмеження та повністю прибирає порт хоста. Але він працює шляхом розміщення застосунку в network namespace sidecar, а контейнер за gluetun уже використав свій єдиний network_mode на gluetun.

Вихідний доступ — це місце, де знову з’являється FIREWALL_OUTBOUND_SUBNETS. Якщо контейнер має підключатися до вузла tailnet, додайте адресу цього вузла. Для кожного вузла краще вказати окремий /32, а не весь /10. Якщо вузол, до якого ви підключаєтеся, розташований у приватній мережі, доступній через VPS, який оголошує цю підмережу у ваш tailnet, вкажіть оголошений діапазон, а не власну адресу 100.x маршрутизатора. Також переконайтеся, що хост прийняв ці маршрути. Імена MagicDNS за замовчуванням не розв’язуються всередині контейнера, оскільки контейнер використовує DNS-сервер gluetun, а не resolver хоста. Тому використовуйте числову адресу 100.x або закріпіть ім’я рядком extra_hosts у сервісі gluetun. Опція DNS_UPSTREAM_PLAIN_ADDRESSES gluetun може натомість пересилати запити до іншого resolver, але надсилає кожен запит у незашифрованому вигляді. Документація gluetun не рекомендує цей варіант, оскільки запити до приватної адреси виходять за межі VPN-тунелю. Те саме стосується випадку, коли ви запускаєте власний сервер керування Tailscale за допомогою Headscale.

Повний compose-файл для типової схеми

Клієнт завантажень працює через VPN, два вебінтерфейси відповідають лише в tailnet, а один контейнер підключається до PostgreSQL, запущеного на хості.

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

Читайте файл, щоб зрозуміти схему, а не назви продуктів. Обидва вебінтерфейси опубліковані через gluetun і прив’язані до tailnet-адреси хоста, тому вони доступні через Tailscale і більше нізвідки. Рядок extra_hosts також розміщений у gluetun, оскільки Prowlarr читає /etc/hosts gluetun під час визначення host.docker.internal, а Docker відхилив би цей рядок безпосередньо в Prowlarr. FIREWALL_OUTBOUND_SUBNETS задає дві окремі адреси: адресу Docker bridge хоста, щоб Prowlarr міг відкрити підключення до бази даних, і одну адресу вузла tailnet.

Сервер PostgreSQL навмисно відсутній у цьому файлі. Він працює на VPS як звичайний системний сервіс і слухає 172.17.0.1:5432. Це та сама схема, що й arr-стек у Docker Compose, але базу даних винесено за межі Docker.

Не зберігайте приватний ключ WireGuard у compose-файлі. ${WIREGUARD_PRIVATE_KEY} читає його з файлу .env поруч із compose-файлом. Цей підхід описано в розділі env-файли та секрети для Docker Compose. Директива condition: service_healthy використовує healthcheck, який уже постачається з образом gluetun, тому жоден сервіс не запускається, доки тунель не повідомить про готовність. Загальну форму описано в розділі healthcheck у Compose.

Публікація на всіх адресах замість лише tailnet

Видаліть префікс адреси та прив’язки портів у 0.0.0.0. Це також відкриє порт на публічній IP-адресі VPS. Робіть це лише за наявності firewall, яким ви керуєте, і спочатку прочитайте наведену вище примітку про ufw.

    ports:
      - "8080:8080/tcp"

Переконайтеся, що тунелем досі проходить трафік

Виконайте той самий запит двічі: один раз зсередини namespace, а другий — з host, і порівняйте результати.

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

У першому випадку має бути виведена exit-адреса вашого VPN-провайдера. У другому — адреса VPS. Якщо адреси збігаються, трафік контейнера не проходить через тунел. Поки це не виправлено, решта інструкцій у цьому посібнику не має значення.

Правила й таблиці маршрутизації показують, який трафік обходить тунел, а який — ні.

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

У конфігурації WireGuard з цього посібника gluetun називає інтерфейс тунелю wg0. Назва tun0 є лише стандартним ім’ям для OpenVPN. Gluetun також зберігає маршрут за замовчуванням тунелю поза основною таблицею маршрутизації. У ip rule show має бути правило, яке надсилає весь трафік, не позначений самим WireGuard, до таблиці 51820, а ця таблиця має містити маршрут за замовчуванням через wg0. Таблиця 199 містить по одному маршруту для кожного запису в FIREWALL_OUTBOUND_SUBNETS. Кожен маршрут вказує на шлюз Docker bridge у eth0, а правило цієї таблиці перевіряється безпосередньо перед правилом тунелю. Звичайний ip route show і далі показує власний маршрут Docker за замовчуванням через eth0. Це очікувано й не є витоком трафіку, оскільки обидва правила gluetun перевіряються перед основною таблицею. Будь-який маршрут у таблиці 199, якого ви не вказали, означає, що відповідний трафік обходить VPN.

Control server gluetun може повідомити ту саму публічну IP-адресу через порт 8000 за адресою /v1/publicip/ip, але за замовчуванням лише після налаштування автентифікації. У документації gluetun зазначено, що всі маршрути control server тепер за замовчуванням є приватними, тому звичайний запит до цього шляху завершується помилкою. Налаштуйте його за допомогою файлу автентифікації, змонтованого в /gluetun/auth/config.toml, використовуючи метод basic або apikey, а потім перезапустіть gluetun. Наведений вище compose file уже монтує ./gluetun у /gluetun, тому на host файл має бути розташований у ./gluetun/auth/config.toml. Змінна HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE є швидшим способом. Якщо встановити для неї значення {"auth":"none"}, автентифікацію буде повністю вимкнено, що в документації позначено як настійно не рекомендоване. У release до v3.39.1 server не був захищений таким чином, і в документації зазначено, що потрібно довіряти будь-чому, що може отримати до нього доступ.

Витік, який створює неправильна підмережа

FIREWALL_OUTBOUND_SUBNETS — це навмисно створений отвір у firewall, тому розмір цього отвору визначає розмір ризику. Уникайте чотирьох помилок:

  • 0.0.0.0/0 не проходить перевірку конфігурації з помилкою outbound subnet has an unspecified address: 0.0.0.0/0. Gluetun відхиляє це значення, а не маршрутизує весь трафік поза тунелем.
  • Надто широкий діапазон. Відкриття 10.0.0.0/8 для доступу до однієї машини за адресою 10.0.1.7 також відкриває всі адреси, які torrent peer може оголосити в цьому діапазоні. Запишіть 10.0.1.7/32.
  • Діапазон, який перетинається з власними адресами тунелю. Документація gluetun попереджає, що в такому разі gluetun починає надсилати VPN-трафік через bridge, а це ламає port forwarding. Перевірте значення WIREGUARD_ADDRESSES перед відкриттям будь-якого приватного діапазону.
  • 100.64.0.0/10 для Tailscale. Це приблизно чотири мільйони відкритих адрес, щоб отримати доступ до одного вузла. Додайте потрібні вузли окремими записами /32.

Пам’ятайте, що цей параметр діє на весь namespace. Відкриття підмережі, щоб indexer міг отримати доступ до сервісу хоста, відкриває ту саму підмережу й для torrent client, який використовує цей namespace. Після кожної зміни цієї змінної повторно виконуйте перевірку публічної IP-адреси. Це єдиний тест, який показує, чи дала зміна очікуваний результат.

Що ламається після перезапуску gluetun

Gluetun керує network namespace, тому життєвий цикл gluetun визначає життєвий цикл namespace. Спроба запустити залежний контейнер, коли gluetun не працює, одразу завершується помилкою:

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

Перезапуск gluetun без пересоздання групи спричиняє менш очевидний збій. Залежні контейнери продовжують працювати, хоча namespace, до якого вони підключилися, перебудовується під ними. Тому docker ps повідомляє, що все працює, але жоден сервіс не відповідає. Після будь-якої зміни в сервісі gluetun пересоздавайте всю групу, а не перезапускайте лише один її компонент.

docker compose up -d --force-recreate

Те саме стосується оновлення образу. Якщо завантажити новий образ gluetun і пересоздати лише цей сервіс, інші контейнери залишаться підключеними до namespace, якого більше не існує.

FAQ

Чому Docker повідомляє "port publishing and the container type network mode"?

Це відбувається тому, що блок ports: досі задано для сервісу, у якому також налаштовано network_mode: service:gluetun. Публікація порту додає правило NAT, яке переспрямовує порт хоста у власний мережевий простір імен контейнера. Контейнер у цьому режимі не має окремого мережевого простору імен. Видаліть блок ports: із цього сервісу та додайте таке саме зіставлення до сервісу gluetun. Номер порту не змінюється, оскільки застосунок і далі прослуховує його у спільному мережевому просторі імен.

Як інші контейнери можуть отримати доступ до сервісу, що працює через gluetun?

Контейнери в одному мережевому просторі імен звертаються один до одного через 127.0.0.1. Контейнери поза ним використовують ім’я сервісу gluetun, тому http://gluetun:8080 працює, а http://qbittorrent:8080 — ні. Контейнер застосунку не має адреси в жодній Docker network, тому вбудованому DNS-серверу нічого повертати для його імені. Публікація порту для цього не потрібна, якщо обидва контейнери підключені до однієї Compose network.

Що потрібно вказати у FIREWALL_OUTBOUND_SUBNETS?

Вказуйте лише адреси, до яких контейнер за gluetun має встановлювати вихідні з’єднання, і задавайте їх якомога точніше. Окремий хост — це /32. Два типові записи — Docker host за адресою 172.17.0.1/32 і по одному /32 для кожного Tailscale peer, до якого потрібно підключатися. Ніколи не додавайте 0.0.0.0/0 і не додавайте діапазон, що перетинається з власними tunnel-адресами VPN. Для вхідних з’єднань до опублікованого порту цей параметр не потрібен.

Чому контейнер не може визначити мої імена Tailscale MagicDNS?

MagicDNS працює, коли resolver хоста спрямовує запити на DNS-сервер Tailscale. Контейнер не використовує resolver хоста. Він використовує /etc/resolv.conf, спільний із gluetun, який спрямовує запити на власний DNS-сервер gluetun. Перевірте це за допомогою docker exec <container> cat /etc/resolv.conf. Використовуйте числову адресу peer 100.x або зафіксуйте ім’я за допомогою запису extra_hosts у сервісі gluetun. Gluetun може переспрямовувати запити до іншого resolver за допомогою DNS_UPSTREAM_PLAIN_ADDRESSES, але в такому разі вони передаються у відкритому вигляді, і документація не рекомендує цей спосіб.

Як перевірити, що трафік і далі проходить через VPN?

Виконайте один запит із мережевого простору імен і такий самий запит із хоста, а потім порівняйте відповіді. docker run --rm --network=container:gluetun curlimages/curl:latest -s https://api.ipify.org має повернути адресу виходу вашого VPN-провайдера, а curl -s https://api.ipify.org на VPS — адресу VPS. Однакові відповіді означають, що тунель не передає трафік контейнера. Повторюйте цю перевірку після кожної зміни FIREWALL_OUTBOUND_SUBNETS.

Чи була ця стаття корисною?