How the VPN in Vistu Server works
Vistu Server can send the playlists you choose through your VPN. Your TVs don’t need a VPN app, and nothing else in your home uses the VPN: not your library, not your NAS, not the other devices on your network.
The short version
- It’s per playlist. You add your VPN service, with the locations you want, in Manage › TV service › VPN, then choose a location in each playlist’s settings. Different playlists can use different services and countries.
- It’s a split tunnel. Only that playlist’s traffic goes through the VPN. Everything else uses your own connection as usual.
- It fails closed. If the VPN drops, those playlists stop until it’s back. They never quietly use your own connection instead.
- It runs inside the container. Nothing changes on your router, your NAS or your other devices.
Where the traffic goes
Without a VPN, a TV asks Vistu Server for a channel, and the server (or the TV itself) connects to your TV service over your home internet. Your TV service sees your home’s internet address.
With a VPN location chosen for a playlist, Vistu Server keeps an encrypted tunnel open to your VPN service’s server. Everything for that playlist goes into the tunnel, comes out at the VPN server, and only then reaches your TV service, which sees the VPN’s address instead of yours. The tunnel still crosses your router, but your router (and your internet provider) only see encrypted traffic to the VPN.
A playlist on the VPN always plays through Vistu Server. Normally a TV may connect to your TV service directly; for a VPN playlist the server never gives TVs the service’s addresses, only its own. Channel logos and posters come through the server too. That’s what lets a TV without any VPN app watch through the VPN.
What uses the VPN
| Through the VPN (for playlists you put on one) | Never through the VPN |
|---|---|
| Loading the playlist: channels, movies, series | Your movies and series library, and your NAS |
| Live channels, movies and episodes as they play | The web pages you manage the server from |
| Logos, posters and other pictures | Sports times and scores |
| The guide, when it comes from your TV service’s own address (other guide websites too, if you tick that in the playlist) | The optional update check |
| Name lookups (DNS) for all of the above | Watching from outside your home |
| The connection check for that playlist | Other playlists, and every other device in your home |
Names are looked up inside the tunnel. Before connecting to your TV service, a computer has to turn its name into an address. For a VPN playlist, Vistu Server asks your VPN service’s own name server, through the tunnel. Your home router and internet provider don’t see which names it looks up.
Several VPNs and locations
Most VPN services have servers in many countries, and give you a file for each one. In Vistu Server, each file you add is a location, for example PrivadoVPN · London. Add as many as you’ll use, from one service or several, then choose a location for each playlist. A UK service can come out in London while a US one comes out in New York, and a playlist that doesn’t need a VPN uses your own connection.
- Only locations in use connect. VPN services limit how many connections you can have at once, so a location connects only while a playlist uses it (or for a moment, when you press Test). Adding a long list of regions costs nothing until you use them.
- One login per service. For OpenVPN services you enter the username and password once; every location of that service uses them.
- Each location is separate. Every location has its own tunnel, and a playlist’s traffic only ever goes into its own. If one location drops, only its playlists stop; the others carry on.
- Removing a location doesn’t move its playlists home. They stop, and say so, until you choose another location (or no VPN) in their settings.
When the VPN drops
VPN connections drop now and then: the VPN server restarts, your internet blips, a login expires. A lot of setups quietly carry on over your own connection when that happens. Vistu Server doesn’t. Connections for a VPN playlist can only leave through the tunnel. With the tunnel down, they fail.
While it’s down, channels on those playlists won’t start, and the VPN page says what’s happening (for example “trying to reach the VPN server”). Vistu Server keeps reconnecting on its own; you don’t need to do anything once the VPN is reachable again. Playlists that don’t use the VPN, and your library, carry on as normal the whole time.
WireGuard or OpenVPN
VPN services hand out settings files for “manual setup” or “router setup”. Vistu Server takes the two common kinds: WireGuard files (.conf) and OpenVPN files (.ovpn). Both give you the same split tunnel and the same fail-closed behaviour. The difference is how they run inside the container.
| WireGuard | OpenVPN | |
|---|---|---|
| File | .conf | .ovpn, with everything in one file |
| Container settings | None | NET_ADMIN and /dev/net/tun |
| How it runs | Entirely inside Vistu Server’s VPN helper, in memory | The standard openvpn program, with its own network device |
| Sign-in | Keys in the file | Often a username and password as well, kept encrypted on the server |
| Services | Mullvad, Proton VPN, IVPN, AirVPN, Surfshark, Windscribe and others | PrivadoVPN, NordVPN, ExpressVPN and others |
Use WireGuard when your service offers it. It needs nothing extra from Docker, it’s quick to connect, and it’s light on a NAS. OpenVPN is there for the services that only give OpenVPN files.
WireGuard: no extra rights
WireGuard’s whole job is turning network packets into encrypted ones. Vistu Server’s VPN helper does that in its own memory, with its own small network stack, and offers the result as a private proxy that only the server uses. No network device is created and the container needs no extra permissions, which is why WireGuard works with a plain docker run.
OpenVPN: its own network device
OpenVPN works differently and needs a real network device: one per location, called vistu1, vistu2 and so on. Making one inside a container takes two settings: the NET_ADMIN right and the /dev/net/tun device. Vistu Server keeps their reach as small as it can:
- Only openvpn gets the right. Vistu Server itself still runs as your ordinary user (
PUID), never root. In the image, only theopenvpnprogram is allowed to useNET_ADMIN, and only within the container’s own network, not your NAS’s (unless you run the container with host networking, which Vistu Server doesn’t need). - It takes no routes. VPN services usually tell OpenVPN to send everything through them. Vistu Server ignores that, along with the VPN’s DNS changes, so the container’s routes stay exactly as they were.
- Only tied connections use it. The helper ties each of a VPN playlist’s connections, and its name lookups, to its location’s device. A connection tied to a device can only leave through it, so when the VPN drops it fails rather than finding another way out.
- Nothing in the file runs. OpenVPN files can ask to run scripts or change routes. Those lines are removed before the file is used. Your username and password go to openvpn directly and are never written to disk.
Setting up OpenVPN
Add the two settings to the Vistu Server container, then recreate it. With Docker Compose, under the vistu-server service:
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun
Then docker compose up -d. With docker run, add --cap-add NET_ADMIN --device /dev/net/tun. On a NAS with a container app, look for “capabilities” (add NET_ADMIN) and “devices” (add /dev/net/tun).
- Open Manage › TV service › VPN and choose your VPN service. For OpenVPN services the page first checks the container and says Ready for OpenVPN, or exactly what’s missing.
- Follow the steps to download an
.ovpnfile for each location you want from your VPN service’s website. - Choose the files (several at once is fine), name each location, enter the username and password, and press Add and test. Some services (NordVPN, ExpressVPN) have a separate username and password for manual setup: use those, not your account login.
- In each playlist that should use a VPN, choose its location.
If it doesn’t start:
- No /dev/net/tun: on Synology, the
tunmodule may not be loaded. A boot-up task runninginsmod /lib/modules/tun.koas root loads it. - no-new-privileges: this Docker security option stops openvpn using
NET_ADMIN. Remove it from the container, or use WireGuard. - “Refers to its ca in a separate file”: download the version of the file with the certificates inside it (usually the default).
Checking it works
- The VPN page shows each location: whether it’s connected, which playlists use it, when the VPN server was last heard from, and the data through it. For some services it also shows where the tunnel comes out, for example Comes out in Toronto, Canada, checked through the tunnel.
- Check on the same page opens any address you give it through the location you choose: use your VPN service’s own “what’s my address” page.
- Activity tags streams that use the VPN, so you can see what’s going through it right now.
- Diagnostics › Connection check runs the chain for one playlist: Vistu Server, internet, VPN, TV service and speed, and says which link is weakest.
What we see
Nothing. The VPN runs on your server, between you and your VPN service. Your VPN file, username and password are stored encrypted on your server and never sent to us, and Vistu Server doesn’t call any Vistu service to check the VPN.
← Vistu Server · Questions? Contact support