SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

GluetunでTorrentアプリのポート転送を設定する方法

ダウンロードできるのに外部接続がない原因を解説します。Gluetunのポート転送を設定し、再接続のたびに新しいポートをTorrentクライアントへ反映して確認する手順です。

ポート転送なしでは外部から接続できない理由

Gluetun のポート転送は、VPN プロバイダーに対して、出口アドレス上の公開ポートをコンテナへ転送するよう要求します。これは、別のピアが torrent クライアントへの接続を開始するための唯一の方法です。その転送がなければ、トンネルは正常で、ダウンロードも実行されますが、外部から接続が開始されることはありません。確立する接続はすべて、クライアント側から先に開始したものです。

この仕組みは NAT(network address translation)です。コンテナは、他の多数の顧客とプロバイダーの出口アドレスを共有します。クライアントが外部への接続を開くと、プロバイダーはその通信フローを記録し、応答をトンネル経由で返します。外部のピアが内向きに接続しても、対応する記録済みのフローがないため、パケットは出口アドレスまで到達した時点で破棄されます。クライアント自身が接続を受け付けられるすべてのピアには接続できるため、ダウンロードは完了し、この問題は見えにくいままです。問題が現れるのはシード時です。シーダーとは、他のユーザーから接続されるマシンだからです。

受信ポートを開くと、2 つの点が変わります。自分からの接続を受け付けられないピアも接続できるため、スウォームにより早く参加できます。また、それらのピアへアップロードできるようになります。

VPN プロバイダーの多くがポート転送を提供しない理由

ポート転送は、共有アドレス上の限られたリソースです。プロバイダーは、1 つの出口 IP の 1 つのポート番号を 1 人の顧客に割り当て、そのポートで顧客が行う通信に対応します。大手プロバイダーのいくつかは、この機能を廃止し、理由として不正利用への対応を挙げています。サポートの有無は、単純なチェック項目ではなく、条件を確認する質問として扱ってください。現在ポート転送を提供しているか、自分のプランで利用できるか、実際に選択できるサーバーで利用できるかを確認します。

ポート転送を利用できる場合でも、ポートは動的です。ポートはアカウントではなく VPN セッションに割り当てられるため、再接続するたびに番号が変わることがあります。Private Internet Access は、gluetun が更新する署名付きポートを発行します。上流のドキュメントによると、/gluetun ディレクトリを bind mount して状態を再起動後も保持すれば、同じポートを 60 日間使用できます。ProtonVPN は、NAT-PMP (NAT port mapping protocol) を介してランダムなポートを短期間のリースで割り当てます。このリースは継続的に更新する必要があります。そのため、クライアントでポートを 1 回設定しただけでは、継続して機能しません。

gluetun がポートを要求できるプロバイダー

gluetun v3.41.3(2026 年 7 月 30 日リリース)時点で、組み込み連携が検証するプロバイダー名は Private Internet Access、ProtonVPN、Perfect Privacy、PrivateVPN の 4 つです。VPN_PORT_FORWARDING=on で有効にします。デフォルト値は off です。古いガイドでは PORT_FORWARDING または PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING が使われています。どちらも後方互換用の名前としてこのバージョンで引き続き動作しますが、いずれも廃止予定です。

要求が成功するかどうかは、プロバイダー側の 2 つの条件で決まります。ProtonVPN では有料プランが必要です。また、NAT-PMP を有効にする必要があります。WireGuard 設定を生成するときに VPN オプションで NAT-PMP (Port Forwarding) を有効にするか、OpenVPN を使う場合はユーザー名に +pmp を追加します。Private Internet Access の OpenVPN には PORT_FORWARD_ONLY があります。これにより、ポートフォワーディングに対応するサーバーだけが選択対象になるため、対応していないサーバーに接続されることを防げます。WireGuard と OpenVPN ではポートの要求方法が異なるため、選択する前にプロバイダーのページを確認してください。

組み込みプロバイダーではなくカスタム設定で gluetun を実行する場合、VPN_PORT_FORWARDING_PROVIDER に gluetun が呼び出す API を指定します。Private Internet Access の上流ページでは、この変数と VPN_PORT_FORWARDING_USERNAME および VPN_PORT_FORWARDING_PASSWORD を組み合わせています。これらには、ポート要求に必要なアカウント認証情報を指定します。

Docker Compose で gluetun のポートフォワーディングを有効にする

ここでは、トンネルがすでに動作していることを前提とします。動作していない場合は、まず 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 の Secret 用 env ファイルを使用して、秘密鍵を compose ファイルに記載しないでください。

Gluetun が転送ポートを書き込む場所

Gluetun はポートを 3 か所で公開し、いずれにも同じ値が入ります。

