Gluetun port forwarding: konfiguracja dla torrentów

Dlaczego połączenia przychodzące nie działają bez przekierowania portów

Funkcja port forwarding w Gluetun wysyła do dostawcy VPN żądanie przypisania jednego publicznego portu na jego adresie wyjściowym do Twojego kontenera. Jest to jedyny sposób, aby inny uczestnik sieci mógł zainicjować połączenie z Twoim klientem torrent. Bez tego mapowania tunel działa poprawnie, pobieranie plików przebiega bez zakłóceń, ale żadne połączenie przychodzące nie zostanie nawiązane. Każde działające połączenie jest wynikiem inicjatywy Twojego klienta.

Mechanizm ten opiera się na NAT (network address translation). Twój kontener współdzieli adres wyjściowy dostawcy z wieloma innymi użytkownikami. Gdy klient otwiera połączenie wychodzące, dostawca rejestruje ten przepływ i przesyła odpowiedzi z powrotem przez tunel. Połączenie przychodzące od nieznanego uczestnika nie pasuje do żadnego zarejestrowanego przepływu, więc pakiet dociera do adresu wyjściowego i jest tam odrzucany. Twój klient nadal łączy się z każdym uczestnikiem, który sam jest dostępny, więc pobieranie kończy się sukcesem, a problem pozostaje niewidoczny. Problem ujawnia się podczas udostępniania (seeding), ponieważ osoba udostępniająca to maszyna, z którą łączą się inni.

Otwarty port przychodzący zmienia dwie rzeczy. Dołączasz do roju (swarm) szybciej, ponieważ uczestnicy, którzy sami nie mogą przyjmować połączeń, mogą teraz połączyć się z Tobą, a Ty możesz przesyłać dane do tych użytkowników.

Dlaczego większość dostawców VPN nie oferuje przekierowania portów

Przekierowany port jest zasobem deficytowym w przypadku współdzielonego adresu IP. Dostawca rezerwuje jeden numer portu na jednym wyjściowym adresie IP dla jednego klienta, a następnie odpowiada za wszelkie działania, które klient z nim podejmuje. Kilku dużych dostawców usunęło tę funkcję, wskazując jako powód trudności w obsłudze nadużyć. Należy traktować wsparcie dla tej funkcji jako kwestię kategorii, a nie prostego pola wyboru: należy zapytać, czy dostawca oferuje przekierowanie portów w aktualnej ofercie, w wybranym planie oraz na serwerach, z których faktycznie można korzystać.

Tam, gdzie przekierowanie istnieje, port jest dynamiczny. Jest on przypisany do sesji VPN, a nie do konta użytkownika, dlatego po każdym ponownym połączeniu numer może być inny. Private Internet Access wydaje podpisany port, który gluetun odświeża, a dokumentacja dostawcy wskazuje, że ten sam port jest utrzymywany przez 60 dni, pod warunkiem zamontowania katalogu /gluetun, co pozwala zachować stan po restarcie. ProtonVPN przypisuje losowy port za pośrednictwem NAT-PMP (NAT port mapping protocol) na krótki czas dzierżawy, który musi być stale odnawiany. Z tego powodu jednorazowa konfiguracja portu w kliencie nigdy nie działa trwale.

Dostawcy, od których gluetun może uzyskać port

W wersji gluetun v3.41.3, wydanej 30 lipca 2026, natywna integracja obsługuje cztery nazwy dostawców: Private Internet Access, ProtonVPN, Perfect Privacy oraz PrivateVPN. Funkcję tę włącza się za pomocą VPN_PORT_FORWARDING=on, co jest ustawieniem domyślnym off. Starsze poradniki wykorzystują PORT_FORWARDING lub PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING. Obie te nazwy działają w tej wersji jako elementy wstecznie kompatybilne, jednak są sukcesywnie wycofywane.

Dwa szczegóły dotyczące dostawcy decydują o tym, czy żądanie może zakończyć się powodzeniem. ProtonVPN wymaga płatnego planu oraz włączonej funkcji NAT-PMP: należy aktywować NAT-PMP (Port Forwarding) w opcjach VPN podczas generowania konfiguracji WireGuard lub dodać +pmp do nazwy użytkownika w przypadku korzystania z OpenVPN. Private Internet Access w protokole OpenVPN posiada PORT_FORWARD_ONLY, co ogranicza wybór serwerów wyłącznie do tych wspierających przekierowanie portów, dzięki czemu nie nastąpi połączenie z serwerem, który go nie obsługuje. WireGuard i OpenVPN różnią się sposobem żądania portu, dlatego przed dokonaniem wyboru należy zapoznać się ze stroną dostawcy.

Gdy gluetun korzysta z konfiguracji niestandardowej zamiast wbudowanego dostawcy, VPN_PORT_FORWARDING_PROVIDER określa nazwę API, z którym gluetun powinien się połączyć. Dokumentacja Private Internet Access powiązuje tę zmienną z VPN_PORT_FORWARDING_USERNAME oraz VPN_PORT_FORWARDING_PASSWORD, które przechowują dane uwierzytelniające wymagane do żądania portu.

Włączanie przekierowania portów gluetun w docker compose

Poniższa procedura zakłada, że tunel działa poprawnie. Jeśli tak nie jest, należy rozpocząć od kierowania ruchu kontenerów Docker przez gluetun i powrócić po uzyskaniu poprawnej łączności.

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

Należy przypiąć wersję obrazu (tag). qmcgaw/gluetun:latest podąża za gałęzią master, w której mechanizmy przekierowania portów zmieniają się w wersji v4, dlatego nieprzypięty obraz może zmienić zachowanie przy kolejnym docker compose pull. Klucz prywatny należy przechowywać poza plikiem compose, korzystając z pliku env dla sekretów compose.

Lokalizacja zapisu przekierowanego portu przez gluetun

Gluetun udostępnia numer portu w trzech miejscach, z których każde zawiera tę samą wartość.

Port jest logowany jednokrotnie przy każdym pozyskaniu. Wiersz logu zawiera port forwarded is 45678, natomiast no port forwarded pojawia się, gdy żądanie nie zwróciło żadnej wartości.

docker logs gluetun 2>&1 | grep -i "port forwarded"

Numer jest zapisywany do pliku określonego przez VPN_PORT_FORWARDING_STATUS_FILE, którego domyślna wartość to /tmp/gluetun/forwarded_port. Plik zawiera jeden port w wierszu, jest zapisywany z uprawnieniami 0644 oraz posiada zmienionego właściciela na PUID i PGID kontenera. Po zatrzymaniu przekierowania gluetun czyści zawartość pliku zamiast go usuwać, dzięki czemu aplikacja odczytująca może otrzymać pusty plik zamiast błędu braku pliku.

docker exec gluetun cat /tmp/gluetun/forwarded_port

Wartość jest udostępniana przez serwer sterujący, który domyślnie nasłuchuje na :8000, co jest konfigurowane za pomocą HTTP_CONTROL_SERVER_ADDRESS.

curl -s http://127.0.0.1:8000/v1/portforward

{"port":45678,"ports":[45678]}

Gluetun otwiera również ten port we własnej zaporze sieciowej na interfejsie VPN, więc FIREWALL_VPN_INPUT_PORTS nie jest wymagane, gdy natywna integracja wykonuje to zadanie. Ta zmienna dotyczy innego przypadku: dostawcy, którego gluetun nie może odpytać, gdzie statyczny port został przydzielony poza systemem i musi zostać otwarty ręcznie.

Jedna z tych trzech metod jest trwała, a dwie pozostałe nie. Dokumentacja upstream oznacza plik stanu jako przestarzały w wersji v4.0.0, a GET /v1/openvpn/portforwarded już teraz odpowiada za pomocą 301 Moved Permanently, wskazując na /v1/portforward. Nowe implementacje powinny odczytywać dane z serwera sterującego.

Dlaczego klient musi otrzymywać numer portu przy każdym ponownym połączeniu

Klient sieci torrent przechowuje numer portu nasłuchiwania w swojej konfiguracji i zachowuje go pomiędzy restartami. Przekierowany port jest natomiast właściwością sesji VPN. Po ponownym nawiązaniu połączenia wartości te stają się rozbieżne: dostawca mapuje port, na którym nic nie nasłuchuje, a klient nasłuchuje na porcie, który nie jest zmapowany. Ponowne połączenia nie są rzadkością: restart kontenera, zmiana serwera, zerwanie tunelu, które wymusza restart przez mechanizm kontroli stanu gluetun, czy wygaśnięcie dzierżawy, której nie udało się odnowić. Skutkuje to konfiguracją, która była dostępna wczoraj, a dziś jest po cichu niedostępna, bez żadnego błędu w logach obu komponentów.

Dlatego port musi być stosowany w momencie, gdy gluetun go uzyskuje. Istnieją dwa sposoby na zrealizowanie tego połączenia, które różnią się tym, który proces wykonuje to zadanie.

Opcja 1: gluetun przekazuje port za pomocą polecenia up

