LibrePortal
Sponsor
Install

Connect a device to your VPN

Step by step, for Android, iPhone, Windows, Mac, Linux and Chromebook: put the config from Admin, VPN, Add device into the official WireGuard app.

On this page
  1. Android
  2. iPhone and iPad
  3. Windows
  4. Mac
  5. Linux
  6. With NetworkManager (Ubuntu, Fedora)
  7. With wg-quick
  8. Chromebook
  9. Optional: names on Windows and Mac
  10. Check it works
  11. Troubleshooting

When you add a device under the LibrePortal VPN, LibrePortal gives you a QR code and a .conf file. Both hold the same thing: the settings that let one device join your private network. You use the official WireGuard app to load it.

You get them from Admin → VPN → Add device. Give the device a name, say what kind it is, press Add device, and keep that window open while you follow the steps for your device below.

The private key is shown once

The device's secret key is made in your browser and the server never keeps it. Once you close the window, the QR code and file can't be shown again. If you lose them, press Regenerate on the device's row for a fresh config. The old one stops working.

Not sure which section is yours? Jump to Android, iPhone and iPad, Windows, Mac, Linux or Chromebook.

Android#

  1. Install WireGuard. Get it from Google Play. If you don't use Google Play, the same app is on F-Droid (search for WireGuard), or as a direct download from WireGuard.
  2. Open the app and tap +. Choose Scan from QR code and point the camera at the code in LibrePortal.
  3. Name the tunnel when asked, then tap Create tunnel. Android asks permission to set up a VPN. Allow it.
  4. Turn the tunnel on with the switch next to its name.

iPhone and iPad#

  1. Install WireGuard from the App Store. It is called WireGuard, by WireGuard Development Team.
  2. Open the app and tap Add a tunnel. Choose Create from QR code and scan the code in LibrePortal.
  3. Name the tunnel, then tap Save. iOS asks permission to add a VPN configuration. Allow it.
  4. Turn the tunnel on with the switch.

Windows#

  1. Install WireGuard from the official installer at wireguard.com/install.
  2. In LibrePortal, press Download to save the .conf file.
  3. Open WireGuard. Press Import tunnel(s) from file and pick the file.
  4. Press Activate. The status changes to Active.

Want your server's names (like https://nextcloud.homeserver.internal) to work too? See Optional: names on Windows and Mac.

Mac#

  1. Install WireGuard from the Mac App Store.
  2. In LibrePortal, press Download to save the .conf file.
  3. Open WireGuard, choose Import tunnel(s) from file from the menu bar icon or the app, and pick the file. Allow the VPN configuration when macOS asks.
  4. Press Activate.

Linux#

Two ways, depending on how your desktop manages its network. If you aren't sure, Ubuntu and Fedora desktops use NetworkManager, so take the first. In both cases, press Download in LibrePortal first and note where the file lands. Replace x.conf below with its real name.

With NetworkManager (Ubuntu, Fedora)#

  1. Install the tools, if they aren't there already. Ubuntu: sudo apt install wireguard. Fedora: sudo dnf install wireguard-tools.

  2. Import the file. Run nmcli connection import type wireguard file x.conf. NetworkManager makes a connection named after the file.

  3. Switch it on with nmcli connection up x, or from the network menu in your desktop.

  4. For .internal names, tell NetworkManager to ask your server about them. LibrePortal shows the exact line, with your values filled in, under Using NetworkManager? in the Add device window:

    nmcli connection modify x ipv4.dns <server DNS address> ipv4.dns-search '~<your suffix>'

    Then turn the connection off and on again. The VPN works without this step; only the names need it.

With wg-quick#

  1. Install wireguard-tools with your package manager.
  2. Copy the file in: sudo cp x.conf /etc/wireguard/. The tunnel is named after the file, so x.conf becomes x.
  3. Start it: sudo wg-quick up x. Stop it with sudo wg-quick down x.
  4. To start it at every boot: sudo systemctl enable --now wg-quick@x.

Names already work with wg-quick if you ticked Use this server's names, because LibrePortal puts the needed lines in the file. More detail on both tools is on the Arch Linux WireGuard page.

Chromebook#

ChromeOS can run the Android app, so use that.

  1. Install WireGuard from Google Play on the Chromebook, as in the Android steps.
  2. Open the app and import the config. A Chromebook has no camera pointed at your screen, so press Download in LibrePortal, then in WireGuard tap + and choose Import from file or archive.
  3. Turn the tunnel on.

Optional: names on Windows and Mac#

The WireGuard apps on Windows and Mac can't send just one name ending (like .internal) down the tunnel by themselves. If you ticked Use this server's names when adding the device, the Add device window shows one command to run once. Everything else works without it.

  • Windows: run it in PowerShell as administrator. It looks like Add-DnsClientNrptRule -Namespace '.<your suffix>' -NameServers '<server DNS address>'.
  • Mac: run it in Terminal. It looks like sudo mkdir -p /etc/resolver && echo 'nameserver <server DNS address>' | sudo tee /etc/resolver/<your suffix>.

Copy the real command from the window, with your values already in it, using its Copy button. Phones and Linux don't need this, because their config already carries the names.

Check it works#

With the tunnel on, open the address LibrePortal shows in the Add device window, under With the tunnel on, this server is here. It is the server's address on the private network. You should see the LibrePortal sign-in page.

Mobile data is the best test. Turn Wi-Fi off, leave the tunnel on, and open the same address. If it loads, you can reach your server from anywhere.

Troubleshooting#

The tunnel turns on but nothing loads, and there is no "latest handshake". The device can't reach the server's VPN port. That port uses UDP, not TCP. Check that it is open on the server's firewall, and, if your server is at home, that your router forwards it. LibrePortal's VPN page warns you when it thinks the server is behind a router. If you can't forward a port, Connect can reach the server through a relay.

It works on Wi-Fi but not on mobile data (or the other way round). The tunnel only works when the device can reach the server's VPN port from where it is. If your server is at home, that means the port must be open to the internet, or reachable through Connect. Some mobile networks and public Wi-Fi also block UDP, so try a different network to be sure.

I lost the QR code or the file. Press Regenerate on the device's row. That makes a fresh key and a new QR code. The old config stops working, so delete the old tunnel in the WireGuard app.

The VPN works but the names don't. Names need the option Use this server's names and, on Windows, Mac and NetworkManager, the one extra command above. See DNS for your VPN.

Next steps

ConnectReach a server behind a router, with no ports opened at home.DNS for your VPNLet the VPN answer names too, and block ads for your devices.Access keysLet another service read your server's status without a password.