Skip to content

WireGuard

Jump to bottom
Orazio edited this page Dec 24, 2020 · 13 revisions

Managing the PiVPN

The commands described are just to get started, run pivpn -h to see the full list of options.

pivpn add

You will be prompted to enter a name for your client. Pick anything you like and hit 'enter'. The script will assemble the client .conf file and place it in the directory 'configs' within your home directory.

pivpn remove

Asks you for the name of the client to remove. Once you remove a client, it will no longer allow you to use the given client config (specifically its public key) to connect. This is useful for many reasons but some ex: You have a profile on a mobile phone and it was lost or stolen. Remove its key and generate a new one for your new phone. Or even if you suspect that a key may have been compromised in any way, just remove it and generate a new one.

pivpn list

If you add more than a few clients, this gives you a nice list of their names and associated keys.

Importing Profiles on Client Machines

Windows

Use a program like WinSCP or Cyberduck. Note that you may need administrator permission to move files to some folders on your Windows machine, so if you have trouble transferring the profile to a particular folder with your chosen file transfer program, try moving it to your desktop.

Mac/Linux

Open the Terminal app and copy the config from the Raspberry Pi using scp pi-user@ip-of-your-raspberry:configs/whatever.conf. The file will be downloaded in the current working directory, which usually is the home folder of your PC.

Android/iOS

Just skip to Connecting to the PiVPN below.

Connecting to the PiVPN

Windows/Mac

Download the WireGuard GUI app, import the configuration and activate the tunnel.

Linux

Install WireGuard following the instructions for your distribution. Now, as root user, create the /etc/wireguard folder and prevent anyone but root to enter it (you only need to do this the first time):

mkdir -p /etc/wireguard
chown root:root /etc/wireguard
chmod 700 /etc/wireguard

Move the config and activate the tunnel:

mv whatever.conf /etc/wireguard/
wg-quick up whatever

Run wg-quick down whatever to deactivate the tunnel.

Android/iOS

Run pivpn -qr on the PiVPN server to generate a QR code of your config, download the Wireguard app Android link / iOS link, click the '+' sign and scan the QR code with your phone's camera. Flip the switch to activate the tunnel.

FAQ (Frequently Asked Questions)

How do I use Pi-hole with PiVPN?

You can safely install PiVPN on the same Raspberry Pi as your Pi-hole install, and point your VPN clients to the IP of your Pi-hole so they get ad blocking, etc. (replace 192.168.23.211 with the LAN IP of your Raspberry Pi).

Note that if you install PiVPN after Pi-hole, your existing Pi-hole installation will be detected and the script will ask if you want to use it as the DNS for the VPN, so you won't need to go through all these steps.

  1. Edit the PiVPN configuration with sudo nano /etc/pivpn/wireguard/setupVars.conf
  2. Remove the pivpnDNS1=[...] and pivpnDNS2=[...] lines
  3. Add this line pivpnDNS1=192.168.23.211 to point clients to the PiVPN IP
  4. Save the file and exit
  5. Run pihole -a -i local to tell Pi-hole to listen on all interfaces

New clients you generate will use Pi-hole but you need to manually edit existing clients:

  1. Open your configuration, for example whatever.conf
  2. Replace the line DNS = [...], [...] with this line DNS = 192.168.23.211
  3. Save the file and connect again

How do I change the public IP/DNS name of the PiVPN after the install?

  1. Edit the PiVPN configuration with sudo nano /etc/pivpn/wireguard/setupVars.conf
  2. Update the pivpnHOST=[...] line
  3. Save and exit

New clients you generate will use the new endpoint but you need to manually edit existing clients:

  1. Open your configuration, for example whatever.conf
  2. Update the line Endpoint = [...]:51820
  3. Save the file and connect again

How do I allow clients access to my home network but not the internet through my PiVPN?

Replace the following line in your client configuration: AllowedIPs = 0.0.0.0/0, ::0/0 with AllowedIPs = [...], 10.6.0.0/24 where [...] is the IP and netmask of your LAN, for example 192.168.23.0/24. 10.6.0.0/24 is the IP and netmask of the virtual network (same for everyone).

How do I upgrade WireGuard to the latest version?

If you installed PiVPN on or after March 17th 2020 WireGuard will be upgraded via the package manager (APT).

Run pivpn -wg and follow the instructions.

How Can I Migrate my configs to another PiVPN Instance?

Backup your server with pivpn -bk copy the tar archive to your computer. example using scp on linux:

scp <user>@<server>:~/pivpnbackup/<archivename> <path/on/local>

Install WireGuard the new pi/server

  1. Backup the current install: sudo cp -r /etc/wireguard /etc/wireguard_backup
  2. Extract the backup archive: tar xzpfv <archive name>
  3. Copy the extracted content: sudo cp -r etc/wireguard /etc
  4. Restart the wireguard service: sudo systemctl restart wg-quick@wg0

OBS: Please be aware of the difference between /etc/ and etc/!
/etc with the starting slash is a system directory
etc/ without starting slash and tailing slash means its a directory in your current working dir.

How to resolve local hostnames?

All you have to do is to use your router as DNS Server instead of using other public DNS providers. If you have already a working installation of WireGuard, all you need to do is to edit your client config and change the line DNS = [...], [...] to DNS = 192.168.23.1 (assuming 192.168.23.1 is your gateway IP).

Alternatively you can change /etc/hosts file and add <IPAddress> <hostname> Example:

192.168.1.1   JohnDoeRouter
192.168.1.2   JohnDoePC
192.168.1.3   JaneDoePC
192.168.1.4   CatPC
192.168.1.5   DogPC

How to I fix a broken WireGuard update?

On Raspbian, from time to time, it may happen that an update of the WireGuard module goes wrong. In that case, after a reboot, PiVPN will stop working. You can see the details by running systemctl status wg-quick@wg0:

$ systemctl status wg-quick@wg0
[...]
Dec 24 11:10:46 raspberrypi systemd[1]: Starting WireGuard via wg-quick(8) for wg0...
Dec 24 11:10:47 raspberrypi wg-quick[3573]: [#] ip link add wg0 type wireguard
Dec 24 11:10:47 raspberrypi wg-quick[3573]: Error: Unknown device type.
Dec 24 11:10:47 raspberrypi wg-quick[3573]: Unable to access interface: Protocol not supported
Dec 24 11:10:47 raspberrypi wg-quick[3573]: [#] ip link delete dev wg0
Dec 24 11:10:47 raspberrypi wg-quick[3573]: Cannot find device "wg0"
Dec 24 11:10:47 raspberrypi systemd[1]: wg-quick@wg0.service: Main process exited, code=exited, status=1/FAILURE
Dec 24 11:10:47 raspberrypi systemd[1]: wg-quick@wg0.service: Failed with result 'exit-code'.
Dec 24 11:10:47 raspberrypi systemd[1]: Failed to start WireGuard via wg-quick(8) for wg0.

To fix this we need to reinstall the latest kernel and kernel header, and recompile the WireGuard module.

Important! Avoid using rpi-update if you plan to run WireGuard. rpi-update installs development kernel that don't always come with matching kernel headers, which are required to successfully compile the module.

  • Reinstall latest kernel and kernel headers: sudo apt install --reinstall raspberrypi-kernel raspberrypi-kernel-headers.
  • Reboot into the new kernel: sudo reboot.
  • Recompile WireGuard kernel module: sudo dpkg-reconfigure wireguard-dkms.
  • Restart WireGuard (you should get no output): sudo systemctl restart wg-quick@wg0.
  • Run pivpn -d and verify that all checks are [OK].
Clone this wiki locally