From 5d42815000bffc1b08efd835836727d6a1f13ae4 Mon Sep 17 00:00:00 2001 From: Pawel Zmarzly Date: Sat, 1 Feb 2025 19:52:38 +0000 Subject: [PATCH 1/4] feat(vpn-port-forwarding): make documentation up-to-date --- setup/advanced/vpn-port-forwarding.md | 16 +++++++++++++--- setup/options/port-forwarding.md | 8 ++++++-- setup/providers/perfect-privacy.md | 2 +- setup/providers/private-internet-access.md | 5 ++--- setup/providers/privatevpn.md | 6 ++++-- 5 files changed, 26 insertions(+), 11 deletions(-) diff --git a/setup/advanced/vpn-port-forwarding.md b/setup/advanced/vpn-port-forwarding.md index c3eee64..6fdacff 100644 --- a/setup/advanced/vpn-port-forwarding.md +++ b/setup/advanced/vpn-port-forwarding.md @@ -6,10 +6,12 @@ ## Native integrations -VPN server side port forwarding is implemented natively into Gluetun for the following providers: +VPN server side port forwarding is currently implemented natively into Gluetun for the following providers: - **Private Internet Access**, [more information](../providers/private-internet-access.md) - **ProtonVPN**, [more information](../providers/protonvpn.md) +- **Perfect Privacy**, [more information](../providers/perfect-privacy.md) +- **PrivateVPN**, [more information](../providers/privatevpn.md) You can enable it with `VPN_PORT_FORWARDING=on`. The forwarded port can be accessed: @@ -36,16 +38,24 @@ Notes: ### qBittorrent example -`VPN_PORT_FORWARDING_UP_COMMAND=/bin/sh -c 'wget -O- --retry-connrefused --post-data "json={\"listen_port\":{{PORTS}}}" http://127.0.0.1:8080/api/v2/app/setPreferences 2>&1'` +`VPN_PORT_FORWARDING_UP_COMMAND=/bin/sh -c 'wget -O- --retry-connrefused --post-data "json={\"listen_port\":$(echo {{PORTS}} | cut -d, -f1),\"random_port\":false,\"upnp\":false}" http://127.0.0.1:8080/api/v2/app/setPreferences 2>&1'` For this to work, the qBittorrent web UI server must be enabled and listening on port `8080` and the Web UI "Bypass authentication for clients on localhost" must be ticked (json key `bypass_local_auth`) so Gluetun can reach qBittorrent without authentication. -Thanks to [@Marsu31](https://github.com/Marsu31) +### Transmission example + +Transmission API requires CSRF tokens, so check out [the `transmission-port-update.sh` script](https://github.com/qdm12/gluetun/pull/2611/files). ## Allow a forwarded port through the firewall For non-native integrations where you have a designated forwarded port from your VPN provider, you can allow it by adding it to the environment variable `FIREWALL_VPN_INPUT_PORTS`. +## Port redirection using iptables + +Gluetun supports setting up a redirection of incoming traffic from VPN opened port to a custom localhost port of your choosing, by using the `VPN_PORT_FORWARDING_LISTENING_PORT` environmental variable. Do not use this with torrent clients, or any other software that publicly announces its port, as that software wouldn't know what the publicly visible port is, and would be announcing the private port instead. + +For example, if you have a web server (nginx, caddy, apache) listening on port 80, you can set `VPN_PORT_FORWARDING_LISTENING_PORT=80` to expose it to the outside world on all available VPN server's public ports. + ## Test it Assuming: diff --git a/setup/options/port-forwarding.md b/setup/options/port-forwarding.md index 362b677..a65a81f 100644 --- a/setup/options/port-forwarding.md +++ b/setup/options/port-forwarding.md @@ -1,5 +1,7 @@ # VPN server port forwarding options +Read [the guide](../advanced/vpn-port-forwarding.md) for details. + ## Environment variables 💁 The following environment variables are all optional. @@ -7,6 +9,8 @@ | Variable | Default | Choices | Description | | --- | --- | --- | --- | | `VPN_PORT_FORWARDING` | `off` | `off` or `on` | Enable custom port forwarding code for supported providers | -| `VPN_PORT_FORWARDING_PROVIDER` | Current provider in use | `private internet access` | Choose the custom port forwarding code to use. This is useful when using the custom provider with Wireguard. For PIA, make sure you set `SERVER_NAMES=`. | +| `VPN_PORT_FORWARDING_PROVIDER` | Current provider in use | See [the list](../advanced/vpn-port-forwarding.md#native-integrations) | Choose the custom port forwarding code to use. This is useful when using the custom provider with Wireguard. For PIA, make sure you set `SERVER_NAMES=`. | | `VPN_PORT_FORWARDING_STATUS_FILE` | `/tmp/gluetun/forwarded_port` | Valid filepath | File path to use for writing the forwarded port obtained. | -| `VPN_PORT_FORWARDING_LISTENING_PORT` | | Valid port number | Port redirection for the VPN server side port forwarded. | +| `VPN_PORT_FORWARDING_LISTENING_PORT` | | Valid port number | Port redirection to redirect incoming traffic to. Do not use with torrent clients. | +| `VPN_PORT_FORWARDING_UP_COMMAND` | | Shell command | Command to run when port forwarding has finished setting up. | +| `VPN_PORT_FORWARDING_DOWN_COMMAND` | | Shell command | Command to run when port forwarding has finished tearing down. | diff --git a/setup/providers/perfect-privacy.md b/setup/providers/perfect-privacy.md index 2ea710c..e7db74d 100644 --- a/setup/providers/perfect-privacy.md +++ b/setup/providers/perfect-privacy.md @@ -39,7 +39,7 @@ services: ## VPN server port forwarding -Set `VPN_PORT_FORWARDING=on` and the 3 ports forwarded will be logged out as well as available via the http control server. +Set `VPN_PORT_FORWARDING=on` and the 3 ports forwarded will be logged out as well as available via the http control server. See [VPN server port forwarding setup page](../advanced/vpn-port-forwarding.md) for more details. ## Servers diff --git a/setup/providers/private-internet-access.md b/setup/providers/private-internet-access.md index cd68bdb..4044466 100644 --- a/setup/providers/private-internet-access.md +++ b/setup/providers/private-internet-access.md @@ -42,8 +42,7 @@ services: - `PORT_FORWARD_ONLY`: Set to `true` to select servers with port forwarding only - `PRIVATE_INTERNET_ACCESS_OPENVPN_ENCRYPTION_PRESET`: Encryption preset, defaulting to `strong`, which can be set to `normal`, `strong` or `none`. ⚠️ `none` disables the `cipher` and `auth` OpenVPN options. - `OPENVPN_ENDPOINT_PORT`: Custom OpenVPN server endpoint port -- `VPN_PORT_FORWARDING`: defaults to `off` and can be set to `on`to enable port forwarding on the VPN server -- `VPN_PORT_FORWARDING_STATUS_FILE`: File path to write the forwarded port number to. It defaults to `/tmp/gluetun/forwarded_port`. +- `VPN_PORT_FORWARDING`: defaults to `off` and can be set to `on` to enable port forwarding on the VPN server ## Wireguard @@ -72,7 +71,7 @@ From [@ddelange](https://github.com/ddelange) on issue [#464](https://github.com ### Setup -First refer to the [VPN server port forwarding setup page](../advanced/vpn-port-forwarding.md#native-integrations). +Refer to the [VPN server port forwarding setup page](../advanced/vpn-port-forwarding.md). Once enabled, you will keep the same forwarded port for 60 days as long as you bind mount the `/gluetun` directory. It will be automatically refreshed. diff --git a/setup/providers/privatevpn.md b/setup/providers/privatevpn.md index 5a04d1f..25bebbc 100644 --- a/setup/providers/privatevpn.md +++ b/setup/providers/privatevpn.md @@ -2,7 +2,7 @@ ## TLDR -💁 To use with Wireguard, see [the custom provider Wireguard section](custom.md#wireguard). +💁 To use with Wireguard, see [the custom provider Wireguard section](custom.md#wireguard). You will need to use the IP address of the endpoint instead of the domain - see [discussion](https://github.com/qdm12/gluetun/issues/2680). For OpenVPN: @@ -44,7 +44,9 @@ services: ## VPN server port forwarding -Set `VPN_PORT_FORWARDING=on` and the port forwarded will be logged out as well as available via the http control server. +VPN server port forwarding is only supported on OpenVPN. If you try using it with Wireguard, PrivateVPN API will return `{"supported":false}` message, resulting in a "port forwarding not supported for this VPN server" error. + +Set `VPN_PORT_FORWARDING=on` and the port forwarded will be logged out as well as available via the http control server. See [VPN server port forwarding setup page](../advanced/vpn-port-forwarding.md) for more details. ## Servers From bdf7171f43d0ee94b7bd1b2f9b1cb9ed4850e22e Mon Sep 17 00:00:00 2001 From: Quentin McGaw Date: Thu, 13 Nov 2025 16:57:30 +0100 Subject: [PATCH 2/4] Apply suggestions from code review --- setup/advanced/vpn-port-forwarding.md | 4 ++-- setup/providers/private-internet-access.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/setup/advanced/vpn-port-forwarding.md b/setup/advanced/vpn-port-forwarding.md index 6fdacff..18cc951 100644 --- a/setup/advanced/vpn-port-forwarding.md +++ b/setup/advanced/vpn-port-forwarding.md @@ -6,7 +6,7 @@ ## Native integrations -VPN server side port forwarding is currently implemented natively into Gluetun for the following providers: +VPN server side port forwarding is implemented natively into Gluetun for the following providers: - **Private Internet Access**, [more information](../providers/private-internet-access.md) - **ProtonVPN**, [more information](../providers/protonvpn.md) @@ -52,7 +52,7 @@ For non-native integrations where you have a designated forwarded port from your ## Port redirection using iptables -Gluetun supports setting up a redirection of incoming traffic from VPN opened port to a custom localhost port of your choosing, by using the `VPN_PORT_FORWARDING_LISTENING_PORT` environmental variable. Do not use this with torrent clients, or any other software that publicly announces its port, as that software wouldn't know what the publicly visible port is, and would be announcing the private port instead. +Gluetun supports setting up a redirection of incoming traffic from the VPN opened port to a custom localhost port of your choosing, by using the `VPN_PORT_FORWARDING_LISTENING_PORT` environment variable. Do not use this with torrent clients, or any other software that publicly announces its port, as that software would not be aware of the publicly visible port and would be announcing the private port instead. For example, if you have a web server (nginx, caddy, apache) listening on port 80, you can set `VPN_PORT_FORWARDING_LISTENING_PORT=80` to expose it to the outside world on all available VPN server's public ports. diff --git a/setup/providers/private-internet-access.md b/setup/providers/private-internet-access.md index 4044466..acc6e3c 100644 --- a/setup/providers/private-internet-access.md +++ b/setup/providers/private-internet-access.md @@ -71,7 +71,7 @@ From [@ddelange](https://github.com/ddelange) on issue [#464](https://github.com ### Setup -Refer to the [VPN server port forwarding setup page](../advanced/vpn-port-forwarding.md). +First refer to the [VPN server port forwarding setup page](../advanced/vpn-port-forwarding.md#native-integrations). Once enabled, you will keep the same forwarded port for 60 days as long as you bind mount the `/gluetun` directory. It will be automatically refreshed. From 71984b25917d111248990fe0b7bafe40d297f3cf Mon Sep 17 00:00:00 2001 From: Quentin McGaw Date: Thu, 13 Nov 2025 16:58:11 +0100 Subject: [PATCH 3/4] Apply suggestion from @qdm12 --- setup/advanced/vpn-port-forwarding.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/setup/advanced/vpn-port-forwarding.md b/setup/advanced/vpn-port-forwarding.md index 18cc951..2ce3bdd 100644 --- a/setup/advanced/vpn-port-forwarding.md +++ b/setup/advanced/vpn-port-forwarding.md @@ -42,9 +42,6 @@ Notes: For this to work, the qBittorrent web UI server must be enabled and listening on port `8080` and the Web UI "Bypass authentication for clients on localhost" must be ticked (json key `bypass_local_auth`) so Gluetun can reach qBittorrent without authentication. -### Transmission example - -Transmission API requires CSRF tokens, so check out [the `transmission-port-update.sh` script](https://github.com/qdm12/gluetun/pull/2611/files). ## Allow a forwarded port through the firewall From 29e0d41f1dd0a417e8326a302d3ebf979cfbc191 Mon Sep 17 00:00:00 2001 From: Quentin McGaw Date: Thu, 13 Nov 2025 17:09:31 +0100 Subject: [PATCH 4/4] Apply suggestions from code review --- setup/advanced/vpn-port-forwarding.md | 1 + setup/providers/privatevpn.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/setup/advanced/vpn-port-forwarding.md b/setup/advanced/vpn-port-forwarding.md index 29bf003..83c1a39 100644 --- a/setup/advanced/vpn-port-forwarding.md +++ b/setup/advanced/vpn-port-forwarding.md @@ -44,6 +44,7 @@ Notes: For this to work, the qBittorrent web UI server must be enabled and listening on port `8080` and the Web UI "Bypass authentication for clients on localhost" must be ticked (json key `bypass_local_auth`) so Gluetun can reach qBittorrent without authentication. Due to a bug in qBittorrent, for port forwarding to be reestablished after a disconnect, the port needs to be re-set. This can be achieved automatically using the DOWN_COMMAND above. +Thanks to [@Marsu31](https://github.com/Marsu31) ## Allow a forwarded port through the firewall diff --git a/setup/providers/privatevpn.md b/setup/providers/privatevpn.md index 25bebbc..03918c2 100644 --- a/setup/providers/privatevpn.md +++ b/setup/providers/privatevpn.md @@ -2,7 +2,7 @@ ## TLDR -💁 To use with Wireguard, see [the custom provider Wireguard section](custom.md#wireguard). You will need to use the IP address of the endpoint instead of the domain - see [discussion](https://github.com/qdm12/gluetun/issues/2680). +💁 To use with Wireguard, see [the custom provider Wireguard section](custom.md#wireguard). For OpenVPN: