Port Forwarding

Port Forwarding

Every WireGuard configuration created with the config generator supports port forwarding. There are two ways to use it:

• Manual: on the WireGuard page, open the ⋮ menu next to your configuration and choose Port forward. We assign a public port that forwards to the port you choose on your device.
• Automatic (NAT-PMP): apps like gluetun and qBittorrent request a port themselves while connected. Nothing to configure on the website.

How automatic port forwarding works

• We assign the public port (between 30000 and 65000). Requesting a specific public port is not supported.
• Each mapping forwards TCP and UDP on the same public port.
• Your app renews the mapping periodically. If it stops renewing (for example, you disconnect), the forward is removed automatically after about an hour.
• The assigned port usually stays the same while your app keeps renewing, but it can change after a container restart or reconnect.
• Automatic forwards appear on the WireGuard page with an auto tag and count towards the 10 port forwards on your account.

gluetun

• 1. Create a configuration on the WireGuard page and download the .conf file.
• 2. Find the server IP address: take the hostname from the Endpoint line of your .conf (for example ca1-1.btguard.com) and resolve it:
  nslookup ca1-1.btguard.com
  gluetun requires an IP address in VPN_ENDPOINT_IP; it does not accept hostnames.
• 3. Use this docker-compose service, filling in the values from your .conf file:

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=custom
      - VPN_TYPE=wireguard
      - VPN_PORT_FORWARDING=on
      - VPN_PORT_FORWARDING_PROVIDER=protonvpn
      # values from your BTGuard .conf file:
      - WIREGUARD_PRIVATE_KEY=    # PrivateKey under [Interface]
      - WIREGUARD_ADDRESSES=      # Address under [Interface]
      - VPN_DNS_ADDRESS=          # DNS under [Interface]
      - WIREGUARD_PUBLIC_KEY=     # PublicKey under [Peer]
      - VPN_ENDPOINT_IP=          # IP of the Endpoint host (step 2)
      - VPN_ENDPOINT_PORT=444     # number after the : in Endpoint

• 4. Why "protonvpn"? gluetun names its NAT-PMP port forwarding code after ProtonVPN; BTGuard speaks the same standard protocol, so this setting works as-is.
• 5. Start the container. The gluetun log prints the assigned port, and it is also written to /tmp/gluetun/forwarded_port inside the container. Configure the application behind gluetun to listen on that port, or use the gluetun + qBittorrent setup below to push the port automatically.

gluetun + qBittorrent (recommended)

qBittorrent does not read gluetun's port file on its own. Use gluetun's up command (VPN_PORT_FORWARDING_UP_COMMAND) to push the assigned port into qBittorrent every time NAT-PMP sets or renews the mapping — including after a restart when the port may change.

• 1. Run qBittorrent in gluetun's network namespace (network_mode: service:gluetun).
• 2. In qBittorrent Options → Web UI, enable Bypass authentication for clients on localhost so gluetun can reach the API without credentials.
• 3. Add the up/down commands below to gluetun. Change 8080 if your qBittorrent Web UI listens on a different port.

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8080:8080/tcp   # qBittorrent Web UI (optional, for your browser)
    environment:
      - VPN_SERVICE_PROVIDER=custom
      - VPN_TYPE=wireguard
      - VPN_PORT_FORWARDING=on
      - VPN_PORT_FORWARDING_PROVIDER=protonvpn
      - 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'
      # values from your BTGuard .conf file:
      - WIREGUARD_PRIVATE_KEY=
      - WIREGUARD_ADDRESSES=
      - VPN_DNS_ADDRESS=
      - WIREGUARD_PUBLIC_KEY=
      - VPN_ENDPOINT_IP=
      - VPN_ENDPOINT_PORT=444

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    network_mode: service:gluetun
    depends_on:
      - gluetun
    environment:
      - PUID=1000
      - PGID=1000
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent/config:/config
      - ./downloads:/downloads

• 4. The up command runs whenever gluetun gets a forwarded port. It sets qBittorrent's listen port to {{PORT}}, binds it to the VPN interface, and disables random port / UPnP so qBittorrent does not override the assignment.
• 5. The down command clears the listen port when forwarding stops (helps qBittorrent recover cleanly after a disconnect).
• 6. Check gluetun's log for the assigned port and confirm qBittorrent shows the same port under Options → Connection. The forward also appears on the WireGuard page with an auto tag.

qBittorrent (running directly on your device)

If WireGuard runs on your host without gluetun, qBittorrent can request a port itself:

• 1. Connect using your BTGuard WireGuard configuration.
• 2. In Options → Advanced, set Network interface to your WireGuard interface so all traffic uses the VPN.
• 3. In Options → Connection, enable Use UPnP / NAT-PMP port forwarding from my router. qBittorrent requests a port automatically; the assigned port appears in its log and on the WireGuard page.