VPN

Written for highsea 0.1.0.

Settings › VPN decides how torrents reach the internet. With a VPN, peers in a swarm see your provider's address instead of yours, and highsea checks that it stays that way. With highsea connects or an interface, only torrents use the VPN, and indexer searches if you choose. With a VPN container, everything highsea does goes through it, since highsea shares the container's network.

Only the Owner sees this area. Admins don't find it in Settings.

Recommended setup has the short version. This page covers each mode, the providers, port forwarding, the checks and what to do when something goes wrong.

The pageCopy Anchor Link

The page has three parts:

• Status: what the VPN is doing now, the checks that prove it, and Check now and Reconnect.
• Connection: the mode, and what that mode needs.
• Behaviour: what highsea does with the tunnel. It's hidden while the mode is Off.

Changes take effect when you press Save.

Choosing a modeCopy Anchor Link

A new server starts with Off.

highsea connectsCopy Anchor Link

highsea brings up a WireGuard tunnel inside its own container and binds every torrent to the tunnel's address. A packet from that address can only leave through the tunnel, so if the tunnel drops, torrents stop rather than fall back to your own connection.

What it needsCopy Anchor Link

• Linux. highsea's Docker image runs Linux, so this works wherever highsea runs in Docker. If you run highsea some other way on macOS or Windows, use another mode.
• The NET_ADMIN capability for highsea's container, so it can make its own network interface and routes. This reaches only highsea's container, not the host.
• Its own network, not host networking. With host networking, highsea's interface and routes would land in the host's network beside everything else.
• The TUN device, only on older kernels without WireGuard built in (Linux before 5.6, which some NAS systems still run).

compose.connects.yaml at the root of highsea's repository has all of this. The lines that matter:

services:
  highsea:
    image: ghcr.io/highsea-tv/highsea:latest
    cap_add: [NET_ADMIN]
    # devices: [/dev/net/tun:/dev/net/tun]   # only on a kernel without WireGuard
    ports:
      - "3000:3000"
      - "6881:6881/tcp"
      - "6881:6881/udp"
      - "7368:7368/udp"

Because the container doesn't use host networking, apps on your network find the server through the UDP broadcast on port 7368 rather than mDNS. See Network and remote access.

If highsea starts without the capability, the status says highsea can't run the tunnel yet and shows the compose lines to add, with a Copy button. Add them, then recreate the container.

Pick your providerCopy Anchor Link

Choose your provider under Provider. highsea shows that provider's own steps beneath it. Most providers give you a WireGuard configuration file to download; upload it with Upload a file, or choose Paste instead and paste its contents. Once saved, the file's keys stay on the server: the page shows only the file's name, with Replace the file to change it.

The list of providers comes from highsea's catalog, so new providers can appear without a new version of highsea.

What the configuration file needsCopy Anchor Link

highsea reads the file as WireGuard's own tools do, and refuses one it can't use, with the reason under the field. Besides its keys and at least one [Peer], the file needs:

• an IPv4 Address in its [Interface] section;
• an Endpoint for each [Peer];
• a DNS line in its [Interface] section. Without it, tracker names would be looked up outside the tunnel, so highsea stops torrents and the Names check says so.

Files downloaded from the providers above have all three.

highsea connects carries IPv4 only for now, so torrents use IPv4 while it's on.

A VPN containerCopy Anchor Link

highsea joins the network of a gluetun container, whose only route out is the tunnel. gluetun makes the tunnel and supports many providers, including those that only offer OpenVPN; highsea reads gluetun's status and forwarded port from its control server.

Set it upCopy Anchor Link

1. Make an API key for gluetun's control server:

   Copy Text

   docker run --rm qmcgaw/gluetun genkey

2. Add a gluetun service to your compose file and join highsea to its network with network_mode: "service:gluetun". highsea's ports move to the gluetun service, since highsea no longer has a network of its own. compose.gluetun.yaml at the root of highsea's repository is a complete example for Proton VPN.

   For other providers, open Compose for your provider on the VPN page, pick your provider, and Copy the block it writes. Fill in what your provider gives you, and put your API key in HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE. gluetun's wiki has a page for each provider with the settings it takes. highsea never gets access to Docker itself, so you run this step.

