How to Set Up WireGuard VPN with PiVPN on Raspberry Pi

PiVPN automates the installation of WireGuard on Raspberry Pi, generating server keys, configuring NAT rules, and providing helper scripts to manage client profiles with a single command.

Deploying a personal VPN on Raspberry Pi hardware provides secure remote access to your home network without relying on third-party services. The mikeroyal/Self-Hosting-Guide repository documents how to combine WireGuard's kernel-level cryptography with PiVPN's automation to create a robust, self-hosted VPN server. This guide covers the exact commands and configuration files used to establish the tunnel.

Understanding WireGuard and PiVPN

WireGuard operates at the OS kernel level, utilizing state-of-the-art cryptography to establish secure tunnels between peers identified by public-key/private-key pairs. Unlike legacy VPN solutions, WireGuard deliberately minimizes complexity—there is no certificate authority, no complex handshaking, and each tunnel requires only a handful of lines in a configuration file.

PiVPN is a community-maintained installer that automates WireGuard server provisioning on Raspberry Pi or any Debian-based system. According to the Self-Hosting-Guide source analysis, the installer performs several critical tasks: installing wireguard and wireguard-tools packages, generating persistent server keys at /etc/pivpn/wireguard/server_private.key, creating the server configuration at /etc/pivpn/wireguard/wg0.conf, enabling IP forwarding via net.ipv4.ip_forward=1, and deploying the /usr/local/bin/pivpn helper utility for client management.

Benefits of the PiVPN Approach

• Simplicity: A single command installs and configures the server without manual editing of wg0.conf.
• Safety: The script runs with root privileges only during installation, then drops to regular user permissions for client management.
• Extensibility: You can later add OpenVPN support or integrate with DNS solutions like Pi-hole by editing the generated configuration.

Prerequisites and System Preparation

Before installation, ensure your Raspberry Pi runs Raspberry Pi OS or another Debian-based distribution with internet connectivity. You need root or sudo access to modify system settings and install kernel modules.

Update your package list and install curl, which fetches the PiVPN installer:

sudo apt update && sudo apt install curl -y

Installing WireGuard with PiVPN

The PiVPN installer handles the complex server configuration automatically, including firewall rules and kernel module setup.

Download and Execute the Installer

Fetch and run the official PiVPN installation script:

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

During the interactive installation, you will configure:

• VPN Type: Select WireGuard (optionally OpenVPN is available).
• VPN Subnet: Default is 10.8.0.0/24 for internal addressing.
• Listening Port: Default 51820 UDP.
• Network Interface: Select your internet-facing interface (e.g., eth0 for Ethernet or wlan0 for Wi-Fi).

The installer generates /etc/pivpn/wireguard/wg0.conf, which defines the listening port, internal subnet, and iptables/NFTables rules to NAT traffic from the VPN to the internet.

Managing Client Profiles

After installation, the pivpn command provides complete lifecycle management for client certificates and configurations. You can add new peers, revoke access for lost devices, and export configurations for mobile import without manually editing WireGuard’s underlying configuration files.

Adding a New Client

Create a new client profile by running the add command. The script prompts for a descriptive name (e.g., "myphone"), an optional password, and assigns an IP address within the VPN subnet:

pivpn add

This generates a client configuration file at /home/pi/configs/myphone.conf, containing the public key and tunnel parameters needed for connection.

Listing and Revoking Peers

View all active client profiles to monitor connected devices or audit your current setup:

pivpn -c

To revoke a specific client and immediately remove their access to the VPN tunnel, use the remove command:

pivpn -r myphone

Exporting Configurations for Mobile Devices

Generate a QR code or text configuration for easy mobile import. Transfer the resulting file to your phone and import it into the official WireGuard application to establish the encrypted tunnel:

pivpn -qr myphone > myphone-wg.conf

Key Configuration Files and Paths

Understanding the generated file structure helps with troubleshooting and backups. The following paths contain critical server and client data generated during installation:

• /etc/pivpn/wireguard/wg0.conf: Server configuration defining the interface, port 51820, subnet, and peers.
• /etc/pivpn/wireguard/server_private.key: Persistent server private key used for decrypting client traffic.
• /home/pi/configs/*.conf: Client configuration files ready for import into WireGuard apps.
• /usr/local/bin/pivpn: Main helper binary for adding, revoking, and listing client profiles.

These files persist across reboots, with the server private key maintained securely outside of version control.

Summary

• PiVPN automates the entire WireGuard server setup on Raspberry Pi, from kernel module installation to firewall configuration.
• Server configuration resides in /etc/pivpn/wireguard/wg0.conf, with the private key stored separately at /etc/pivpn/wireguard/server_private.key.
• Client management uses the pivpn command to add, list, revoke, and export profiles to /home/pi/configs/.
• Default networking uses UDP port 51820 and subnet 10.8.0.0/24, with IP forwarding enabled automatically.
• Security relies on modern cryptography via public-key pairs without certificate authority complexity.

Frequently Asked Questions

Can I run PiVPN on systems other than Raspberry Pi?

Yes, PiVPN supports any Debian-based distribution including Ubuntu and Debian itself. The installer detects the underlying system and installs appropriate kernel modules for WireGuard, making it compatible with most ARM and x86 Linux devices.

How do I change the default VPN port from 51820?

During the interactive installation, the script prompts for the listening port. You can specify any unused UDP port. To change it after installation, edit the ListenPort directive in /etc/pivpn/wireguard/wg0.conf and update your firewall rules accordingly.

Where are client configuration files stored and how do I back them up?

Client configurations are stored in /home/pi/configs/ (or /home/<username>/configs/ depending on the installing user). Each .conf file contains the private key and tunnel settings for that specific peer. Back up this directory regularly to prevent lockout, as losing these files requires generating new client profiles.

Is WireGuard more secure than OpenVPN?

WireGuard uses modern, audited cryptographic primitives (Curve25519, ChaCha20, Poly1305) and has a smaller codebase than OpenVPN, reducing the attack surface. However, both protocols provide strong security when configured properly. WireGuard's simplicity offers better performance on resource-constrained devices like the Raspberry Pi.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}