PiVPN

https://docs.pivpn.io/
Admin
PiVPN is a simple, open-source installation script for setting up a VPN server on a Raspberry Pi...
Tokens:8,777
Snippets:126
Trust Score:9.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install PiVPN by cloning the repository

Source: https://docs.pivpn.io/install

Clone the PiVPN repository and then run the installation script from the local copy.

```bash
git clone https://github.com/pivpn/pivpn.git
bash pivpn/auto_install/install.sh

```

--------------------------------

### Automate PiVPN installation with user data

Source: https://docs.pivpn.io/guides/user-data

Use this script to define installation parameters in an options file and execute the unattended installer. Ensure the network interface and user paths match your cloud instance configuration.

```bash
#!/bin/bash

# Create options file
cat << EOF > /tmp/options.conf
USING_UFW=0
IPv4dev=ens5
install_user=admin
install_home=/home/admin
VPN=openvpn
pivpnPROTO=udp
pivpnPORT=1194
pivpnDNS1=8.8.8.8
pivpnDNS2=8.8.4.4
TWO_POINT_FOUR=1
pivpnENCRYPT=256
USE_PREDEFINED_DH_PARAM=1
INPUT_CHAIN_EDITED=0
FORWARD_CHAIN_EDITED=0
pivpnDEV=tun0
pivpnNET=10.8.0.0
subnetClass=24
UNATTUPG=1
EOF

# Install git and clone pivpn repo
apt update && apt install -y git
git clone https://github.com/pivpn/pivpn /tmp/pivpn

# Install PiVPN from options.conf
cd /tmp/ || exit
bash pivpn/auto_install/install.sh --unattended /tmp/options.conf
```

--------------------------------

### Install and Configure OpenVPN on Linux

Source: https://docs.pivpn.io/openvpn

Commands to install the OpenVPN package and set up the secure client directory.

```bash
apt install openvpn
mkdir -p /etc/openvpn/client
chown root:root /etc/openvpn/client
chmod 700 /etc/openvpn/client
```

--------------------------------

### Install PiVPN using direct link

Source: https://docs.pivpn.io/install

This method downloads the install script from a specific GitHub URL and executes it.

```bash
curl https://raw.githubusercontent.com/pivpn/pivpn/master/auto_install/install.sh | bash

```

--------------------------------

### Install PiVPN using curl

Source: https://docs.pivpn.io/install

Use this command to download and execute the PiVPN installation script directly.

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

```

--------------------------------

### Initialize WireGuard on Linux

Source: https://docs.pivpn.io/wireguard

Setup the WireGuard directory and permissions on a Linux host.

```bash
mkdir -p /etc/wireguard
chown root:root /etc/wireguard
chmod 700 /etc/wireguard
```

--------------------------------

### Install PiVPN from Test/Development branch

Source: https://docs.pivpn.io/install

Use this command to install PiVPN from a testing branch. Set the TESTING environment variable to 'bash'.

```bash
curl -L https://test.pivpn.io | TESTING= bash

```

--------------------------------

### Install and Configure ddclient

Source: https://docs.pivpn.io/faq

Commands and configuration for setting up dynamic DNS using ddclient.

```bash
apt-get install ddclient
```

```text
# Configuration file for ddclient generated by debconf
#
# /etc/ddclient.conf

ssl=yes
protocol=dyndns2
use=web, web=checkip.dyndns.com, web-skip='IP Address'
server=members.dyndns.org
login=username
password='password'
mydyn.domain.com
```

--------------------------------

### Install PiVPN from custom Git URL and branch

Source: https://docs.pivpn.io/install

Clone a custom Git repository and install PiVPN using specified Git URL and branch parameters. This is intended for development testing.

```bash
git clone < customgitrepourl >
bash pivpn/auto_install/install.sh --giturl < customgitrepourl > --gitbranch < customgitbranch >

```

```bash
git clone https://github.com/userthatforked/pivpn.git
bash pivpn/auto_install/install.sh --giturl https://github.com/userthatforked/pivpn.git --gitbranch myfeaturebranch

