In this tutorial, we will look at how to set up WireGuard VPN on a Raspberry Pi using PiVPN! The goal is to provide easy instructions that will help you set up the WireGuard Raspberry Pi VPN server.
WireGuard is awesome! Up until WireGuard, the gold standard for VPNs has been OpenVPN, which is still a great VPN option. However, WireGuard is a faster alternative that’s somewhat easier to implement.
It also has the benefit of being a lot simpler than OpenVPN, which doesn’t seem important, but it is. If you’re already using OpenVPN, the overall functionality will be similar.
Ultimately, more complex systems have more attack points, so if you care about security, WireGuard might be your answer. It’s important to note that you can install WireGuard on various types of devices.
It’s best to run PiVPN and WireGuard on a Raspberry Pi 4 or 5, but if you have at least a Raspberry Pi 3 B+, that should be fine. This is because only the Raspberry Pi 3 B+ and Raspberry Pi 4 have gigabit ethernet, which is preferable for PiVPN and WireGuard.
How to Set Up a WireGuard VPN on a Raspberry Pi
Setting up a WireGuard Raspberry Pi VPN Server is a quick and easy process thanks to PiVPN which we will be utilizing in this tutorial.
1. Installing Raspberry Pi OS (Initial Install Steps)
Before you can install WireGuard, you must install the Raspberry Pi OS using the steps below.
1. Navigate to the Raspberry Pi website and download the Raspberry Pi Imager.
2. After the download finishes, launch the Raspberry Pi Imager application and connect your SD card to your computer.
3. Select Choose OS and choose the operating system that you would like to use. In this example, I will be using Raspbian Lite.
4. After selecting your operating system, select Choose SD Card and select the SD card that you connected to your machine.
NOTE: This will fully format the SD card so remove any important data prior to proceeding.
5. After the operating system and SD card have been selected, select write. This will write the operating system to the SD card.
2. Using PiVPN for WireGuard
We will look at how to set up WireGuard on a Raspberry Pi below using PiVPN.
Thanks to a handy script (PiVPN), installing WireGuard is very simple. Generally, you want to ensure the script you’re running is trusted. This is a known and trusted script, but I still urge you to review it.
1. Open Terminal on your Raspberry Pi and run the command below, which will execute a script to install PiVPN (which has WireGuard built-in).
curl -L https://install.pivpn.io | bash
2. Wait for the process to install the necessary packages. When it’s done, you will be brought to a screen that will inform you that PiVPN will allow you to install OpenVPN or WireGuard. Select OK.
3. The next screen will inform you that you need to set a static IP address. It’s best to set a static IP address in your router’s settings, as you are ensuring that DHCP does not try and give this address to any other devices.
However, certain routers (mostly ISP-provided ones) do not allow you to complete DHCP reservations. If you can’t set a static IP address for your Raspberry Pi in your router, set a static IP address on the Raspberry Pi by following the instructions.
I specified a static IP address in my router so I am going to skip this step.
4. You will now need to select a local user. If you’ve created a different user (outside of the default pi user), you will have the option here.
5. You will be asked to select a VPN type. Select WireGuard.
6. You might be prompted to install the latest kernel update. If you are, select Yes to proceed. If it doesn’t, skip to the next step to proceed.
NOTE: If you need to update the kernel, you will be required to restart this process after your Raspberry Pi reboots (start from step 1).
7. WireGuard will now install.
8. You will be asked to enter the port you’d like to use (default is 51820). It’s probably best to keep it as the default, but if you have a reason to change it, you can do that here.
NOTE: This is UDP port 51820.
9. Select Yes.
10. You now need to select the DNS provider you’d like to use. Select Custom if you’d like to use your own DNS server, or any of the public DNS providers if you don’t want to use a local DNS server.
11. I am using a local Pi-hole DNS server that I already have configured, so I added the IP address there. If you are using a public DNS provider, you can skip this step.
NOTE: The IP addresses (192.168.1.197,192.168.1.198) are my local DNS servers. This will not work for you so ensure you use your local DNS servers or a public DNS provider!
12. The DNS servers that you select will now be listed. Select Yes.
13. You will now be prompted to use your public IP address or public DNS entry. If you have a static IP address, you are free to use this address.
However, if you have a dynamic external IP address, you will need to set up DDNS. You can learn how to do that here.
14. If you selected to use a dynamic DNS address, you can enter that information here. At the next screen, select Yes to confirm that it is correct.
15. You will now be prompted that the server keys will be generated. Select OK. The next step will tell you that the VPN Server will check for unattended-upgrades, and a periodic reboot will be required.
This is a great option. Enable unattended-upgrades (unless you have a good reason not to) and proceed. The packages will now install.
16. The installation is now complete! Reboot your system. If you’re using the Raspberry Pi Firewall, make sure you create a rule for UDP port 51820.
VPN Connection Types
This section is important for future steps (so you know what kind of profiles you’d like to create). We will be creating either a split-tunnel VPN, a full tunnel VPN, or both in later steps.
Split-Tunnel VPN: Traffic is only sent through your network if it is attempting to access an internal resource. Your IP address when navigating to a site outside of your network will be the IP address of the network that you are currently on.
Full-Tunnel VPN: All traffic is sent through your home network. Your IP address for internal and external requests will be your home network.
I created a very basic image below that explains this, but we will look at how to configure both in later steps. It’s important to note that both connection types will allow you to access your local network. This only shows how traffic is routed differently to external networks.
NOTE: This is not the exact network flow. I am simplifying the process as much as I can.
3. Configuration File Changes
The two changes that we will make below are in the wg0 config file. Run these commands to open the config file:
sudo su
nano /etc/wireguard/wg0.confWith the file open, proceed to the next steps.
PostUp & PostDown Rules
This section is a little tricky because these lines will be mandatory if you’re interested in using a split-tunnel VPN profile. If you are using full-tunnel only, there’s a chance that everything will work without adding the PostUp and PostDown lines to the config file. So in summary, add these lines if you intend on using a split-tunnel VPN profile.
If you only intend on using full-tunnel, you might not need to add these lines as all traffic will be routed through your Raspberry Pi. If you don’t add them and you can’t access local resources or connect to the internet when you’re connected to your VPN, come back to this section and add these two lines.
I will do my best to break down everything in these commands so there’s some sort of explanation as to what these changes do.
- PostUp: command that is executed when you connect to your WireGuard VPN.
- IPTables: What the system should do with certain packets. A table is created with these rules so the system knows what to do when it receives a packet. These are what the different command-line parameters mean.
- Masquerade: IP address will be rewritten from source (wg0) to destination (eth0). In layman’s terms, the traffic appears as if it originates from the Raspberry Pi as opposed to the source device. When traffic comes in and is sent to your client device (where you are connected to the VPN), the traffic will have the destination IP rewritten from eth0 (Raspberry Pi) to wg0 (WireGuard network). You still need a static route if you’d like to access your VPN clients!
- PostDown: command that is executed when you disconnect from your WireGuard VPN to undo everything that we did in the “PostUp” command.
Add these lines to the config file to create an IP table when you connect to WireGuard and masquerade your IP address. NOTE: You might need to change eth0 to be the network interface of your device. However, since you’re using a Raspberry Pi, it’s most likely eth0.
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADESave the file and exit!
4. VPN Profile Creation & Modifications
This is the section where we will create our VPN profiles. I will be creating both, a split-tunnel VPN and a full-tunnel VPN, but feel free to only create profiles for the VPN types you’d like.
1. Run the command below to add a profile.
sudo pivpn add
2. Navigate to the configs folder. There will be two config files, one for our split-tunnel profile and one for our full-tunnel.
cd configs
3. By default, WireGuard is configured as full-tunnel. For this reason, we can leave the full-tunnel file alone and edit the split-tunnel file.
nano PiVPN-ST.conf
4. The only change that we have to make here is the AllowedIPs line. By default, AllowedIPs is set as 0.0.0.0/0 which means that all traffic will go through your home network (full-tunnel VPN). To change this so that only local traffic is sent through WireGuard, we need to change this line to our local IP range.
For most people, it will be 192.168.1.0/24 or 192.168.0.0/24. If you aren’t sure what your IP range is, you can look in your router’s configuration under LAN Setup.
If you’d like to have VPN clients talk to each other, you need to add the VPN subnet as well (10.6.0.0/24). Change this file to have your local IP range and save it.
5. The configuration file setup process is now complete!
Persistent Keep-Alive
WireGuard attempts to be as quiet as possible, meaning that it only sends and receives packets when it needs to. For this reason, clients behind a NAT or firewall might be required to keep the connection alive even when it’s not in use. To do this, you need to make a change in the configuration file.
A scenario where this is normally needed is when you have an off-site server that always needs to stay connected to your VPN server. This line will ensure the connection will not close.
1. Run these commands to open the configuration file.
sudo su
nano /etc/wireguard/wg0.conf2. You will see the VPN profiles that you configured. Add the line below to the profiles where you would like the connection to stay active.
PersistentKeepalive=25
5. Port Forwarding & Router Changes
We now need to port forward UDP port 51820 on our router to our Raspberry Pi. Port forwarding will be completely different on every brand’s router settings page.
This is a great guide that shows how to port forward on a few different brands of routers, but the best thing to do is try and google the name of your router and port forwarding. Example: Netgear port forwarding
- Create a port forwarding rule for UDP port 51820 to your Raspberry Pi’s IP address. In the example below, 192.168.1.30 is the IP address of my Raspberry Pi.
Static Route Configuration
This step is not required unless you need to access VPN devices from your home network. This is an old screenshot, so ignore the IP addresses listed and ensure you are putting the correct info into yours.
Your home network and VPN network will be on different subnets which means that your local devices will only be able to talk to the machines on its subnet (VPN network will see both).
In order to have your local network talk to your VPN network (in my case, 192.168.1.X and 10.5.0.X), a static route will need to be configured in your router.
I cannot go over the setup steps for this as each router is different, but below is a screenshot of the static route that I configured. The Gateway IP Address will be the IP address of your Raspberry Pi (since that’s where your VPN is running). The 10.5.0.0/24 subnet is where you will need to enter the IP range you are using (as defined in the WireGuard).
6. Accessing/Testing WireGuard VPN Config Files
WireGuard offers applications for almost all devices that you can use. They are fairly basic, but ultimately, you only need to use them to connect to your VPN so there’s no need for them to be complex!
WireGuard Mobile Application
One of my favorite WireGuard features is the ability to generate a QR code and scan that code with your phone. It makes everything so much easier. Not that dealing with config files is particularly hard (and there are situations where you will still need to use config files), but taking out your phone and quickly scanning a QR code is awesome.
If you’d like to generate a QR code to scan, it’s pretty easy. First, ensure that you have the WireGuard application installed on your phone or tablet.
1. Run this command to generate a QR code.
pivpn -qr [PROFILE_NAME]
2. A QR code will be generated. Scan this code with your phone, import the profile and you’re done!
NOTE: This QR holds all information to connect to your WireGuard Raspberry Pi VPN. Do not share this image with anyone unless you’d like them to get your VPN profile.
There are situations where the QR code does not pass the correct information to the mobile client. Ensure that the information in the mobile client is correct before proceeding.
3. Scan the QR code with the WireGuard smartphone application. Add the new entry and connect using an outside network. You should be able to connect to all of your local resources!
NOTE: If you test the split-tunnel config file, your external IP address should be your cell phone providers and if you test the full-tunnel, it should be your home ISP’s IP address.
WireGuard PC/Mac Application
If you are setting it up on a PC, you will need to copy the config files over to your device and add them to the application. You can download the application for your device here.
NOTE: You don’t need to physically copy the file, you can simply copy the contents of the file and create your own [VPN_PROFILE].conf file if it’s easier.
WireGuard Performance
You might feel that the performance isn’t as “fast” as you expected. The reason is that you’re limited by the upload speed of your local network and there is a loss in performance from the traffic encryption of the WireGuard VPN server.
For example, if your ISP provides 25Mbps upload speeds, your download speeds through the Raspberry Pi VPN tunnel will be capped at a maximum of 25Mbps (real-world usage will be less).
This doesn’t mean that the performance will be bad, but you will certainly have slower speeds than you would if you were sitting at home on your local network.
At this point, you should have WireGuard set up and configured on your Raspberry Pi. If you have any questions, please leave them in the comments!
