PiVPN / WireGuard Complete Setup 2022

This tutorial will show you how to install your own personal Raspberry Pi-based VPN into your network using PiVPN and WireGuard. Why would you want to do this? A number of reasons – remote access to your local servers and files, surfing through your own Internet connection when on the road, and just general good security practices!

None of this would be possible of course without the PiVPN project which you can find at https://pivpn.io. This project is maintained to be a simple and easy solution for getting OpenVPN or WireGuard VPN services running on a Raspberry Pi – plus it’s a really fun project! Consider contributing to the PiVPN project by clicking here: https://github.com/pivpn/pivpn/blob/master/CONTRIBUTING.md

Prerequisites – here’s what you need to get started!

(1) Raspberry Pi – recommend the Raspberry Pi 4 w/2GB RAM which is what I’m using for this tutorial. These Raspberry Pi devices can be difficult to get your hands on, but you can check where to purchase them here: https://www.raspberrypi.com/products/raspberry-pi-4-model-b/

(1) microSD card – recommend a 32GB class 10 microSD card such as this one: https://geni.us/dudGT – you will also need a microSD card reader to get it initially provisioned with the Raspberry Pi OS.

Keyboard/monitor hooked up to the Raspberry Pi is optional, but recommended – just makes everything a bit easier! Once you’re past the initial setup, you won’t need a keyboard/monitor connected anymore.

30-60 minutes – this project is fairly easy! I would give it a 4 out of 10 on the difficulty scale. It does require some knowledge of networking technologies, firewall rules, etc., but nothing too severe.

Part 1 – Install Raspberry PI OS Lite (32-bit)

Using a separate PC (I’m using Windows 10 in this tutorial), insert your microSD card into a microSD card reader.

NOTE: All data on the microSD card will be destroyed – make sure this is a microSD card you are OK with erasing! 

Download and install the Raspberry Pi Imager: https://www.raspberrypi.com/software/ – v1.7.1 as of the writing of this article.

Run the Raspberry Pi imager – we’ll need to select the OS we want, the microSD card as the destination, and then some additional settings.