取得するたびに、ポートを 1 回ログに記録します。行は 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 です。ファイルには 1 行につき 1 つのポートが入り、mode 0644 で書き込まれ、コンテナの PUID と PGID に chown されます。転送を停止すると、gluetun はファイルを削除せずに内容を消去します。そのため、利用側はファイルがない状態に遭遇せず、空のファイルを読み取れます。

docker exec gluetun cat /tmp/gluetun/forwarded_port

コントロールサーバーでも値を提供します。コントロールサーバーはデフォルトで :8000 で待ち受け、HTTP_CONTROL_SERVER_ADDRESS で設定します。

curl -s http://127.0.0.1:8000/v1/portforward
{"port":45678,"ports":[45678]}

Gluetun は VPN インターフェース上の自身のファイアウォールでも、そのポートを開きます。そのため、ネイティブ統合が処理する場合は FIREWALL_VPN_INPUT_PORTS は不要です。この変数は別のケースを対象にしています。プロバイダーに gluetun が問い合わせできず、帯域外で静的ポートを割り当てられ、それを手動で許可する必要がある場合です。

3 つの方法のうち、永続的なのは 1 つだけで、残り 2 つは永続的ではありません。upstream のドキュメントでは、ステータスファイルは v4.0.0 で deprecated とされています。また、GET /v1/openvpn/portforwarded はすでに 301 Moved Permanently を返し、/v1/portforward を指しています。新しい処理では、コントロールサーバーを読み取ってください。

再接続のたびにクライアントへポートを通知する必要がある理由

Torrent クライアントは待ち受けポートを自身の設定に保存し、再起動後もその番号を使い続けます。転送されるポートは VPN セッションの属性です。再接続後はこの2つの番号が一致しなくなるため、プロバイダーは何も待ち受けていないポートへ転送し、クライアントは何も転送されていないポートで待ち受けます。再接続は珍しくありません。コンテナの再起動、サーバーの変更、切断されたトンネルを gluetun のヘルスチェックが再起動する場合、またはリースを更新できなかった場合に発生します。その結果、昨日までは到達可能だった構成が、どちらのログにもエラーを残さないまま、今日は到達不能になります。

そのため、gluetun がポートを取得した時点で、そのポートを適用する必要があります。接続方法は2つあり、どのプロセスが処理を担うかが異なります。

オプション 1: up コマンドで gluetun がポートを設定する

VPN_PORT_FORWARDING_UP_COMMANDはポートフォワーディングが開始されたときに実行され、VPN_PORT_FORWARDING_DOWN_COMMANDは停止したときに実行されます。Gluetun はコマンドを実行する前に、{{PORT}}(最初のポート)、{{PORTS}}(すべてのポートをカンマ区切りにした値)、{{VPN_INTERFACE}}(トンネルインターフェース名。デフォルトは tun0)を置き換えます。Shell 構文を使う場合は、明示的な /bin/sh -c ラッパーが必要です。以下は、upstream の qBittorrent の例を compose の環境変数エントリとして 2 つに分けたものです。

      - 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 をトンネルにバインドします。random_portを false にすると、次回の起動時に qBittorrent が独自のポートを選択しなくなります。upnpを false にすると、存在しないルーター経由でポートをマッピングしようとしなくなります。

この方法には 2 つの要件があります。qBittorrent の Web UI を有効にし、ポート 8080 で待ち受ける必要があります。また、gluetun のネットワーク名前空間を共有することで、gluetun コンテナ内から 127.0.0.1:8080 に応答できるようになります。さらに、Bypass authentication for clients on localhost(bypass_local_auth)を有効にする必要があります。このコマンドは認証情報を送信しないためです。切断後に qBittorrent が必ずしもポートを再確立しないため、down コマンドも必要です。

このコマンドは、Alpine ベースで wgetを同梱する gluetun コンテナ内で実行されます。このイメージには curl がありません。イメージに存在しないバイナリを指定したコマンドは、ポートフォワーディングが開始されるたびに必ず失敗します。

オプション 2: gluetun の外部にあるプロセスがポートを読み取る

もう 1 つの構成では、gluetun の横で小さなプロセスを実行し、ポートを取得してクライアント自身の API 経由でクライアントに渡します。control server から読み取る場合は、次のようにします。

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

プロセスからファイルを参照できる場合は、ファイルを読み取ることもできます。/tmp/gluetun/forwarded_port は gluetun コンテナ内にあるため、sidecar には両方のコンテナで /tmp/gluetun にマウントした共有ボリュームが必要です。または、すでにマウントしているボリューム内のパスを VPN_PORT_FORWARDING_STATUS_FILE に指定します。

ここでは認証が重要です。v3.41.3 では、GET /v1/portforward の route は public というデフォルト role に属し、auth = "none" が設定されているため、認証情報なしで応答します。また、gluetun は route GET /v1/portforward is unprotected by default, please set up authentication で始まる警告をログに出力します。上流では後のリリースでこの経路を閉じる予定です。現在の control server のドキュメントでも、すべての route はデフォルトで private と説明されています。次のように、/gluetun/auth/config.toml に bind mount するファイルで role を今のうちに定義します。

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

docker run --rm qmcgaw/gluetun:v3.41.3 genkey で key を生成し、X-API-Key header に指定して送信します。HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE は、ファイル内の role で対象になっていないすべての route に対するデフォルト role を、JSON でエンコードした 1 つの環境変数として定義します。role を 1 つでも定義すると、v3.41.3 は組み込みの public role を適用しなくなります。そのため、その後に呼び出すすべての route には、対象 route を列挙した role か、設定したデフォルト role が必要です。role をまったく定義しない場合、この組み込みの public role は PUT /v1/vpn/status も対象にします。したがって、認証設定なしで公開した port 8000 に到達できるユーザーは、VPN の状態を制御できます。ホストや他のコンテナから gluetun に接続する方法を確認し、どこまで到達可能にするかを意図的に決めてください。

クライアントが 1 回の wget 呼び出しで操作できる API を公開している場合は、up command を選択してください。イベントごとに正確に 1 回だけ実行され、常駐プロセスも不要です。クライアントにログイン処理、設定ファイルの書き換え、再起動が必要な場合は、外部プロセスを選択します。1 つの gluetun コンテナの背後に arr stack を置く構成では、通常、必要な torrent client が 1 つだけなので、小さな poller 1 つにまとめられます。

落とし穴: namespace を共有しても待ち受けポートは設定されません

この問題では、原因の特定に最も時間がかかります。network_mode: "service:gluetun" はクライアントを gluetun の network namespace に配置するため、VPN アドレス、トンネルのルート、gluetun のファイアウォールルールを使用します。ただし、これらによってクライアントの待ち受けポートが設定されるわけではありません。gluetun は VPN インターフェース上で転送ポートを開き、そのポート宛てのパケットは namespace に到達します。クライアントが別のポートで待ち受けている場合、カーネルにはパケットの配送先がありません。すべての送信接続の確認が正常でも、接続は拒否されるかタイムアウトします。転送ポートとクライアントの待ち受けポートは別々の番号であり、両者を一致させることが必要です。

推測せず、両者を比較してください。以下の2つのコマンドは同じ 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]*'

もう1つの設定も、誤った方向へ切り分けを進める原因になります。VPN_PORT_FORWARDING_LISTENING_PORT は、iptables を使用して転送ポート宛ての受信トラフィックを固定されたローカルポートへ転送します。Upstream は、torrent クライアントではこの設定を使用しないよう案内しています。クライアントは自身の待ち受けポートを trackers と peers に通知するため、swarm に誤ったポート番号が伝わるからです。

転送ポートに到達できることを確認する方法

クライアント自身の接続インジケーターは、外向きの tracker 接続を示します。そのため、何もこちらに到達できない状態でも緑色に見えることがあります。トンネル外のネットワークから、自分で管理する listener を使ってテストします。Upstream はこのための小さなツールを公開しています。2 つのプロセスは同じポートを bind できないため、最初に torrent client を停止してください。

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

container 内で、amd64 を使用している CPU architecture に、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 が使用している exit address を確認します。応答は JSON 形式で、アドレスは public_ip フィールドに含まれています。

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

この認証情報なしのリクエストが応答するのは、次の 3 つの場合です。v3.41.3 が認証設定なしで動作しており、組み込みの public role が対象を許可している場合、認証設定である role に GET /v1/publicip/ip が記載され、auth = "none" が設定されている場合、または HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE='{"auth":"none"}' が設定されており、ファイル内のどの role もその route を対象としていない場合です。Upstream のドキュメントでは、none を認証不要として定義しています。代わりに Option 2 のように apikey role を定義した場合は、その role の routes に GET /v1/publicip/ip を追加し、その key を送信します。たとえば curl -s -H "X-API-Key: myapikey" http://127.0.0.1:8000/v1/publicip/ip のように指定します。

同じ VPN に接続していない device から http://<that address>:4567 を開きます。モバイルデータ通信中の phone で構いません。browser の IP address と user agent を示すページが表示され、port-checker に対応するリクエストが記録されていれば、inbound TCP は namespace に到達しています。timeout になる場合は到達しておらず、原因は client より上流にあります。CTRL+C で tool を停止し、exit で shell を終了してから、client を再起動します。この確認でテストできるのは TCP のみです。DHT (distributed hash table) と uTP の traffic は同じポート番号で UDP を使用しますが、このテストの対象外です。

失敗するパターンと表示される文字列