```

--------------------------------

### Inspect PiVPN Setup Variables

Source: https://docs.pivpn.io/faq

Display the configuration file to identify network interface, IP address, gateway, and port settings.

```bash
[...]
IPv4dev=eth0                  <--- Network interface you have chosen

IPv4addr=192.168.23.211/24    <--- IP address of the Raspberry Pi at the time of installation
                                   (only consider the 192.168.23.211 part)

IPv4gw=192.168.23.1           <--- Gateway IP, which you will type into a web browser to open
                                   the management interface

pivpnPROTO=udp                <--- Protocol you need to use in the port forwarding entry

pivpnPORT=1194                <--- Port you need to forward

pivpnHOST=192.0.2.48          <--- Public IP or DNS name your clients will use to connect to
                                   the PiVPN
[...]
```

--------------------------------

### Unattended PiVPN Installation

Source: https://docs.pivpn.io/install

Perform a non-interactive PiVPN installation using a configuration file. Ensure the script is executable.

```bash
curl -L https://install.pivpn.io > install.sh
chmod +x install.sh
./install.sh --unattended options.conf

```

--------------------------------

### Install PiVPN Dependencies on Alpine Linux

Source: https://docs.pivpn.io/install

Install required packages like bash, busybox-initscripts (or busybox-openrc), and sudo on Alpine Linux. Ensure correct busybox version is used.

```bash
apk add bash

```

```bash
apk add busybox-initscripts

```

```bash
apk add busybox-openrc

```

```bash
apk add sudo; echo '%wheel ALL=(ALL) ALL' > /etc/sudoers.d/wheel

```

--------------------------------

### Install PiVPN Dependencies on Alpine with doas

Source: https://docs.pivpn.io/install

On AWS AMIs, use 'doas' to install dependencies like bash, busybox-initscripts, and sudo. Configure sudoers for the wheel group.

```bash
doas su
apk add bash
apk add busybox-initscripts
apk add sudo
echo '%wheel ALL=(ALL) ALL' > wheel
mv wheel /etc/sudoers.d/
chown root:root /etc/sudoers.d/wheel

```

--------------------------------

### Manage VPN Protocols

Source: https://docs.pivpn.io/faq

Commands for managing Wireguard and OpenVPN protocols after installation.

```bash
pivpn wg [options]
pivpn ovpn [options]
```

--------------------------------

### Configure custom Git URL and Branch for Unattended Install

Source: https://docs.pivpn.io/install

Set these variables to specify a custom Git repository and branch for unattended PiVPN installations.

```bash
pivpnGitUrl="https://github.com/userthatforked/pivpn.git"
pivpnGitBranch="myfeaturebranch"