Operating System:  Raspberry Pi OS Lite (32-BIT)
  (Available under Raspberry Pi OS (other)

Storage:  Choose your microSD card drive

Click the gear icon for settings.

Set the following settings (anything unmentioned can remain default):

Set hostname:  pivpn.local

Check ‘Enable SSH’

  • Use password authentication

Check ‘Set username and password’

  • Set a username if you want, or just leave the default ‘pi’
  • Set a password – this will be used to log into your PiVPN once it’s up and running

Check ‘Set locale settings’ and set your time zone/keyboard layout:

NOTE:  We’re specifically not using WiFi for this – I have not tested it, and I highly recommend just plugging in a network cable for the most reliable VPN connection.

Click ‘Save’ at the bottom and then click ‘Write’ to write the OS to your microSD card.

Part 2 – Boot the Raspberry Pi and Log In

From here, you can either use a keyboard and mouse with a monitor plugged into the Pi, or you can SSH in.  If you want to SSH in, you’ll need to know the Pi’s IP address – this can be found a number of ways, but most commonly, you will find the IP that was given to the Pi via DHCP by checking out your DHCP lease table, or you can temporarily hook up a keyboard/mouse/monitor, log in and run the command:

ip a

to get the IP address.

NOTE: Speaking of IP A (see what I did there?) – if you are enjoying this tutorial and are looking forward to secure VPN connectivity into your network, consider buying me a beer!

Once booted, login as ‘pi’ and the password that you set in step 1.  (Either by using a directly connected keyboard and mouse, or by SSHing to the IP address of your Pi)

Part 3 – Update the Raspberry Pi

Let’s get everything updated!  Run this command:

sudo apt update && sudo apt upgrade -y

This will take a few minutes to complete.

Part 4 – Install PiVPN

Run the following command:

curl -L https://install.pivpn.io | bash

This will start the PiVPN installation wizard.

Click OK.

First step is to set a static IP on your PiVPN server.  Click OK.

Setting a static IP address basically means that we want PiVPN to run on an IP address that will never change.  This is because we will be setting up a firewall rule that allows traffic to flow through to the PiVPN.  

You can achieve an IP address that never changes by manually setting an IP address that is outside of your DHCP lease pool range, or by telling DHCP that the IP address assigned to your PiVPN server should never change (this is called a DHCP reservation).

For this tutorial, we will set a static IP address, so we will choose ‘No’ on this screen.

In this example, is the IP address that was given to my PiVPN by the network’s DHCP server.  Since we want to set up a static IP, we will have to change this IP to something different.  So choose ‘No’ because we don’t want to use the DHCP IP address for the PiVPN.

I have set the IP address to in this example, which is an unused IP address outside of my network’s DHCP pool range.

Click OK.

Next, set your gateway IP (it should already be correct) and click OK.

If everything looks OK on the summary screen, click Yes.

Next, we’re going to have to choose a local user for our VPN configurations – since we only have 1 user at this point, just click OK and then choose the Pi user on the next screen.

Click OK.

Next, we want to choose whether we’re going to use WireGuard or OpenVPN as our VPN software.  WireGuard is what we’re going to use here – it is newer, faster, and lighter than OpenVPN.

Click OK.

Next, we can select a WireGuard port – UDP 51820 is the default, so we’re just going to leave that and click OK, but you can choose a different port if you want.  Just keep in mind that your firewall rule will have to reflect whichever port you choose here.

Click Yes to confirm those settings.

Next, the wizard will ask us to choose a DNS provider for name resolution.  You can pick whichever one of these options you want, but I am going to choose ‘CloudFlare’ for this tutorial.

Click OK.

Next, the wizard wants to know if we’re going to connect to PiVPN using a DNS name (FQDN) or a WAN IP address.  If you have a static WAN IP address from your ISP, then just choose IP.  But, if you do not have a static IP address, you’ll want to use a DNS name – either one that you control yourself, or a dynamic DNS name.  

Here are the instructions for either way:

Static IP

Select your IP and click ‘OK.’  

DNS Entry

Select DNS Entry and click OK.

Enter in the FQDN for your PiVPN server and click OK.

Confirm the DNS name by clicking ‘Yes.’

Now your server’s encryption keys will be generated.  Click OK.

Next, we get a warning message about exposing this server to the Internet.  Since we will have a port open through to this server, it is recommended that unattended-upgrades are enabled on the server.  This way, any security vulnerabilities will be patched automatically.

Click OK.

Click Yes.

The final screen tells us that we can run ‘pivpn add’ to add VPN users to PiVPN.  We will get to this, but first we need to reboot since we changed our static IP address.  Click OK.

Click Yes to reboot.  Followed by OK to confirm.

Part 5 – Add VPN users

Reconnect to your PiVPN server via SSH.

***NOTE:  Remember that if you changed your IP address to a static IP, you’ll have to connect to the NEW IP address this time around!  In my case, I had set the IP to, so I will be connecting to that new IP.

Run this command to add users:

pivpn -a

You will be prompted to enter a name for the client – we’ll call our client ‘client1’ for this example.  Ideally, you will have a separate client/user for every device that connects to your PiVPN.

That’s it!  Repeat this step for every user you want to create.

Part 6 – Firewall changes

PiVPN / WireGuard requires a port open through your firewall.  By default, the port is UDP 51820.  Every router/firewall will have an option to port forward through your WAN interface into your LAN, and this process will be different depending on the model of router/firewall you have.

If you don’t know how to port forward through your firewall, just Google ‘[router model] port forward’ and you should find instructions – it’s a very common process.

In my case, I have an EdgeRouter 4 – to port forward, I go to the Firewall/NAT tab → Port Forwarding tab.

I entered these settings:

WAN Interface (1): eth0 (your WAN port)

LAN interface (2):  eth1 (your LAN port or VLAN)

Port forwarding rules (3):

Original port:  51820 (the port external traffic will come in on)

Protocol:  UDP

Forward-to address: (the IP of the PiVPN)

Forward-to port:  (leave blank since the destination is the same port as the source)

Description:  PiVPN

Click ‘Apply.’ (4)

Part 7 – Connect devices

The PiVPN is all set up and ready to receive clients!  So now let’s connect our devices. 

NOTE:  This article assumes that the devices you’re connecting from are NOT in the same network as your PiVPN.  For example, if you’re trying to connect with an iPhone, you may want to disable WiFi and try connecting over LTE instead.

Connect with QR code

PiVPN has an excellent feature that generates a QR code for easy connectivity.  If you’re using a device that has the WireGuard app installed, it can add new VPN connections by scanning that QR code.  You can generate the QR code in SSH and then scan it on your screen, or print it out for your users.

To generate the QR code for a user, run this command:

pivpn -qr

Then, select the user you want to generate the QR code for.

In the WireGuard app, click ‘Add a tunnel.’  Then choose ‘Create from QR code.’  Scan the QR code, and follow the prompts, and you’re good to go!  Connect your VPN and you should now be able to see devices on your network.  If you go to a website such as https://whatismyip.com, you should see the WAN IP address of your home network.

Try to ping around your network now – you should be able to see any LAN connected devices. If you can NOT ping other devices (like your LAN’s gateway), then run this command

pivpn -d

That will run through a quick debugging wizard that checks settings. Any settings that aren’t set correctly, it will fix. For instance, I have had a couple of times where the IPTABLES rules were not set properly during the install wizard – but running pivpn -d fixed everything.

Connect with conf file

If you don’t have a device that can scan a QR code (like a Windows/Mac/Linux desktop PC), then you can connect to your Pi and download the configuration file manually.

To do this, I am using a program called WinSCP in Windows (it’s free to download and install).  After you download, install, and launch WinSCP, you’ll be prompted to connect to a server.  Change the File Protocol to SCP, enter in the IP address of your PiVPN, and then type your ‘pi’ username and password – then click ‘Login.’  Accept any windows that pop up about connecting to a new server.

Once connected, you’ll see a ‘configs’ folder in the right-hand window pane.  Double-click ‘configs’ and you should see configuration files (user.conf) for your PiVPN users.  Download those configuration files to a safe and secure location.

Download and install the Windows WireGuard client, then click ‘Import tunnel(s) from file.’  

Browse to the file that you downloaded and double-click it.  You should now see it imported in your WireGuard client.  

Click ‘Activate’ to activate the tunnel.  Your Windows machine should now be connected to the PiVPN server, and should have access to your local LAN!

If you go to a website such as https://whatismyip.com, you should now see the WAN IP of your PiVPN network.

If you want to see a list of all connected clients in PiVPN run this command:

pivpn -c

And you should see everyone who is currently connected.

That’s it!  You’re all done.

Part 8 – Back up your PiVPN server

Well….not quite done yet.  Because you wouldn’t want to skip backups right?  RIGHT?!?

Run this command:

pivpn -bk

This will create a backup TGZ file that contains your PiVPN configs and user profiles. The backup file is created in /home/pi/pivpnbackup.  Download that file with WinSCP and save it in a secure location – you’ll also want to be sure to make a new backup anytime you make significant changes to your PiVPN configuration.

Enjoy this tutorial?

Comments 21

  1. Thank you for the tutorial . i have a doubt , i live in a rural area and only use 4g for internet through smartphone , so, is the ip address provided by my network provider is static or not. how can i do this port forwarding thing without a router.

  2. Is there a way I can set this up so my network server can connect with a third party VPN ( to give me different ip addresses)

  3. Great tutorial.

    I am having an issue where my server has 2 networks. Really need this as one of the networks does not have active internet access. I am able to browse but not

    How do i configure my PiVPN server to allow both networks to be accessed

  4. I’ve tried this many times, but can never get past the point where I select the wireguard vs. openvpn. I select wireguard, and it hangs. It happens regardless of what host I’m using, raspberry pi 4b (lite os, both 32 bit and 64 bit, both buster and bullseye), and a virtual machine on PC from ISO (buster), or virtual machine on my NAS. They all hang in the same spot.

  5. I’m a little confused. I got through the whole tutorial with no issues, but when do you set a password for the client? Shouldn’t there be a username and password to actually sign on to the VPN?

  6. i did not have the privilege’s to open the configs folder when using WinSCP. i got access denied. any suggestions on how to get the config file copied to my windows machine? thanks in advance,

    1. I had the same problem, first try to check the owner of the configs folder an if it is different from you current user, try this command:
      sudo chown -R youruser:youruser configs

      1. Doesnt the ownership go from root to Pi then? I did: sudo chmod -R 755 configs
        After that I could access the folder as Pi but I believe root is still the owner…

  7. Just wanted to say I followed two other guides for installing WireGuard on an RPi (3b and 4b) running bullseye and no VPN connection could be established.

    This guide resulted in success on both RPis the first time with multiple client peers (iPhone and two laptops).

    I also run WireGuard as a docker container on an unRAID server, but, if that is down for some reason, it is nice to have a backup running on an RPi. Fortunately, both my servers have IPMI and I can reach the admin page through WireGuard on the RPi to power on the server if necessary. Two weeks ago there was a power outage when I was out of town that took down my server (on a UPS fortunately), but I no RPi backup then. 🙁

    Thank you.

  8. You could complete the tutorial by explaining how to give permission to download the config files from oracle through WinSCP. because when i connect it does not have permission to download- it does not allow to open the config folder neither. I have tried to add permission through SSH connection to the folder config, now it can enter the folder but still does not have permission to download the config file.

  9. Thanks, but it looks like they are not giving out address anymore. I am getting with a DNS of I tried to update /etc/pivpn/wireguard/setupVars.conf by changing the 10.60.249 entries but that did not help, still got a

  10. Thanks for the tutorial, the only issue I encountered was when it asked if I wanted to use my IP address or DNS I selected DNS and nothing happened, then it didn’t generate the server’s encryption keys. I have PiHole and Unbound on the same Raspberry Pi 4, so I don’t know if that would cause this.

  11. This work great for me. Your video was very easy to follow. I set it up on an OrangePi 3 LTS.
    used the Debian Bullseye server linux https://drive.google.com/drive/folders/1ctuKgHNN9r517tiAv9GGGaR7UYQgZiXP found here.
    Only small issue I had was Router NightHawk R700, for port forwarding you hav to first add it then go back and edit to select UDP and the port. Worked great after that. Well one other thing was trying to add the vpn to my Galaxy Tablet the camera would not scan that big QR code lol.

    on site question since you would have way more YouTube knowledge then me, whenever I try to comment on something. I click comment and it the page re-directs back to the main youtube.com page.

    But I did make sure to at least like and subscribe.

    Thanks again all the videos I have watched are very wasy to follow.

  12. Just a heads-up. Latest Raspberry Pi-OS Lite is called “bookworm” and it uses Network Manager instead of dhcpcd. This means you can’t change IP address within the PiVPN installation. You will get an error message stating that it can’t find /etc/dhcpcd.conf and the install program will quit. To get the installation to proceed beyond this point, create the file (touch /etc/dhcpcd.conf) and restart the PiVPN installation.

    To change the IP address, run “sudo nmtui”.

    I’m sure this will be handled by the PiVPN team soon but…

  13. Hi and thank you for the tutorial.
    Regarding your note
    “NOTE: This article assumes that the devices you’re connecting from are NOT in the same network as your PiVPN. For example, if you’re trying to connect with an iPhone, you may want to disable WiFi and try connecting over LTE instead.”

    How can I make it work for my local network? Currently, when I enable the VPN and I’m on WiFi in my local network, I can’t reach the internet. I’d like to use the VPN for requests from my network too.

    Thank you!

Leave a Reply

Your email address will not be published. Required fields are marked *