VPN_PORT_FORWARDING_UP_COMMAND uruchamia się, gdy przekierowanie portów zostaje nawiązane, a VPN_PORT_FORWARDING_DOWN_COMMAND, gdy zostaje przerwane. Przed wykonaniem polecenia gluetun podstawia {{PORT}} (pierwszy port), {{PORTS}} (wszystkie porty rozdzielone przecinkami) oraz {{VPN_INTERFACE}} (nazwę interfejsu tunelu, domyślnie tun0). Składnia powłoki wymaga jawnego użycia otoczki /bin/sh -c. Poniżej znajduje się przykład dla qBittorrent, zapisany jako dwa wpisy środowiskowe w pliku 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'

Każde pole w tym wywołaniu pełni określoną funkcję. listen_port to nowy port. current_network_interface wiąże qBittorrent z tunelem. Ustawienie random_port na false zapobiega samodzielnemu wybieraniu portu przez qBittorrent przy kolejnym uruchomieniu. Ustawienie upnp na false wyłącza próbę mapowania portu przez router, który nie istnieje.

To podejście wymaga spełnienia dwóch warunków. Interfejs webowy qBittorrent musi odpowiadać na 127.0.0.1:8080 z wnętrza kontenera gluetun, co dzieje się automatycznie, gdy klient współdzieli przestrzeń nazw sieciowych gluetun. Ponadto Bypass authentication for clients on localhost (bypass_local_auth) musi być włączone, ponieważ polecenie nie przesyła żadnych danych uwierzytelniających. Polecenie down jest niezbędne, ponieważ qBittorrent nie zawsze przywraca port po rozłączeniu.

Polecenie jest wykonywane wewnątrz kontenera gluetun, który bazuje na Alpine i zawiera wget. W tym obrazie brakuje curl. Polecenie wskazujące na plik binarny, którego nie ma w obrazie, zakończy się niepowodzeniem przy każdej próbie nawiązania przekierowania.

Opcja 2: proces zewnętrzny względem gluetun odczytuje port

Drugi wzorzec zakłada uruchomienie niewielkiego procesu obok gluetun, który pobiera port i przekazuje go do klienta za pośrednictwem jego własnego API. Odczytaj go z serwera sterującego:

port=$(curl -s http://127.0.0.1:8000/v1/portforward | jq -r .port)

Można również odczytać plik, jeśli proces ma do niego dostęp. /tmp/gluetun/forwarded_port znajduje się wewnątrz kontenera gluetun, więc sidecar wymaga współdzielonego wolumenu zamontowanego w /tmp/gluetun w obu kontenerach, albo należy wskazać VPN_PORT_FORWARDING_STATUS_FILE na ścieżkę wewnątrz wolumenu, który jest już zamontowany.

Uwierzytelnianie jest tutaj istotne. W wersji v3.41.3 trasa GET /v1/portforward należy do domyślnej roli o nazwie public z auth = "none", więc odpowiada bez poświadczeń, a gluetun loguje ostrzeżenie zaczynające się od route GET /v1/portforward is unprotected by default, please set up authentication. Twórcy oprogramowania zamkną tę możliwość w przyszłym wydaniu. Zdefiniuj rolę już teraz w pliku zamontowanym w /gluetun/auth/config.toml:

roles = [
  { name = "qbittorrent", routes = ["GET /v1/portforward"], auth = "apikey", apikey = "myapikey" }
]

Wygeneruj klucz za pomocą docker run --rm qmcgaw/gluetun:v3.41.3 genkey i prześlij go w nagłówku X-API-Key. HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE wykonuje to samo zadanie co jedna zmienna środowiskowa zakodowana w JSON, jeśli wolisz nie montować pliku. Port 8000 opublikowany bez roli daje każdemu, kto ma do niego dostęp, kontrolę nad stanem VPN, więc podejmij świadomą decyzję o zasięgu dostępu, analizując jak uzyskać dostęp do gluetun z hosta i innych kontenerów.

Wybierz polecenie up, gdy klient udostępnia API, które można obsłużyć jednym wywołaniem wget, ponieważ uruchamia się ono dokładnie raz na zdarzenie i nie wymaga ciągłego działania. Wybierz proces zewnętrzny, gdy klient wymaga procesu logowania, nadpisania pliku konfiguracyjnego lub restartu. W stosie arr za jednym kontenerem gluetun zazwyczaj kończy się to na jednym małym procesie odpytującym, ponieważ tylko klient torrent dba o port.

Pułapka: współdzielenie przestrzeni nazw nie ustawia portu nasłuchiwania

Ten błąd powoduje największą stratę czasu. network_mode: "service:gluetun" umieszcza klienta w przestrzeni nazw sieciowej gluetun, dzięki czemu korzysta on z adresu VPN, tras tunelu oraz reguł zapory sieciowej gluetun. Żaden z tych elementów nie ustawia portu nasłuchiwania klienta. Gluetun otwiera przekierowany port na interfejsie VPN, pakiety docierają do przestrzeni nazw, ale jeśli klient nasłuchuje na innym porcie, jądro nie ma miejsca, do którego mogłoby je dostarczyć. Połączenie jest odrzucane lub przekracza czas oczekiwania, mimo że każda kontrola ruchu wychodzącego wskazuje na poprawne działanie. Przekierowany port oraz port nasłuchiwania klienta to dwie różne wartości, a zapewnienie ich zgodności jest kluczowym zadaniem.

Należy je porównać, zamiast zgadywać. Obie komendy są uruchamiane w tej samej przestrzeni nazw:

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]*'

