Gluetun: проброс порту для torrent-клієнта
Завантаження працюють, але вхідних підключень немає? Налаштуйте проброс порту в Gluetun, передавайте новий порт клієнту після reconnect і перевірте його.
Чому без проброшеного порту немає вхідних підключень
Проброс портів у Gluetun просить вашого VPN-провайдера зіставити один публічний порт на його вихідній адресі з вашим контейнером. Це єдиний спосіб, у який інший peer може ініціювати підключення до вашого torrent-клієнта. Без такого зіставлення тунель працює, завантаження виконуються, але вхідні підключення самостійно не надходять. Кожне робоче підключення ініціює ваш клієнт.
Цей механізм називається NAT (перетворення мережевих адрес). Ваш контейнер використовує вихідну адресу провайдера спільно з багатьма іншими клієнтами. Коли ваш клієнт відкриває вихідне підключення, провайдер записує цей потік і передає відповіді назад через ваш тунель. Вхідне підключення від peer, який вам невідомий, не відповідає жодному записаному потоку. Тому пакет доходить до вихідної адреси й відкидається там. Ваш клієнт і далі підключається до кожного peer, який сам може приймати підключення, тому завантаження завершуються, а проблема залишається непомітною. Вона проявляється під час роздачі, оскільки seeder — це машина, до якої підключаються інші користувачі.
Відкритий вхідний порт змінює дві речі. Ви швидше підключаєтеся до swarm, оскільки peer, які самі не можуть приймати підключення, тепер можуть підключатися до вас. Крім того, ви взагалі можете передавати дані цим peer.
Чому більшість VPN-провайдерів не пропонує переадресацію порту
Переадресований порт є обмеженим ресурсом на спільній адресі. Провайдер резервує один номер порту на одній вихідній IP-адресі для одного клієнта, а потім відповідає за все, що цей клієнт робить через нього. Кілька великих провайдерів вилучили цю функцію та назвали причиною обробку зловживань. Розглядайте підтримку цієї функції як окреме питання, а не як прапорець у списку можливостей: запитайте, чи пропонує провайдер переадресацію портів зараз, у вашому тарифі та на серверах, які ви справді можете вибрати.
Якщо переадресація доступна, порт є динамічним. Він належить сеансу VPN, а не вашому обліковому запису, тому після кожного повторного підключення номер може бути іншим. Private Internet Access видає підписаний порт, який gluetun оновлює. В документації upstream зазначено, що той самий порт зберігається протягом 60 днів, якщо змонтувати каталог /gluetun через bind mount, щоб стан зберігався після перезапуску. ProtonVPN призначає випадковий порт через NAT-PMP (протокол зіставлення портів NAT) на короткий строк оренди, який потрібно постійно поновлювати. Тому одноразове встановлення порту в клієнті не забезпечує його постійну роботу.
Які провайдери можуть запитувати порт через gluetun
Станом на gluetun v3.41.3, випущену 30 July 2026, нативна інтеграція перевіряє чотири назви провайдерів: Private Internet Access, ProtonVPN, Perfect Privacy і PrivateVPN. Увімкніть її за допомогою VPN_PORT_FORWARDING=on. За замовчуванням це off. У старіших інструкціях використовуються PORT_FORWARDING або PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING. В обох випадках у цій версії вони ще працюють як сумісні зі старими конфігураціями назви, але їх поступово вилучають.
Дві особливості провайдерів визначають, чи може запит узагалі виконатися. Для ProtonVPN потрібен платний план, а NAT-PMP має бути ввімкнено: увімкніть NAT-PMP (Port Forwarding) у параметрах VPN під час створення конфігурації WireGuard або додайте +pmp до імені користувача, якщо використовуєте OpenVPN. Для Private Internet Access в OpenVPN доступний параметр PORT_FORWARD_ONLY. Він обмежує вибір серверів серверами з підтримкою port forwarding, щоб підключення не потрапило на сервер, який ніколи його не підтримував. WireGuard і OpenVPN по-різному запитують порт, тому перед вибором ознайомтеся зі сторінкою свого провайдера.
Коли gluetun використовує власну конфігурацію замість вбудованого провайдера, VPN_PORT_FORWARDING_PROVIDER визначає API, до якого gluetun має звертатися. На сторінці Private Internet Access у upstream-репозиторії цю змінну використовують разом із VPN_PORT_FORWARDING_USERNAME і VPN_PORT_FORWARDING_PASSWORD. Вони передають облікові дані, потрібні для запиту порту.
Увімкнення перенаправлення портів gluetun у docker compose
Це передбачає, що тунель уже працює. Якщо ні, спочатку виконайте маршрутизацію трафіку Docker-контейнерів через gluetun, а потім поверніться до цього розділу, коли завантаження запрацюють.
services:
gluetun:
image: qmcgaw/gluetun:v3.41.3
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
ports:
- 8080:8080/tcp
- 8000:8000/tcp
volumes:
- ./gluetun:/gluetun
environment:
- VPN_SERVICE_PROVIDER=protonvpn
- VPN_TYPE=wireguard
- WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}
- VPN_PORT_FORWARDING=on
- TZ=Etc/UTC
restart: unless-stopped
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:5.2.3
container_name: qbittorrent
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- WEBUI_PORT=8080
volumes:
- ./qbittorrent:/config
- ./downloads:/downloads
depends_on:
- gluetun
restart: unless-stoppedЗафіксуйте тег. qmcgaw/gluetun:latest стежить за гілкою master, де внутрішні механізми перенаправлення портів змінюються для v4, тому образ без зафіксованого тегу може змінити поведінку під час наступного docker compose pull. Зберігайте приватний ключ поза файлом compose за допомогою env-файлу для секретів compose.
Де gluetun записує перенаправлений порт
Gluetun надає порт у трьох місцях, і всюди вказано однакове значення.
Під час кожного отримання порту він один раз записує його в журнал. Рядок має вигляд port forwarded is 45678, а якщо запит не повернув значення — no port forwarded.
docker logs gluetun 2>&1 | grep -i "port forwarded"Він записує номер у файл, заданий параметром VPN_PORT_FORWARDING_STATUS_FILE; значення за замовчуванням — /tmp/gluetun/forwarded_port. Файл містить один порт у кожному рядку, має права доступу 0644, а його власником і групою є відповідно PUID та PGID контейнера. Коли перенаправлення припиняється, gluetun очищає файл, а не видаляє його. Тому споживач отримує порожній файл, а не помилку через відсутній файл.
docker exec gluetun cat /tmp/gluetun/forwarded_portВін надає це значення через control server, який за замовчуванням прослуховує :8000 і налаштовується параметром HTTP_CONTROL_SERVER_ADDRESS.
curl -s http://127.0.0.1:8000/v1/portforward{"port":45678,"ports":[45678]}Gluetun також відкриває цей порт у власному firewall на VPN-інтерфейсі. Тому FIREWALL_VPN_INPUT_PORTS не потрібна, якщо працює нативна інтеграція. Ця змінна потрібна в іншому випадку: коли провайдер не підтримується gluetun, а ви отримали статичний порт іншим каналом і маєте дозволити його вручну.
Одне з цих трьох джерел є довговічним, а два інші — ні. Документація upstream позначає status file як deprecated у v4.0.0. Крім того, GET /v1/openvpn/portforwarded уже повертає 301 Moved Permanently із посиланням на /v1/portforward. Новий код має читати дані з control server.
Чому клієнту потрібно повідомляти порт після кожного повторного підключення
Torrent-клієнт зберігає порт для прослуховування у власній конфігурації та використовує цей номер після перезапуску. Перенаправлений порт є властивістю сеансу VPN. Після повторного підключення ці два номери не збігаються: провайдер перенаправляє порт, який ніхто не прослуховує, а клієнт прослуховує порт, на який нічого не перенаправляється. Повторні підключення не є рідкістю: це може бути перезапуск контейнера, зміна сервера, розірваний тунель, який health check gluetun перезапускає, або lease, який не вдалося поновити. У результаті конфігурація, яка вчора була доступною, сьогодні непомітно стає недоступною, хоча в жодному журналі немає помилки.
Тому порт потрібно застосовувати саме в момент, коли gluetun отримує його. Є два способи це налаштувати. Вони відрізняються тим, який процес виконує цю роботу.
Варіант 1: gluetun передає порт за допомогою команди up
VPN_PORT_FORWARDING_UP_COMMAND виконується після встановлення port forwarding, а VPN_PORT_FORWARDING_DOWN_COMMAND — після його вимкнення. Gluetun підставляє {{PORT}} (перший порт), {{PORTS}} (усі порти через кому) і {{VPN_INTERFACE}} (назву інтерфейсу тунелю, за замовчуванням — tun0), перш ніж виконати команду. Для синтаксису shell потрібна явна оболонка-обгортка /bin/sh -c. Це приклад від upstream для qBittorrent, записаний як два параметри середовища compose:
- VPN_PORT_FORWARDING_UP_COMMAND=/bin/sh -c 'wget -O- -nv --retry-connrefused --post-data "json={\"listen_port\":{{PORT}},\"current_network_interface\":\"{{VPN_INTERFACE}}\",\"random_port\":false,\"upnp\":false}" http://127.0.0.1:8080/api/v2/app/setPreferences'
- VPN_PORT_FORWARDING_DOWN_COMMAND=/bin/sh -c 'wget -O- -nv --retry-connrefused --post-data "json={\"listen_port\":0,\"current_network_interface\":\"lo\"}" http://127.0.0.1:8080/api/v2/app/setPreferences'Кожне поле цього виклику має окреме призначення. listen_port — це новий порт. current_network_interface прив’язує qBittorrent до тунелю. Значення false для random_port забороняє qBittorrent вибирати власний порт під час наступного запуску. Значення false для upnp забороняє йому намагатися налаштувати перенаправлення порту через маршрутизатор, якого немає.
Цей підхід має дві вимоги. Вебінтерфейс qBittorrent має бути увімкнений і прослуховувати порт 8080, а спільний network namespace gluetun дає змогу відповідати на 127.0.0.1:8080 із контейнера gluetun. Також має бути увімкнено Bypass authentication for clients on localhost (bypass_local_auth), оскільки команда не передає облікові дані. Команда down потрібна тому, що після розриву з’єднання qBittorrent не завжди повторно встановлює порт.
Команда виконується всередині контейнера gluetun, створеного на базі Alpine, до якого входить wget. У цьому образі немає curl. Команда, яка викликає бінарний файл, відсутній в образі, щоразу завершується помилкою під час встановлення port forwarding.
Варіант 2: процес поза gluetun читає порт
Інший підхід — запустити поруч із gluetun невеликий процес, який отримує порт і передає його клієнту через власний API клієнта. Прочитайте його з control server:
port=$(curl -s http://127.0.0.1:8000/v1/portforward | jq -r .port)Або прочитайте файл, якщо процес має до нього доступ. /tmp/gluetun/forwarded_port розташований усередині контейнера gluetun, тому для sidecar потрібен спільний volume, змонтований у /tmp/gluetun в обох контейнерах. Інший варіант — вказати VPN_PORT_FORWARDING_STATUS_FILE на шлях у volume, який уже змонтований.
Автентифікація тут важлива. У v3.41.3 маршрут GET /v1/portforward належить до ролі за замовчуванням із назвою public та параметром auth = "none", тому відповідає без облікових даних, а gluetun записує попередження, що починається з route GET /v1/portforward is unprotected by default, please set up authentication. У наступнішому релізі upstream закриває цей доступ. Поточна документація control server уже описує кожен маршрут як приватний за замовчуванням. Визначте роль уже зараз у файлі, змонтованому через bind mount у /gluetun/auth/config.toml:
roles = [
{ name = "qbittorrent", routes = ["GET /v1/portforward"], auth = "apikey", apikey = "myapikey" }
]Згенеруйте ключ за допомогою docker run --rm qmcgaw/gluetun:v3.41.3 genkey і передавайте його в заголовку X-API-Key. HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE визначає роль за замовчуванням як одну JSON-кодовану змінну середовища для всіх маршрутів, які не охоплюють ролі у файлі. Після визначення будь-якої ролі v3.41.3 припиняє застосовувати вбудовану роль public. Тому для кожного наступного виклику маршруту потрібна або роль, у якій цей маршрут зазначено, або налаштована роль за замовчуванням. Якщо не визначено жодної ролі, вбудована роль public також охоплює PUT /v1/vpn/status. Отже, публікація порту 8000 без налаштування автентифікації дає кожному, хто має до нього доступ, можливість керувати станом VPN. Заздалегідь визначте, наскільки далеко має бути доступний цей порт, коли налаштовуєте доступ до gluetun із хоста та інших контейнерів.
Вибирайте команду up, коли клієнт має API, яким можна керувати одним викликом wget. Вона виконується рівно один раз для кожної події та не потребує постійного процесу. Використовуйте зовнішній процес, коли клієнту потрібні процедура входу, перезапис конфігураційного файлу або перезапуск. У arr stack за одним контейнером gluetun це зазвичай один невеликий poller, оскільки порт потрібен лише torrent client.
Пастка: спільний network namespace не встановлює порт прослуховування
Ця помилка забирає найбільше часу. network_mode: "service:gluetun" розміщує клієнт у network namespace gluetun, тому клієнт отримує VPN-адресу, маршрути тунелю та правила firewall gluetun. Жоден із цих параметрів не встановлює порт прослуховування клієнта. Gluetun відкриває перенаправлений порт на VPN-інтерфейсі. Пакети для цього порту надходять у namespace. Якщо клієнт прослуховує інший порт, kernel не має процесу, якому можна передати ці пакети. З’єднання відхиляється або завершується тайм-аутом, хоча всі перевірки вихідного трафіку проходять успішно. Перенаправлений порт і порт прослуховування клієнта — це два окремі номери. Увімкнути однакове значення для них — основне завдання.
Порівняйте їх, а не вгадуйте. Обидві команди виконуються в тому самому namespace:
docker exec gluetun cat /tmp/gluetun/forwarded_port
docker exec gluetun wget -qO- http://127.0.0.1:8080/api/v2/app/preferences | grep -o '"listen_port":[0-9]*'Ще один параметр може спрямувати діагностику в неправильний бік. VPN_PORT_FORWARDING_LISTENING_PORT перенаправляє вхідний трафік із перенаправленого порту на фіксований локальний порт за допомогою iptables. Upstream не рекомендує використовувати його з torrent-клієнтами, оскільки клієнт повідомляє tracker-ам і пірам власний порт прослуховування. Через це swarm отримує неправильний номер порту.
Як довести, що перенаправлений порт доступний
Власний індикатор підключення клієнта відображає вихідні підключення до трекерів. Тому він може показувати зелений стан, навіть якщо вхідні підключення до вас неможливі. Виконайте перевірку за допомогою керованого вами слухача з мережі поза тунелем. Upstream публікує для цього невеликий інструмент. Спочатку зупиніть torrent client, оскільки два процеси не можуть прив’язати один і той самий порт.
docker stop qbittorrent
docker exec -it gluetun /bin/shУсередині контейнера замініть amd64 на значення для вашої архітектури CPU, а 4567 — на перенаправлений порт:
wget -qO port-checker https://github.com/qdm12/port-checker/releases/download/v0.4.0/port-checker_0.4.0_linux_amd64
chmod +x port-checker
./port-checker --listening-address=":4567"Тепер визначте адресу виходу, яку використовує gluetun. Відповідь має формат JSON, а адреса міститься в полі public_ip.
curl -s http://127.0.0.1:8000/v1/publicip/ipЦей запит без облікових даних працює у трьох випадках: v3.41.3 запущено без конфігурації автентифікації, і доступ дозволяє вбудована роль public; конфігурація автентифікації містить GET /v1/publicip/ip у ролі з auth = "none"; або використовується HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE='{"auth":"none"}', якщо жодна роль у файлі не охоплює цей маршрут. В upstream-документації none означає, що автентифікація не потрібна. Якщо замість цього ви визначили роль apikey, як у варіанті 2, додайте GET /v1/publicip/ip до її routes і передайте її ключ, наприклад curl -s -H "X-API-Key: myapikey" http://127.0.0.1:8000/v1/publicip/ip.
Відкрийте http://<that address>:4567 з пристрою, який не підключений до тієї самої VPN. Для цього підійде телефон із мобільним інтернетом. Сторінка, яка показує IP-адресу та user agent вашого браузера, разом із відповідним записом запиту в журналі port-checker означає, що вхідний TCP-трафік досягає namespace. Тайм-аут означає, що він не досягає namespace, а причина виникає на рівні вище за клієнт. Зупиніть інструмент за допомогою CTRL+C, вийдіть із shell командою exit і знову запустіть клієнт. Ця перевірка охоплює лише TCP. Трафік DHT (distributed hash table) і uTP використовує UDP на тому самому номері порту, але ця перевірка його не охоплює.
Типові причини збоїв і повідомлення, які ви побачите
У журналі взагалі немає рядка про порт. Жоден компонент не запитував порт. Переконайтеся, що змінна фактично передалася в контейнер, за допомогою docker exec gluetun printenv | grep PORT_FORWARDING. Поширена причина — змінну задано не в тому сервісі compose.
Gluetun не запускається та повідомляє про помилку провайдера. Значення VPN_PORT_FORWARDING_PROVIDER перевіряється за чотирма підтримуваними назвами. Тому помилка в написанні зупиняє контейнер, а не дає йому непомітно працювати без port forwarding.
У журналі зазначено no port forwarded. Gluetun надіслав запит, але провайдер не повернув результату. Для ProtonVPN це зазвичай означає, що NAT-PMP не було ввімкнено в згенерованій конфігурації або тарифний план не підтримує port forwarding. Для Private Internet Access це зазвичай означає, що вибраний сервер не підтримує цю функцію.
Порт отримано, але підключення не встановлюється. Порівняйте forwarded port із listening port клієнта за допомогою двох наведених вище команд. Якщо вони збігаються, перевірте, чи клієнт прив’язаний до tunnel interface і чи вимкнено його опцію random port. Ця опція змінює listening port під час кожного запуску.
Команда up, схоже, нічого не робить. Виконайте точну команду всередині контейнера, щоб побачити помилку: docker exec gluetun /bin/sh -c '<your command>'. Зазвичай результатом буде curl: not found, оскільки image містить лише wget.
401 Unauthorized від control server. Жодна role не охоплює маршрут, до якого ви звертаєтеся, або всі відповідні role відхиляють запит через відсутні чи неправильні облікові дані. Налаштований HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE охоплює маршрути, не перелічені у файлі. Кожен маршрут записується як method і path, наприклад GET /v1/portforward. Якщо записати лише /v1/portforward, це не призведе до відповіді 401: gluetun завершить роботу під час запуску.
Після кожного перезапуску Private Internet Access використовує інший порт. Додайте bind mount для /gluetun, щоб збережений стан порту зберігався після перезапуску. Без цього volume gluetun щоразу запитує новий порт.
FAQ
Чому мої torrent завантажуються, але вхідні з’єднання не встановлюються?
Без перенаправленого порту VPN provider не має NAT rule, яка надсилає вхідні пакети на будь-який порт у ваш тунель, тому з’єднання, ініційовані не вами, відкидаються на exit address. Завантаження все одно працюють, оскільки ваш клієнт сам відкриває ці з’єднання і може підключитися до будь-якого доступного peer. Роздача та приєднання до swarm погіршуються, оскільки обидві функції залежать від можливості інших користувачів підключитися до вас. Потрібен provider, який підтримує port forwarding, VPN_PORT_FORWARDING=on у gluetun, а також застосування отриманого порту як listening port клієнта.
Чи працює gluetun із port forwarding будь-якого VPN provider?
Ні. Gluetun v3.41.3 має вбудовану інтеграцію з чотирма provider: Private Internet Access, ProtonVPN, Perfect Privacy і PrivateVPN. Будь-який provider поза цим списком не проходить перевірку для VPN_PORT_FORWARDING_PROVIDER, і контейнер зупиняється під час запуску. Якщо ваш provider видає статичний порт через власну панель керування, gluetun не може запитати його для вас, але FIREWALL_VPN_INPUT_PORTS пропустить цей фіксований порт через firewall gluetun. Політики provider змінюються, тому перед придбанням плану перевірте актуальну сторінку provider.
Чи потрібно оновлювати порт після кожного повторного підключення?
Так, і це оновлення має виконуватися автоматично. Перенаправлений порт належить VPN-сесії, тому перезапуск контейнера, зміна сервера або невдале поновлення lease можуть призвести до отримання нового номера, тоді як клієнт зберігатиме старий порт у власній конфігурації. Дозвольте gluetun передати його за допомогою VPN_PORT_FORWARDING_UP_COMMAND, що запускається одразу після активації forwarding, або запустіть невеликий процес, який читає GET /v1/portforward із control server і записує це значення в клієнт через його API.
Як перевірити, що перенаправлений порт справді відкритий?
Запустіть listener на цьому самому порту в network namespace gluetun і підключіться до нього з-поза VPN. Спочатку зупиніть torrent client, щоб звільнити порт, потім запустіть upstream binary port-checker всередині контейнера gluetun за допомогою --listening-address=":<port>". Отримайте exit address із curl -s http://127.0.0.1:8000/v1/publicip/ip, додавши -H "X-API-Key: <key>", якщо роль із GET /v1/publicip/ip використовує auth = "apikey", і відкрийте http://<address>:<port> з телефона через мобільний інтернет. Поява запиту в журналі port-checker доводить, що вхідний TCP досягає контейнера. Тайм-аут означає, що цього не відбувається, незалежно від того, що показує власний індикатор стану клієнта.