3. Start both, then in Settings › VPN choose A VPN container.

4. Leave Control server at http://127.0.0.1:8000. The two containers share a network, so gluetun is on highsea's own loopback address.

5. Enter the API key and save. highsea asks gluetun before it saves, and says so if gluetun refuses the key or can't be reached.

For port forwarding through gluetun, turn it on in gluetun's settings (VPN_PORT_FORWARDING: "on" for providers gluetun supports it with) and keep Use the forwarded port on in highsea.

Apps can't find the server on their own in this setup, since discovery needs host networking or highsea's own published ports. Give them the server's address instead.

An interface on this machineCopy Anchor Link

If you already run a VPN on the host, such as WireGuard or OpenVPN, choose An interface on this machine and pick its Interface. The list shows the interfaces highsea can see besides the LAN, with their addresses. In Docker, highsea sees the host's interfaces only with host networking.

highsea binds every torrent to the interface's address. If the interface goes down or loses its address, torrents stop at once and start again when it's back. Your system's routing still decides the path, so highsea can promise less here than in the other two modes; the Kill switch check says so.

Port forwarding is up to you in this mode: forward the torrent port through your tunnel yourself, if your provider allows it.

BehaviourCopy Anchor Link

Port forwardingCopy Anchor Link

Without a forwarded port, downloads still work: highsea connects out to peers. With one, peers can connect in too, so more peers can reach you, which helps with less popular torrents and with seeding.

• Proton VPN and Private Internet Access: highsea asks the provider for a port once connected, keeps it renewed, and moves torrents to it. If the provider doesn't forward one, highsea tries again every minute and the check warns.
• AirVPN, Windscribe and Another WireGuard provider: reserve a port with your provider and type it into Forwarded port. Leave the field empty if there isn't one.
• Mullvad, IVPN and Surfshark don't forward ports.
• A VPN container: highsea uses the port gluetun reports.

Status and checksCopy Anchor Link

The top of the page says what the VPN is doing:

When the tunnel drops, highsea reconnects on its own, waiting a little longer after each try, up to 5 minutes between tries. Reconnect tries at once.

Below the status is a list of checks, each marked Passed, Warning, Failed, Note or Waiting:

The checks run when the tunnel connects, every 5 minutes after that, after each reconnect, and when you press Check now. Torrents only start once the first checks are done.

With highsea connects, a check that finds a leak stops torrents: an exit address that's your own, names looked up outside the tunnel, or a missing routing rule (which highsea puts back first). In the other modes a failing check warns, since the container has no other route and the interface binding already holds.

When the VPN is down or a check fails, System › Health says so too, and a connection that hears Health sends it to you. See Notifications.

TroubleshootingCopy Anchor Link

highsea can't run the tunnel yet. highsea's container is missing the NET_ADMIN capability. Add cap_add: [NET_ADMIN] to its service and recreate the container.

The kernel has no WireGuard, and /dev/net/tun isn't there. Common on older NAS kernels. Add devices: [/dev/net/tun:/dev/net/tun] to highsea's service and recreate the container.

highsea connects runs on Linux. highsea isn't running in its Docker image or on Linux. Use a VPN container or an interface on this machine instead.

Names are being looked up outside the tunnel. The WireGuard file has no DNS line. Download a new file from your provider, or add the DNS server your provider documents, and upload it again.

PIA didn't accept that username and password. Use the username you sign in to PIA with, which starts with p, not your email address.

Couldn't reach the VPN container's control server. Check that gluetun is running, that highsea uses network_mode: "service:gluetun", and that the address is http://127.0.0.1:8000.

gluetun's control server refused that API key. The key in Settings › VPN must match the one in gluetun's HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE. Recreate the gluetun container after changing it.

Couldn't check the exit address. The IP echo service didn't answer. This isn't a leak; highsea checks again in 5 minutes.

Your provider didn't forward a port. Downloads still work, with fewer peers able to reach you. For Proton VPN, make sure the configuration is for a P2P server with NAT-PMP turned on.