Jeszcze jedno ustawienie wprowadza użytkowników w błąd. VPN_PORT_FORWARDING_LISTENING_PORT przekierowuje ruch przychodzący z przekierowanego portu na stały port lokalny przy użyciu iptables. Dostawca zaleca, aby nie używać tej opcji w klientach torrent, ponieważ klient ogłasza własny port nasłuchiwania trackerom i innym użytkownikom, przez co sieć otrzymuje błędny numer portu.

Jak sprawdzić, czy przekierowany port jest osiągalny

Wskaźnik połączenia w kliencie odzwierciedla wychodzące połączenia z trackerem, więc może być zielony, mimo że nikt nie może nawiązać połączenia z Twoim serwerem. Przeprowadź test za pomocą nasłuchującego procesu, nad którym masz kontrolę, z sieci znajdującej się poza tunelem. Dostawca VPN udostępnia w tym celu niewielkie narzędzie. Najpierw zatrzymaj klienta torrent, ponieważ dwa procesy nie mogą jednocześnie korzystać z tego samego portu.

docker stop qbittorrent
docker exec -it gluetun /bin/sh

Wewnątrz kontenera zmień amd64 na odpowiednią architekturę procesora, a 4567 na swój przekierowany port:

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"

Teraz znajdź adres wyjściowy używany przez gluetun. Odpowiedź jest w formacie JSON, a adres znajduje się w polu public_ip.

curl -s http://127.0.0.1:8000/v1/publicip/ip

Otwórz http://<that address>:4567 z urządzenia, które nie korzysta z tej samej sieci VPN. Telefon z włączoną transmisją danych komórkowych będzie odpowiedni. Strona wyświetlająca adres IP Twojej przeglądarki oraz user agent, przy jednoczesnym zarejestrowaniu żądania przez port-checker, oznacza, że ruch przychodzący TCP dociera do przestrzeni nazw. Przekroczenie czasu oczekiwania (timeout) oznacza, że ruch nie dociera, a przyczyna leży powyżej klienta. Zatrzymaj narzędzie za pomocą CTRL+C, opuść powłokę komendą exit i uruchom ponownie klienta. Ten test sprawdza wyłącznie protokół TCP. Ruch DHT (distributed hash table) oraz uTP wykorzystuje protokół UDP na tym samym numerze portu, czego ten test nie obejmuje.

Tryby awarii i komunikaty, które zobaczysz

Brak linii z portem w dzienniku. Żaden proces nie zażądał portu. Potwierdź, że zmienna faktycznie dotarła do kontenera za pomocą docker exec gluetun printenv | grep PORT_FORWARDING, ponieważ zmienna ustawiona w niewłaściwej usłudze w pliku compose jest częstą przyczyną problemów.

Gluetun odmawia startu i zgłasza błąd dostawcy. Wartość VPN_PORT_FORWARDING_PROVIDER jest weryfikowana pod kątem czterech obsługiwanych nazw, więc literówka zatrzymuje kontener, zamiast pozwalać mu działać po cichu bez przekierowania.

Dziennik zawiera komunikat no port forwarded. Gluetun wysłał zapytanie, ale dostawca nie zwrócił żadnej odpowiedzi. W przypadku ProtonVPN zazwyczaj oznacza to, że funkcja NAT-PMP nie została włączona w wygenerowanej konfiguracji lub posiadany plan nie obejmuje przekierowania portów. W przypadku Private Internet Access zazwyczaj oznacza to, że wybrany serwer nie oferuje tej funkcji.

