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.

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

  1. install the WireGuard software on your client system, then
  2. create the client configuration on the server and
  3. 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

  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

Blocking Internet Access

Replace the following line in your client configuration: AllowedIPs =, ::0/0 with AllowedIPs = [...], where [...] is the IP and netmask of your LAN, for example 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 = (assuming is your gateway IP).

Alternatively you can change /etc/hosts file and add <IPAddress> <hostname> Example:   MyRouter   PCSystem01   PCSystem02   LivingroomPC   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>

  1. Backup the current (new instance) install: sudo cp -r /etc/wireguard /etc/new_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


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.