Install PiGuard on Raspberry Pi

This page is a guide for anyone willing to install PiGuard on a Raspberry Pi 4.

Prerequisites

System requirements

• A fresh Raspberry Pi OS Lite (Bookworm, 64-bit) image flashed on a Raspberry Pi 4
• SSH enabled and WiFi country code set (via Raspberry Pi Imager or raspi-config)
• Root / sudo access on the Pi

Network requirements

• WAN connected on eth0 (Ethernet) with Internet access

Repository requirements

• The provisioning/ folder and the p2-wportal/ portal repository copied onto the Pi, side by side (same parent directory)

Installation Steps

Step 1 — Copy the repository

Copy provisioning/ (and p2-wportal/ next to it) onto the Pi, e.g. via scp or git clone.

Step 2 — Configure

cd provisioning
cp piguard.env.example piguard.env
nano piguard.env

Edit at least: WiFi SSID/passphrase, WireGuard settings, obfs4 bridge line, portal credentials.

Step 3 — Run the installer

sudo bash install.sh

This copies piguard.env to /etc/piguard/piguard.env (mode 600), then runs each step in order:

Step	Role
00-base	Installs packages (hostapd, dnsmasq, wireguard, tor, obfs4proxy, iptables…)
05-ssh	Enables SSH password authentication
10-network-ap	Configures hostapd/dnsmasq, static IP on wlan0
20-wireguard	Generates keys, writes wg0.conf, enables wg-quick@wg0 at boot
40-firewall	Installs iptables kill-switch scripts, enabled at boot
50-portal	Deploys the p2-wportal web portal (venv + systemd service on port 8000)

A single step can be re-run on its own:

sudo bash install.sh 40-firewall

Step 4 — Reboot

sudo reboot

WireGuard finalization

Retrieve the generated public key and send it to your VPN operator:

sudo cat /etc/wireguard/publickey

Then fill in WG_ENDPOINT and WG_SERVER_PUBKEY in /etc/piguard/piguard.env and re-run:

sudo bash install.sh 20-wireguard

Optional Tor bridge

Set your private obfs4 bridge line in OBFS4_BRIDGE (in piguard.env, without the leading Bridge keyword), then:

sudo bash install.sh 30-tor
sudo systemctl restart tor

Access configuration

Connect to the configured WiFi SSID, then open the portal at:

http://192.168.50.1:8000/

Default login is n2h (see PORTAL_USERNAME / PORTAL_PASSWORD_HASH). Change the password by generating a new hash:

python3 -c "from werkzeug.security import generate_password_hash as h; print(h('YOUR_PASSWORD'))"

Verification

systemctl status ssh hostapd dnsmasq piguard-ap piguard-firewall tor piguard_portal
sudo wg show
sudo iptables -S ; sudo iptables -t nat -S

From a WiFi client: check the assigned IP (192.168.50.x), the gateway (192.168.50.1), and Internet access.