Mastering the 'pivpn' Command (with examples)

PiVPN is a powerful tool that simplifies the setup and management of a secure VPN. Initially created for the Raspberry Pi, this command-line utility allows you to deploy OpenVPN servers easily on various Linux-based systems. Its primary goal is to save time and minimize the complexity of VPN setup with its straightforward command syntax and user-friendly approach. With PiVPN, you can add new clients, manage connections, and even uninstall the VPN service if needed.

Use case 1: Adding a New Client Device

Code:

sudo pivpn add

Motivation:

There are times when you want to grant a new device access to your secure network. For instance, if you have just purchased a new smartphone or laptop and wish to secure its communications, or you’re setting up access for a team member, you will need to add it as a client to your existing VPN server. This command helps you create a client profile easily, which can then be used to connect to the VPN.

Explanation:

• sudo: This command requires administrative privileges because it modifies network settings and the VPN configuration.
• pivpn: This is the primary command for interacting with your VPN setup.
• add: This argument specifies that a new client should be added to the VPN. It prompts you through a guided setup to generate a client configuration file that can be distributed to the new device.

Example Output:

Enter a Name for the Client: [device-name]
Enter the password for the client key: 
The ovpn profile will be located at: /home/pi/ovpns/[device-name].ovpn

Use case 2: Listing All Client Devices

Code:

sudo pivpn list

Motivation:

Managing multiple VPN clients can be daunting if you don’t have an organized view of who has access. By listing all devices that have been granted access, network administrators can maintain oversight, audit usage, ensure compliance with security policies, and manage devices effectively on their network.

Explanation:

• sudo: This ensures you have the required permissions to view the VPN client list.
• pivpn: The command to interact with the PiVPN utility.
• list: This argument instructs PiVPN to display a list of all configured VPN clients, providing details such as client names and keys.

Example Output:

::: Certificate List :::

Client Name      Remote IP        Bytes Received     Bytes Sent      Date Expired
client1          192.168.1.10     345B               430B            Dec 31 2023
client2          192.168.1.11     1423B              1542B           Jan 15 2024

Use case 3: Listing Currently Connected Devices and Their Statistics

Code:

sudo pivpn clients

Motivation:

Security-conscious users and network administrators need real-time information about current VPN connections to monitor network activity, detect unauthorized access, and ensure proper usage of resources. This command helps you to obtain live statistics about active clients.

Explanation:

• sudo: Required to access real-time statistics securely.
• pivpn: The command to access PiVPN functionalities.
• clients: Specifies that you want to view information about currently connected VPN clients, including IP addresses and data transferred during the session.

Example Output:

::: Connected Clients List :::

Name        Remote IP       Virtual IP          RX        TX       Connected Since
client1     192.168.1.100   10.8.0.2            245K      164K     2023-09-20 08:14
client2     192.168.1.101   10.8.0.3            53M       21M      2023-09-20 07:20

Use case 4: Revoking a Previously Authenticated Device

Code:

sudo pivpn revoke

Motivation:

There may be occasions when you need to terminate access for a device that previously had VPN access due to security concerns or personnel changes. Revoking a device plays a critical role in maintaining the integrity and security of your network by ensuring that only authorized devices can connect.

Explanation:

• sudo: Administrative rights are needed to modify access permissions.
• pivpn: The command provides access to the PiVPN tool.
• revoke: This argument is used to cancel the credentials and network access rights of a specified VPN client, effectively cutting off its access.

Example Output:

Enter the Name of the client to be revoked: [device-name]
Successfully revoked [device-name]
Certificate for [device-name] has been removed

Use case 5: Uninstalling PiVPN

Code:

sudo pivpn uninstall

Motivation:

Uninstallation may be necessary if you are decommissioning your VPN server or transitioning to a different solution. This ensures that your system does not have unused software occupying resources and that potential access points to your network are safely closed.

Explanation:

• sudo: Required to perform uninstallation tasks that affect system-wide configurations.
• pivpn: Executes the PiVPN tool.
• uninstall: This argument guides you through steps to completely remove PiVPN from your system, cleaning up configuration files and dependencies.

Example Output:

:::
::: PiVPN is now removed from your system. 
::: If you still encounter any issues, please visit https://www.pivpn.io
:::

Conclusion:

The PiVPN command is a versatile tool for administrators who need to manage VPN setups efficiently. Each of the outlined use cases serves a specific aspect of VPN management, from client addition and removal to live monitoring and final uninstallation. By mastering these commands, you can ensure that your VPN setup is secure, streamlined, and adaptable to the ever-changing needs of your network environment.