```

--------------------------------

### Migrate PiVPN and OpenVPN

Source: https://docs.pivpn.io/openvpn

Steps to migrate an existing PiVPN and OpenVPN installation to a new server. This involves backing up the current configuration, setting up OpenVPN on the new server, and restoring the backup.

```bash
sudo cp -r /etc/openvpn /etc/openvpn_backup
```

```bash
tar xzpfv <archive name>
```

```bash
sudo cp -r etc/openvpn /etc
```

```bash
sudo systemctl restart openvpn
```

--------------------------------

### Update OpenVPN Repository

Source: https://docs.pivpn.io/openvpn

Add the official OpenVPN repository to your system to update OpenVPN to a newer version on PC/Desktop installations. This involves adding a GPG key and a new APT source list.

```bash
sudo -s
wget -O - https://swupdate.openvpn.net/repos/repo-public.gpg | apt-key add -
echo "deb http://build.openvpn.net/debian/openvpn/stable [osrelease] main" > /etc/apt/sources.list.d/openvpn-aptrepo.list
exit
```

--------------------------------

### Disable OctoPi Git Wrapper

Source: https://docs.pivpn.io/faq

Removes the git wrapper that prevents the PiVPN installer from running as root on OctoPi.

```bash
sudo rm /root/bin/git
```

--------------------------------

### Connect to OpenVPN on Linux

Source: https://docs.pivpn.io/openvpn

Commands to move the configuration file and initiate the OpenVPN connection.

```bash
mv whatever.ovpn /etc/openvpn/client/
openvpn /etc/openvpn/client/whatever.ovpn
```

--------------------------------

### Import Client Profile via SCP

Source: https://docs.pivpn.io/wireguard

Copy a configuration file from the Raspberry Pi to a local machine.

```bash
scp pi-user@ip-of-your-raspberry:configs/whatever.conf path/to/target
```

--------------------------------

### Migrate PiVPN Instance

Source: https://docs.pivpn.io/wireguard

Commands for backing up and restoring PiVPN configurations between servers.

```bash
pivpn -bk
```

```bash
scp <user>@<server>:~/pivpnbackup/<archivename> <path/on/local>
```

```bash
sudo cp -r /etc/wireguard /etc/new_wireguard_backup
```

```bash
tar xzpfv <archive name>
```

```bash
sudo cp -r etc/wireguard /etc
```

```bash
sudo systemctl restart wg-quick@wg0
```

--------------------------------

### View PiVPN Help

Source: https://docs.pivpn.io/faq

Displays the help dialog for managing VPN protocols.

```text
# pivpn help
:::
::: To pass off to the pivpn command for each protocol
:::
::: Usage: pivpn wg  <command> [option]
::: Usage: pivpn ovpn <command> [option]
:::
:::  -h,  help             Show this help dialog
:::  -u,  uninstall        Uninstall pivpn from your system!
:::  -bk, backup           Backup VPN configs and user profiles

