VPN Configuration - Will-Luck/iplayer-arr GitHub Wiki

VPN Configuration

Overview

BBC iPlayer enforces geographic restrictions and only serves content to UK IP addresses. If you are running iplayer-arr outside the UK, a VPN tunnel is the primary way to obtain a UK IP address so that stream resolution and downloads succeed.

iplayer-arr is built on the hotio/base:alpinevpn image, which provides:

  • WireGuard tunnel support (built into the Alpine kernel)
  • nftables kill switch that blocks all traffic if the tunnel drops, preventing non-UK requests from leaking
  • s6-overlay process supervision for reliable tunnel lifecycle management
  • PIA and Proton provider integrations with automatic key exchange
  • Generic WireGuard support for any provider that supplies a .conf file

VPN is disabled by default (VPN_ENABLED=false). When you are already on a UK network, no VPN configuration is needed -- the container works without any VPN variables set.

Environment Variables

All VPN variables are handled by the hotio base image. iplayer-arr does not add any VPN variables of its own.

Variable Default Description
VPN_ENABLED false Enable the WireGuard VPN tunnel. When true, the container creates a wg0 interface and routes all traffic through it.
VPN_PROVIDER generic VPN provider preset. Accepted values: generic, pia, proton. The generic provider reads a WireGuard config file from disk; pia and proton handle key exchange automatically.
VPN_LAN_NETWORK -- Local network CIDR to exclude from the tunnel (e.g. 192.168.1.0/24). Required so the web UI remains reachable from your LAN. Multiple subnets can be comma-separated.
VPN_PIA_USER -- PIA username (starts with p). Only used when VPN_PROVIDER=pia.
VPN_PIA_PASS -- PIA password. Only used when VPN_PROVIDER=pia.
VPN_PIA_PREFERRED_REGION -- PIA server region (e.g. uk). Only used when VPN_PROVIDER=pia.
VPN_HEALTHCHECK_ENABLED false When true, the container monitors tunnel health and brings the container down if the VPN connection fails. Useful for preventing downloads over an unprotected connection.
VPN_AUTO_PORT_FORWARD false Automatically retrieve a forwarded port from the provider. Supported by PIA and Proton. Not typically needed for iplayer-arr since it only makes outbound connections.
WEBUI_PORTS -- Ports to allow through the nftables kill switch so the web UI remains accessible (e.g. 8191/tcp). Without this, the kill switch blocks inbound connections to the container.

Note: VPN_LAN_NETWORK and WEBUI_PORTS are effectively required whenever VPN_ENABLED=true. Without them, the web UI will be unreachable from your network.

Docker Capabilities

When VPN_ENABLED=true, two additional Docker flags are required:

--cap-add=NET_ADMIN
--sysctl net.ipv4.conf.all.src_valid_mark=1
  • NET_ADMIN allows the container to create the WireGuard network interface and configure nftables rules.
  • The sysctl flag is needed for policy-based routing so the tunnel and LAN traffic coexist correctly.

If either flag is missing, the container will fail to bring up the tunnel and log an error at startup.

PIA Setup

Private Internet Access is the simplest provider to configure because the hotio base image handles WireGuard key exchange automatically -- no config file is needed.

Docker CLI

docker run -d \
  --name iplayer-arr \
  --cap-add NET_ADMIN \
  --sysctl net.ipv4.conf.all.src_valid_mark=1 \
  -e TZ=Europe/London \
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=002 \
  -e VPN_ENABLED=true \
  -e VPN_PROVIDER=pia \
  -e VPN_PIA_USER=p1234567 \
  -e VPN_PIA_PASS=YourPassword \
  -e VPN_PIA_PREFERRED_REGION=uk \
  -e VPN_LAN_NETWORK=192.168.1.0/24 \
  -e WEBUI_PORTS=8191/tcp \
  -p 8191:8191 \
  -v /path/to/config:/config \
  -v /path/to/downloads:/downloads \
  ghcr.io/will-luck/iplayer-arr:latest

Docker Compose

