pivpn

Add a new client device

$ sudo pivpn add

$ sudo pivpn list

$ sudo pivpn clients

$ sudo pivpn revoke

$ sudo pivpn uninstall

pivpn command [options]
pivpn install

install
    Initiates the interactive PiVPN setup wizard to configure your OpenVPN or WireGuard server.

add [nopass]
    Creates a new VPN client configuration file. The nopass option creates a client without a password (OpenVPN) or passphrase (WireGuard).

list / clients
    Displays a comprehensive list of all configured VPN clients, including their current connection status.

revoke
    Revokes an existing client's certificate or key, immediately disabling their access to the VPN server.

debug
    Runs a diagnostic script to check the PiVPN setup and server status, providing useful information for troubleshooting.

uninstall
    Removes all PiVPN configurations, installed packages, and associated files from the system.

update
    Updates the PiVPN script itself to the latest version, ensuring you have the newest features and bug fixes.

upgrade
    Upgrades the underlying system packages using the system's package manager (e.g., apt update && apt upgrade).

qr
    Displays the QR code for a specified WireGuard client configuration, facilitating easy setup on mobile devices.

disconnect
    Disconnects a currently connected OpenVPN client.

enable client_name
    Enables a previously disabled WireGuard client, allowing it to connect to the VPN.

disable client_name
    Disables an active WireGuard client, preventing it from connecting until re-enabled.

help
    Shows a list of available PiVPN commands and their basic usage.

PiVPN is a script designed to simplify the process of setting up and managing a personal VPN server using either OpenVPN or WireGuard protocols. It automates the complex configuration steps on a Raspberry Pi or other Debian-based systems, including certificate generation, client profile creation, and firewall rules. The tool aims to make VPN server deployment accessible to users who want to secure their internet traffic, bypass geo-restrictions, or access their home network remotely. PiVPN provides a user-friendly command-line interface with interactive prompts for initial installation and various commands for ongoing management tasks such as adding, revoking, or listing VPN clients. It handles the generation of client configuration files (.ovpn for OpenVPN, plain text/QR for WireGuard) for easy distribution to client devices, ensuring a seamless setup experience. Regular updates help maintain security and compatibility.

• Requires a clean installation of a Debian-based OS (e.g., Raspberry Pi OS, Ubuntu Server) for optimal results.
• Should ideally be run on a dedicated machine or a virtual private server (VPS) to avoid conflicts with other services.
• Requires root privileges to install and manage the VPN server.
• Port forwarding might be necessary on your router if the server is behind a Network Address Translation (NAT) device.

PiVPN automates the generation of client configuration files. For OpenVPN, it creates .ovpn files that can be imported directly into OpenVPN client applications. For WireGuard, it provides plain text configurations or QR codes, which simplify setup on various devices, especially mobile phones.

During the initial installation, PiVPN prompts the user to choose between deploying an OpenVPN or WireGuard server. This flexibility allows users to select the protocol that best fits their needs regarding speed, security, and client compatibility.

PiVPN was initially developed to streamline the installation and management of OpenVPN servers specifically for Raspberry Pi devices, making personal VPN deployment accessible to hobbyists and home users. Over time, its functionality expanded to include support for the WireGuard protocol, offering a more modern and performant VPN option. The project has consistently focused on user-friendliness, automation, and broad compatibility with various Debian-based distributions, solidifying its reputation as a go-to solution for setting up personal VPNs.

openvpn(8), wg(8), apt(8), systemctl(1), ip(8)