```

--------------------------------

### Import Client Profile via SCP

Source: https://docs.pivpn.io/openvpn

Command to copy an OpenVPN configuration file from a remote Raspberry Pi to a local machine.

```bash
scp pi-user@ip-of-your-raspberry:ovpns/whatever.ovpn path/to/target
```

--------------------------------

### PiVPN Management Commands

Source: https://docs.pivpn.io/wireguard

Common commands for managing client configurations and server state.

```bash
pivpn add
```

```bash
pivpn remove
```

```bash
pivpn list
```

```bash
pivpn backup
```

```bash
pivpn debug
```

--------------------------------

### PiVPN Command List

Source: https://docs.pivpn.io/wireguard

Reference for available PiVPN command-line arguments.

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

--------------------------------

### Update PiVPN Host Configuration

Source: https://docs.pivpn.io/guides/dynamic-dns

Modify the `setupVars.conf` file to set your new dynamic DNS domain name. This ensures that newly created client profiles use the correct endpoint. Requires root privileges to edit.

```bash
cd /etc/pivpn/wireguard
sudo nano setupVars.conf
```

--------------------------------

### Configure Static IP for VPN Clients

Source: https://docs.pivpn.io/openvpn

Set up static IP addresses for individual VPN clients by creating client-specific configuration files. This prevents IP address conflicts and ensures consistent IP assignment for each user. Ensure the client common name matches the filename.

```bash
client-config-dir /etc/openvpn/ccd
```

```bash
sudo mkdir /etc/openvpn/ccd
```

```bash
sudo chown -R openvpn:openvpn /etc/openvpn/ccd
```

```bash
sudo nano /etc/openvpn/ccd/exampleuser
```

```bash
ifconfig-push 10.8.0.3 255.255.255.0
```

```bash
sudo systemctl restart openvpn
```

--------------------------------

### Configure Pi-hole and Host Settings

Source: https://docs.pivpn.io/wireguard

Commands for modifying PiVPN configuration files.

```bash
pihole -a -i local
```

```bash
sudo nano /etc/pivpn/wireguard/setupVars.conf
```

--------------------------------

### Backup PiVPN Configuration

Source: https://docs.pivpn.io/openvpn

Create a backup of your current PiVPN and OpenVPN server configuration. This is essential before migrating or making significant changes. The backup is saved as a tar archive.

```bash
pivpn -bk
```

```bash
scp <user>@<server>:~/pivpnbackup/<archivename> <path/on/local>
```

--------------------------------

### Configure Router as DNS Server

Source: https://docs.pivpn.io/openvpn

Set up your router as the DNS server for VPN clients by editing the OpenVPN server configuration. This ensures that local hostnames are resolved correctly. Restart the OpenVPN service after making changes.

```bash
push "dhcp-option DNS 192.168.23.1"
```

```bash
sudo systemctl restart openvpn
```

--------------------------------

### Run PiVPN Debug Self-Check

Source: https://docs.pivpn.io/faq

Execute the built-in diagnostic tool to verify system configuration and service status.

```bash
$ pivpn -d
[...]
::::        Self check       ::::
:: [OK] IP forwarding is enabled
:: [OK] Iptables MASQUERADE rule set
:: [OK] OpenVPN is running
:: [OK] OpenVPN is enabled (it will automatically start on reboot)
:: [OK] OpenVPN is listening on port 1194/udp
=============================================
[...]
```

--------------------------------

### Generate QR Code

Source: https://docs.pivpn.io/wireguard

Commands to generate QR codes for mobile client configuration.

```bash
pivpn -qr
```

```bash
pivpn -qr -a256
```

--------------------------------

### PiVPN Management Commands

Source: https://docs.pivpn.io/openvpn

Individual commands for managing client certificates, server backups, and debugging.

```bash
pivpn add
```

```bash
pivpn revoke
```

```bash
pivpn list
```

```bash
pivpn backup
```

```bash
pivpn debug
```

--------------------------------

### Check firewall rules

Source: https://docs.pivpn.io/faq

Commands to display current iptables rules for troubleshooting connectivity.

```bash
sudo iptables -S
```

```bash
sudo iptables -t nat -S
```

--------------------------------

### Configure PersistentKeepalive

Source: https://docs.pivpn.io/wireguard

Settings to maintain WireGuard connections through NAT.

```text
PersistentKeepalive = 25
```

```text
pivpnPERSISTENTKEEPALIVE=25
```

--------------------------------

### Update WireGuard

Source: https://docs.pivpn.io/wireguard

Command to initiate the WireGuard update process.

```bash
pivpn -wg
```

--------------------------------

### Verify WireGuard Kernel Module

Source: https://docs.pivpn.io/faq

Check if the WireGuard kernel module is loaded and active.

```bash
wireguard             225280  0
ip6_udp_tunnel         16384  1 wireguard
udp_tunnel             16384  1 wireguard
```

--------------------------------

### Configure AllowedIPs for Split-Tunneling

Source: https://docs.pivpn.io/wireguard

Replace the default AllowedIPs in the client configuration to restrict traffic to specific subnets.

```text
AllowedIPs = 0.0.0.0/0, ::0/0
```

```text
AllowedIPs = <your-lan-ip/netmask>, <wireguard-ipv4/netmask>, <wireguard-ipv6/netmask>
```

```text
AllowedIPs = 192.168.0.1/24, 10.19.17.0/24, fd11:5ee:bad:c0de::/64
```

--------------------------------

### Resolve Local Hostnames

Source: https://docs.pivpn.io/wireguard

Configure DNS or local hosts file to resolve internal network hostnames.

```text
DNS = 192.168.23.1
```

```text
192.168.1.1   JohnDoeRouter
192.168.1.2   JohnDoePC
192.168.1.3   JaneDoePC
192.168.1.4   CatPC
192.168.1.5   DogPC
```

--------------------------------

### Add Local Hostnames to /etc/hosts

Source: https://docs.pivpn.io/openvpn

Manually configure local hostname resolution by editing the /etc/hosts file. Map IP addresses to hostnames for devices on your local network. This is an alternative to using the router as the DNS server.

```text
192.168.1.1   JohnDoeRouter
192.168.1.2   JohnDoePC
192.168.1.3   JaneDoePC
192.168.1.4   CatPC
192.168.1.5   DogPC
```

--------------------------------

### Manage WireGuard Tunnel on Linux

Source: https://docs.pivpn.io/wireguard

Commands to activate and deactivate the WireGuard tunnel.

```bash
mv whatever.conf /etc/wireguard/
wg-quick up whatever
```

```bash
wg-quick down whatever
```

--------------------------------

### Configure Pi-hole DNS for VPN Clients

Source: https://docs.pivpn.io/openvpn

Edit the OpenVPN server configuration to push the Pi-hole's IP address as the DNS server for connected VPN clients. This enables ad blocking for all VPN traffic. Ensure the IP address is correct for your network.

```bash
sudo nano /etc/openvpn/server.conf
```

```bash
push "dhcp-option DNS 192.168.23.211"
```

```bash
sudo systemctl restart openvpn
```

```bash
pihole -a -i local
```

--------------------------------

### Check Public IP Address

Source: https://docs.pivpn.io/faq

Retrieve the current public IP address of the connection to compare against the PiVPN host configuration.

```bash
$ curl -s https://checkip.amazonaws.com
192.0.2.48
```

--------------------------------

### Check Interface IP Address

Source: https://docs.pivpn.io/faq

Verify the current IP address assigned to the specified network interface.

```bash
$ ip -f inet address show eth0
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    `inet 192.168.23.211/24 brd 192.168.23.255 scope global dynamic eth0
       valid_lft 84694sec preferred_lft 84694sec
```