Port został przydzielony, ale połączenia nie docierają. Porównaj przekierowany port z portem nasłuchiwania klienta, używając dwóch powyższych poleceń. Jeśli są zgodne, sprawdź, czy klient jest powiązany z interfejsem tunelu oraz czy opcja losowego portu jest wyłączona, ponieważ ta opcja zmienia port nasłuchiwania przy każdym uruchomieniu.

Polecenie up wydaje się nie działać. Uruchom dokładnie to polecenie wewnątrz kontenera, aby zobaczyć błąd: docker exec gluetun /bin/sh -c '<your command>'. Wynikiem jest zazwyczaj curl: not found, ponieważ obraz zawiera tylko wget.

Błąd 401 Unauthorized z serwera sterującego. Zdefiniowano konfigurację autoryzacji, a rola nie zawiera ścieżki, którą wywołujesz. Trasy są dopasowywane jako metoda oraz ścieżka, więc rola wymieniająca tylko /v1/portforward nie obejmuje GET /v1/portforward.

Różny port w Private Internet Access po każdym restarcie. Użyj bind mount dla /gluetun, aby zapisany stan portu przetrwał restart. Bez tego wolumenu gluetun za każdym razem żąda nowego portu.

FAQ

Dlaczego moje torrenty pobierają się, ale nie otrzymują połączeń przychodzących?

Bez przekierowanego portu dostawca VPN nie posiada reguły NAT, która przesyłałaby pakiety przychodzące na dowolny port do tunelu, więc połączenia, których użytkownik nie zainicjował, są odrzucane na adresie wyjściowym. Pobieranie nadal działa, ponieważ klient sam otwiera te połączenia i może połączyć się z każdym dostępnym partnerem. Udostępnianie (seeding) i dołączanie do roju (swarm) są utrudnione, ponieważ oba te procesy zależą od możliwości nawiązania połączenia z użytkownikiem przez inne osoby. Rozwiązaniem jest dostawca oferujący przekierowanie portów, konfiguracja VPN_PORT_FORWARDING=on w gluetun oraz zastosowanie uzyskanego portu jako portu nasłuchiwania klienta.

Czy gluetun współpracuje z przekierowaniem portów każdego dostawcy VPN?

Nie. Gluetun w wersji 3.41.3 posiada natywną integrację z czterema dostawcami: Private Internet Access, ProtonVPN, Perfect Privacy oraz PrivateVPN. Każdy dostawca spoza tej listy nie przejdzie walidacji dla VPN_PORT_FORWARDING_PROVIDER, a kontener zatrzyma się podczas uruchamiania. Jeśli dostawca przydziela statyczny port za pośrednictwem własnego panelu sterowania, gluetun nie może go automatycznie zażądać, ale FIREWALL_VPN_INPUT_PORTS pozwoli na przepuszczenie tego stałego portu przez zaporę sieciową gluetun. Zasady dostawców ulegają zmianom, dlatego przed zakupem planu należy sprawdzić aktualną stronę dostawcy.

Czy muszę aktualizować port po każdym ponownym połączeniu?

Tak, a aktualizacja ta powinna odbywać się automatycznie. Przekierowany port jest przypisany do sesji VPN, więc restart kontenera, zmiana serwera lub nieudane odnowienie dzierżawy mogą wygenerować nowy numer, podczas gdy klient zachowuje stary port w swojej konfiguracji. Należy pozwolić gluetun na przekazanie go za pomocą VPN_PORT_FORWARDING_UP_COMMAND, co następuje w momencie ustanowienia przekierowania, lub uruchomić niewielki proces, który odczytuje GET /v1/portforward z serwera sterującego i zapisuje wartość w kliencie poprzez jego API.

Jak sprawdzić, czy przekierowany port jest rzeczywiście otwarty?

Należy uruchomić proces nasłuchujący na tym konkretnym porcie wewnątrz przestrzeni nazw sieciowej gluetun i połączyć się z nim spoza sieci VPN. Najpierw należy zatrzymać klienta torrent, aby zwolnić port, a następnie uruchomić binarny program sprawdzający porty wewnątrz kontenera gluetun za pomocą --listening-address=":<port>". Należy pobrać adres wyjściowy z curl -s http://127.0.0.1:8000/v1/publicip/ip i otworzyć http://<address>:<port> z telefonu korzystającego z transmisji danych mobilnych. Żądanie widoczne w dzienniku programu sprawdzającego porty potwierdza, że ruch TCP przychodzący dociera do celu. Przekroczenie czasu oczekiwania oznacza, że ruch nie dociera, niezależnie od tego, co wskazuje ikona statusu w kliencie.