services:
  iplayer-arr:
    image: ghcr.io/will-luck/iplayer-arr:latest
    container_name: iplayer-arr
    cap_add:
      - NET_ADMIN
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    environment:
      - TZ=Europe/London
      - PUID=1000
      - PGID=1000
      - UMASK=002
      - VPN_ENABLED=true
      - VPN_PROVIDER=pia
      - VPN_PIA_USER=p1234567
      - VPN_PIA_PASS=YourPassword
      - VPN_PIA_PREFERRED_REGION=uk
      - VPN_LAN_NETWORK=192.168.1.0/24
      - WEBUI_PORTS=8191/tcp
    ports:
      - 8191:8191
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    restart: unless-stopped

Set VPN_PIA_PREFERRED_REGION to uk to ensure you get a UK exit IP. PIA region names are listed in the PIA server list.

Generic WireGuard

For any WireGuard provider that gives you a .conf file (Mullvad, IVPN, self-hosted, etc.), use the generic provider and mount your config file into the container.

  1. Obtain a WireGuard configuration file from your provider. Make sure the endpoint resolves to a UK server.
  2. Save it as wg0.conf in your config directory.
  3. Mount it to /config/wireguard/wg0.conf.

Docker CLI

docker run -d \
  --name iplayer-arr \
  --cap-add NET_ADMIN \
  --sysctl net.ipv4.conf.all.src_valid_mark=1 \
  -e TZ=Europe/London \
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=002 \
  -e VPN_ENABLED=true \
  -e VPN_PROVIDER=generic \
  -e VPN_LAN_NETWORK=192.168.1.0/24 \
  -e WEBUI_PORTS=8191/tcp \
  -p 8191:8191 \
  -v /path/to/config:/config \
  -v /path/to/config/wireguard/wg0.conf:/config/wireguard/wg0.conf \
  -v /path/to/downloads:/downloads \
  ghcr.io/will-luck/iplayer-arr:latest

Docker Compose

services:
  iplayer-arr:
    image: ghcr.io/will-luck/iplayer-arr:latest
    container_name: iplayer-arr
    cap_add:
      - NET_ADMIN
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    environment:
      - TZ=Europe/London
      - PUID=1000
      - PGID=1000
      - UMASK=002
      - VPN_ENABLED=true
      - VPN_PROVIDER=generic
      - VPN_LAN_NETWORK=192.168.1.0/24
      - WEBUI_PORTS=8191/tcp
    ports:
      - 8191:8191
    volumes:
      - ./config:/config
      - ./wireguard/wg0.conf:/config/wireguard/wg0.conf
      - ./downloads:/downloads
    restart: unless-stopped

The config file must be named wg0.conf. The hotio base image reads it automatically on startup and brings up the wg0 interface.

Verifying VPN

After starting the container with VPN enabled, confirm the tunnel is working before relying on downloads.

From the Web UI

Open the System page in the iplayer-arr web UI. The geo status indicator shows whether the container has a UK IP address. If the status shows a non-UK country, the tunnel is not routing traffic correctly.

From the Command Line

docker exec iplayer-arr curl -s ifconfig.me

The output should be a UK IP address belonging to your VPN provider. You can verify the country with:

docker exec iplayer-arr curl -s https://ipinfo.io/country

This should return GB. If it returns your real country, the tunnel is not active.

Checking the Tunnel Interface

docker exec iplayer-arr wg show

This displays the WireGuard interface status, including the endpoint, last handshake time, and transfer statistics. If no output is returned, the tunnel was not created.

Troubleshooting

Container exits immediately with VPN enabled

  • Verify --cap-add=NET_ADMIN and --sysctl net.ipv4.conf.all.src_valid_mark=1 are set.
  • Check container logs: docker logs iplayer-arr. The s6-overlay init will log the failure reason.

Web UI not reachable

  • Confirm VPN_LAN_NETWORK matches your local subnet.
  • Confirm WEBUI_PORTS includes 8191/tcp (or whichever port you are using).

Downloads fail with "not available in your area"

  • The VPN tunnel may be connected to a non-UK server. Check your exit IP with docker exec iplayer-arr curl -s ifconfig.me.
  • For PIA, set VPN_PIA_PREFERRED_REGION=uk. For generic configs, ensure the endpoint is a UK server.

Tunnel drops intermittently

  • Enable VPN_HEALTHCHECK_ENABLED=true so the container restarts when the tunnel fails, rather than silently falling back to your real IP.
  • Check your provider for connection limits or server issues.

Further Reading