FAQ (Frequently asked questions)
What boards/OSes does PiVPN support?
PiVPN runs at least on the following hardware
- Raspberry Pi models (1/2/3/4/Zero)
- All SBC's supported by DietPi.
- x86_64 (Intel and AMD) servers
PiVPN Supports the following systems
- Raspbian and Raspberry PI OS
- Ubuntu Server
- Bionic Beaver (18.04)
- Focal Fossa (20.04)
- Jammy Jellyfish (22.04)
- Alpine Linux
What about other Debian / Ubuntu based distributions?
PiVPN may be able run and install VPN Protocols on any other Debian or Ubuntu based distributions however we do not provide support for them.
What about docker?
Support for docker images is currently experimental and we do not provide any official images or official support. There is no ETA for full support.
What About Octopi?
As per Github Issue #373 on Octpi OctoPi doesn't play well with PiVPN installer as they use a git wrapper that blocks it from running as root user. To disable the git wrapper please do:
sudo rm /root/bin/git
Can I have Wireguard and OpenVPN at the same time?
Yes! All you have to do is to run PiVPN installation again. PiVPN will ask you what intend to do and setup everything for you. After the installation is finished all you have to do is to use
pivpn wg [options] and
pivpn ovpn [options] to manage each protocol.
# pivpn help ::: To pass off to the pivpn command for each protocol ::: ::: Usage: pivpn wg <command> [option] ::: Usage: pivpn ovpn <command> [option] ::: ::: -h, help Show this help dialog ::: -u, uninstall Uninstall pivpn from your system! ::: -bk, backup Backup VPN configs and user profiles
My ISP doesn't give me a static external IP address and my server IP address keeps changing!
You will need a dynamic DNS service and a hostname. If your IP address changes, your hostname will then automatically point to the new IP address. Some free dynamic DNS services are http://noip.com, http://freedns.afraid.org/ or https://www.duckdns.org/.
Refer to: https://help.dyn.com/ddclient/
apt-get install ddclient
/etc/ddclient.conf example config:
# Configuration file for ddclient generated by debconf # # /etc/ddclient.conf ssl=yes protocol=dyndns2 use=web, web=checkip.dyndns.com, web-skip='IP Address' server=members.dyndns.org login=username password='password' mydyn.domain.com
If you use a namecheap domain your ddclient setup can be found here.
How do I troubleshoot connection issues?
- Confirm that all checks are [OK] using
In our case:
$ pivpn -d [...] :::: Self check :::: :: [OK] IP forwarding is enabled :: [OK] Iptables MASQUERADE rule set :: [OK] OpenVPN is running :: [OK] OpenVPN is enabled (it will automatically start on reboot) :: [OK] OpenVPN is listening on port 1194/udp ============================================= [...]
If your debug log shows some [ERR], accept the [Y/n], run
pivpn -d again and verify that all checks pass. If not, stop here and look up the error (if you get any) among existing issues or open a new issue.
- Verify that the server is running.
- OpenVPN, restart the server with
sudo systemctl restart openvpn, run
pivpn -dand confirm that the snippet of the server log ends with
Initialization Sequence Completed.
- WireGuard, restart the server with
sudo systemctl restart wg-quick@wg0. Run
lsmod | grep wireguardand confirm that you get at least this output (numbers don't matter).
wireguard 225280 0 ip6_udp_tunnel 16384 1 wireguard udp_tunnel 16384 1 wireguard
- Acquire the installation settings using
cat /etc/pivpn/wireguard/setupVars.confif using WireGuard or
cat /etc/pivpn/openvpn/setupVars.confif using OpenVPN.
[...] IPv4dev=eth0 <--- Network interface you have chosen IPv4addr=192.168.23.211/24 <--- IP address of the Raspberry Pi at the time of installation (only consider the 192.168.23.211 part) IPv4gw=192.168.23.1 <--- Gateway IP, which you will type into a web browser to open the management interface pivpnPROTO=udp <--- Protocol you need to use in the port forwarding entry pivpnPORT=1194 <--- Port you need to forward pivpnHOST=192.0.2.48 <--- Public IP or DNS name your clients will use to connect to the PiVPN [...]
- Check that the current IP address of the interface
IPv4devis the same as
IPv4addr. You can see the current IP with
ip -f inet address show IPv4dev.
In our case:
$ ip -f inet address show eth0 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 `inet 192.168.23.211/24 brd 192.168.23.255 scope global dynamic eth0 valid_lft 84694sec preferred_lft 84694sec
192.168.23.211 is the same as the content of the
If it's not the same, go to your router admin webpage and reserve the static IP
IPv4addr to the MAC address of the
IPv4dev interface. To show the MAC address:
cat /sys/class/net/IPv4dev/address. Then reboot the Raspberry Pi.
- Check that the current public IP of your connection is the same as
pivpnHOST. To check the current public IP:
curl -s https://checkip.amazonaws.com.
In our case:
$ curl -s https://checkip.amazonaws.com 192.0.2.48
192.0.2.48 is the same as the content of the
If you are already using a DDNS, and thus
pivpnHOST contains your domain name, use
dig +short yourdomain.example.com to check whether the returned IP matches
curl -s https://checkip.amazonaws.com.
We will use
tcpdump to take a peek into the network interface to see if packets are reaching our Raspberry Pi.
First off, if you want to test the connection using your smartphone as a client, make sure to use MOBILE DATA, do not test from the same network where the Raspberry Pi is located. If you want to use a PC, connect to the internet via TETHERING/HOTSPOT.
Connecting from the same network as the server not only doesn't make sense (you are already inside the network the VPN is supposed to connect you to) but may not work with many routers.
From your device, go to https://ipleak.net and check what's your IP address, let's say we have 192.0.2.45.
- Open a root shell:
- Install tcpdump:
apt install tcpdump -y
tcpdump -n -i IPv4dev pivpnPROTO port pivpnPORT(it will block the terminal but don't worry)
- Try to connect from your device
- Shortly after you should see some packets being exchanged between your Raspberry Pi and your device
In our case:
# tcpdump -n -i eth0 udp port 1194 tcpdump: verbose output suppressed, use -v or -vv for full protocol decode listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes 10:57:38.952503 IP 192.0.2.45.28050 > 192.168.23.211.1194: UDP, length 32 <--- Your device sent a packet to the Raspberry Pi 10:57:49.109202 IP 192.168.23.211.1194 > 192.0.2.45.28050: UDP, length 128 <--- Your Raspberry Pi responded to your device 10:57:49.144774 IP 192.0.2.45.28050 > 192.168.23.211.1194: UDP, length 128 10:57:59.490185 IP 192.168.23.211.1194 > 192.0.2.45.28050: UDP, length 32
You are looking at udp or tcp packets coming to your Raspberry Pi on the port you specified, via the network interface (ethernet or wifi) you chose. The example output above is a successful conversation.
Here's an unsuccessful one (no packets reach the Raspberry Pi):
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
- Press CTRL-C to stop the capture
- Exit the root shell:
On some networks, you may see that packets are being exchanged, data transfer occurs in both directions (Rx/Tx) as seen in the WireGuard app or
pivpn -c, but can't browse the web or connect to servers in the LAN. This is sometimes caused by improper MTU. To attempt a fix, start from the default MTU of 1420 and lower the value by 10 until you find the highest that works. The MTU can be changed by adding/editing the
MTU = something line of the
[Interface] section of the client
.conf file, or by changing the MTU section in the WireGuard app on Android and iOS.
What to do if I see no packets?
- If you set up PiVPN with ethernet and later switched to wifi, you will have a different IP. Easiest way to fix is to reinstall and pick the new network interface.
- Check if your ISP uses Carrier-grade NAT (check online). With CGNAT, your router gets a private IP, making port forwarding ineffective. This is mostly the norm if your router connects via 4G/LTE. If that's the case, you need to ask the ISP for a public IP.
- If you see packets coming to the Pi, but no response to the smartphone, it may indicate routing issues, attempts to block the connection (on either side), poor connectivity. In all cases, try to connect from a different network. It may also indicate misconfigured keys though this shouldn't happen with the official scripts.
- If you have multiple chained routers, then you need to configure multiple port forwardings. Example:
(192.0.2.48) ISP router (192.168.1.1)--->
(192.168.1.2) Own router (192.168.23.1)--->
(192.168.23.211) Raspberry Pi. Given that, on the ISP router port forward 1194 udp to 192.168.1.2 and on your own router port forward 1194 UDP to 192.168.23.211.
- You may have misconfigured firewall rules on your Pi, open an issue and add the output of
sudo iptables -Sand
sudo iptables -t nat -S.
If you performed all the following steps and suggestions, but you still can't connect, open a new issue showing all the steps you followed to troubleshoot. Include the packet capture as well (censor client IPs if you want). Remember to follow the ISSUE TEMPLATE.