--------------------------------

### Set Hybrid Compatible MTU Size

Source: https://docs.pivpn.io/openvpn

Add this line to your OpenVPN configuration file to adjust the MTU for Telekom Hybrid connections. This is particularly useful for newly created .ovpn files.

```config
tun-mtu 1316
```

--------------------------------

### Capture UDP traffic with tcpdump

Source: https://docs.pivpn.io/faq

Use this command to monitor incoming and outgoing traffic on a specific port and network interface.

```bash
tcpdump -n -i eth0 udp port 1194
```

--------------------------------

### Kick Connected VPN Client

Source: https://docs.pivpn.io/openvpn

Disconnect a specific VPN client from the server by using the OpenVPN management interface. This requires enabling the management interface in the server configuration and then using netcat to send commands.

```bash
sudo systemctl openvpn stop
```

```bash
management 127.0.0.1 PORT
```

```bash
sudo systemctl openvpn start
```

```bash
nc 127.0.0.1 PORT
```

```bash
kill CLIENTNAME
```

--------------------------------

### Exit root shell

Source: https://docs.pivpn.io/faq

Command to terminate the current root shell session.

```bash
exit
```

--------------------------------

### Block Internet Access for VPN Clients

Source: https://docs.pivpn.io/openvpn

Modify the OpenVPN server configuration to prevent VPN clients from accessing the internet directly, while still allowing access to the local network. Replace the default gateway push with a specific route for your local network.

```bash
push "route 192.168.23.0 255.255.255.0"
```

```bash
sudo systemctl restart openvpn
```

--------------------------------

### OpenVPN TLS Cipher List

Source: https://docs.pivpn.io/openvpn

This list specifies the ciphers that can be used by OpenVPN for its control channel. These ciphers are recommended for secure communication.

```plaintext
TLS-ECDHE-RSA-WITH-AES-256-GCM-SHA384
TLS-ECDHE-ECDSA-WITH-AES-256-GCM-SHA384
TLS-ECDHE-RSA-WITH-AES-256-CBC-SHA384
TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384
TLS-DHE-RSA-WITH-AES-256-GCM-SHA384
TLS-DHE-RSA-WITH-AES-256-CBC-SHA256
TLS-DHE-RSA-WITH-AES-128-GCM-SHA256
TLS-DHE-RSA-WITH-AES-128-CBC-SHA256
```
Tokens:
Raw