ログにポート行がまったくない。 ポートを要求する処理が実行されていません。変数を誤った compose サービスに設定していることがよくあるため、docker exec gluetun printenv | grep PORT_FORWARDING でその変数が実際にコンテナへ渡っていることを確認します。

Gluetun が起動せず、provider についてエラーを表示する。 VPN_PORT_FORWARDING_PROVIDER はサポート対象の4つの名前と照合されます。スペルミスがあると、ポート転送なしで処理を続けるのではなく、コンテナが停止します。

ログに no port forwarded と表示される。 Gluetun が要求したものの、provider から応答がありません。ProtonVPN では通常、生成した設定で NAT-PMP が有効になっていないか、契約プランにポート転送が含まれていないことを意味します。Private Internet Access では通常、選択したサーバーがポート転送に対応していないことを意味します。

ポートは取得できるが、接続を受け付けない。 上記の2つのコマンドを使い、転送されたポートとクライアントの待ち受けポートを比較します。一致している場合は、クライアントがトンネルインターフェースにバインドされていることと、ランダムポートのオプションが無効であることを確認します。このオプションを有効にすると、起動するたびに待ち受けポートが書き換えられます。

up コマンドを実行しても何も起きないように見える。 コンテナ内で正確なコマンドを実行し、エラーを確認します。docker exec gluetun /bin/sh -c '<your command>'。通常は curl: not found になります。イメージに含まれているのは wget だけだからです。

制御サーバーから 401 Unauthorized が返る。 呼び出しているルートを担当する role がないか、該当するすべての role が認証情報の欠落または誤りによってリクエストを拒否しています。設定済みの HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE は、ファイルに記載されていないルートを対象にします。各ルートは、GET /v1/portforward のように method と path の組み合わせで記述します。/v1/portforward だけでルートを記述しても 401 にはなりません。代わりに、gluetun は起動時に失敗します。

Private Internet Access で再起動するたびに別のポートになる。 /gluetun を bind mount し、保存されたポートの状態を再起動後も保持します。この volume がない場合、gluetun は毎回新しいポートを要求します。

FAQ

トレントはダウンロードできますが、着信接続を受けられないのはなぜですか?

転送ポートがない場合、VPN provider にはトンネル宛ての任意のポートに着信パケットを送る NAT ルールがないため、exit address で自分から開始していない接続は破棄されます。client 自身が接続を開始するためダウンロードは引き続き動作し、接続可能な peer には到達できます。シードと swarm への参加は、他のユーザーから接続される必要があるため影響を受けます。解決策は、port forwarding に対応した provider を使用し、gluetun で VPN_PORT_FORWARDING=on を設定し、その結果得られたポートを client の listening port に適用することです。

gluetun は、どの VPN provider の port forwarding でも使用できますか?

いいえ。gluetun v3.41.3 には、Private Internet Access、ProtonVPN、Perfect Privacy、PrivateVPN の4つの provider とのネイティブ統合があります。この一覧にない provider は VPN_PORT_FORWARDING_PROVIDER の検証に失敗し、コンテナは起動時に停止します。provider が独自の control panel で static port を発行する場合、gluetun がそのポートを代わりに要求することはできません。ただし、FIREWALL_VPN_INPUT_PORTS により、その固定ポートを gluetun の firewall 経由で許可できます。provider のポリシーは変更されるため、プランを購入する前に現在の provider ページを確認してください。

reconnect のたびにポートを更新する必要がありますか?

はい。この更新は自動で行われるようにしてください。転送ポートは VPN session に属するため、コンテナの再起動、server の変更、または lease renewal の失敗によって新しい番号が割り当てられることがあります。一方、client は自身の設定に保存されたポートを使い続けます。VPN_PORT_FORWARDING_UP_COMMAND により gluetun からポートを渡す方法があります。これは forwarding が開始した時点で実行されます。または、control server から GET /v1/portforward を読み取り、API 経由でその値を client に書き込む小さなプロセスを実行します。

転送ポートが実際に開いていることを確認するにはどうすればよいですか?

gluetun の network namespace 内で、その正確なポートを listen するプロセスを実行し、VPN の外部から接続します。まず torrent client を停止してポートを空けます。次に、--listening-address=":<port>" を指定して upstream port-checker binary を gluetun コンテナ内で実行します。curl -s http://127.0.0.1:8000/v1/publicip/ip から exit address を取得します。GET /v1/publicip/ip を一覧表示する role が auth = "apikey" を使用する場合は -H "X-API-Key: <key>" を追加し、mobile data を使用している phone から http://<address>:<port> を開きます。port-checker の log に request が記録されれば、着信 TCP が到達したことを確認できます。timeout になる場合は、client 自身の status icon に何が表示されていても、着信 TCP は到達していません。

この記事は役に立ちましたか?