# How to Set Up WireGuard VPN with PiVPN on Raspberry Pi

> Easily set up WireGuard VPN with PiVPN on Raspberry Pi. PiVPN automates installation, configures NAT, and simplifies client management for secure remote access using simple commands.

- Repository: [Michael Royal/Self-Hosting-Guide](https://github.com/mikeroyal/Self-Hosting-Guide)
- Tags: how-to-guide
- Published: 2026-06-17

---

**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`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main//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`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main/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:

```bash
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:

```bash
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`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main//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:

```bash
pivpn add

```

This generates a client configuration file at [`/home/pi/configs/myphone.conf`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main//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:

```bash
pivpn -c

```

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

```bash
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:

```bash
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`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main//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`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main//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`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main//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.