Once you are running your own VPN server based on PiVPN and WireGuard you want to manage clients to connect to the VPN server. This article covers some aspects about configuring WireGuard clients with PiVPN.
Important information: This article is about the PiVPN, a nice pre-defined script for easy install of WireGuard VPN on a Raspberry Pi and other systems with similar Linux versions. Beginning of April 2024 it was announced that PiVPN is no longer maintained. Find more information here: Release v4.6.0: The end · pivpn/pivpn · GitHub!
We will review options and alternatives and we keep you updated on our website www.airix.net!
The abbreviation VPN stands for Virtual Private Network which means an encrypted connection over the internet from a device to a network. To connect from outside into your home network, the only trusted option for us is to run your own VPN server on your home server. Once your are connected and "tunneled" into your business or home network you have access to its local network resources, while the local resources don’t have to be exposed directly to the Internet.
To install your own VPN server at your home, you can use the approach from the PiVPN project. PiVPN is a project to simplify the VPN installation of WireGuard or OpenVPN on a Raspberry Pi. In principle it is just a collection of shell-scripts to make the installation and configuration much easier.
The article Run your own VPN Server at Home on a Raspberry Pi covers the installation of your own VPN server at home on Raspberry Pi with WireGuard and a PiVPN installation.
WireGuard Client Install
You normally have to
- install the WireGuard software on your client system, then
- create the client configuration on the server and
- transfer the configuration files onto the client.
Install the WireGuard software on the client
To use WireGuard on your client, you need to install the WireGuard software on the client. Note that the WireGuard software you will need depends on the client's operating system, but that there is no distinction between a WireGuard software for servers and clients as they can perform as a server and as a client.
The entry point to install the respective software is available on the WireGuard home page: https://www.wireguard.com/install/
Create the Client Configuration
List of Commands of WireGuard PiVPN
On the command line of your VPN server you get the following overview with the command pivpn help
-a, add Create a client conf profile
-c, clients List any connected clients to the server
-d, debug Start a debugging session if having trouble
-l, list List all clients
-qr, qrcode Show the qrcode of a client for use with the mobile app
-r, remove Remove a client
-h, help Show this help dialog
-u, uninstall Uninstall pivpn from your system!
-up, update Updates PiVPN Scripts
-bk, backup Backup VPN configs and user profiles
Creating New Client Configuration
pivpn add
This command is to add a new client to the server and create a respective configuration file for the client.
This command will prompt 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 the home directory.
When you are using the WireGuard mobile app on iOS or Android, the command pivpn qrcode is useful. It shows the QR-code of a client configuration and you can easily scan the code with your mobile device.
Listing Clients
pivpn clients
You get a list of the clients and if they are connected also some additional connection information (Remite IP, Bytes Received, Bytes Sent).
pivpn list
Get a list of clients' names and associated keys.
Remove a Client Configuration
pivpn remove
The command asks 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 example: 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 if you suspect that a key may have been compromised in any way, just remove it and generate a new one.
Create a Server Backup
pivpn backup
Creates a backup archive of the WireGuard settings and slient certificates, and places it on your pivpn user home directory
Help with Troubleshooting
pivpn debug
Outputs setup information for troubleshooting.
Transfer the Client Configuration onto the Client
On a mobile device (e.g. iOS, Android) while using a the WireGuard app you can scan the QR code for the respective configuration show with
pivpn qrcode
For other devices you may need to transfer or copy the client's configuration file (this is normally stored in sub-folder configs of the pivpn user's home directory) and transfer the file onto your client system.
Keep the WireGuard configuration file secret, because this file is the key to connect to your VPN server.
Advanced Configuration Changes
Changing the public IP address or public DNS name of your server
- Edit the PiVPN configuration with
sudo nano /etc/pivpn/wireguard/setupVars.conf - Update the
pivpnHOST=[...]line - Save and exit
New clients you generate will use the new endpoint but you need to manually edit existing clients:
- Open your configuration, for example whatever.conf
- Update the line
Endpoint = [...]:51820 - Save the file and connect again
Blocking Internet Access
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).
Resolving 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 MyRouter
192.168.1.2 PCSystem01
192.168.1.3 PCSystem02
192.168.1.4 LivingroomPC
192.168.1.5 BedroomPC
Migrating WireGuard and PiVPN to a New Server
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>
- Backup the current (new instance) install:
sudo cp -r /etc/wireguard /etc/new_wireguard_backup - Extract the backup archive:
tar xzpfv <archive name> - Copy the extracted content:
sudo cp -r etc/wireguard /etc - Restart the wireguard service:
sudo systemctl restart wg-quick@wg0
Warning:
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.