Turn a Raspberry Pi into a simple WireGuard™ VPN Appliance
WGAdmin is a free tool that converts a Raspberry Pi single-board computer into an easy-to-use WireGuard VPN Appliance. WGAdmin allows you to create, configure, and manage a simple WireGuard network without messing around with configuration files.
Architecturally, WGAdmin is a configuration management layer wrapped around the standard WireGuard software. It's the missing WireGuard GUI and config generator. Security and heavy lifting is handled by WireGuard natively.
WGAdmin needs to run as a daemon. WGAdmin will be responsible for starting and stopping the WireGuard tunnels.
i.e. You do not install wg-quick@wg0 etc.
It is possible to use wg-quick for other tunnels that are separate from
the interface managed by WGAdmin. e.g. let WGAdmin manage wg0 and wg-quick manage wg1 etc.
By default, WGAdmin listens on 0.0.0.0:8000 but you can change this manually in the /etc/wgadmin.json config file.
WGAdmin is available prepackaged as .deb files below.
- wgadmin_latest_arm64.deb (ARM 64bit)
- wgadmin_latest_armhf.deb (ARM 32bit)
- wgadmin_latest_arm64.deb (AMD 64bit)
The packages are very simple and it can also be installed manually if you prefer.
To install on other distributions...
Be sure the dependancies are satisfied.
- Requires a recent kernel with WireGuard included (5.6+)
- or WireGuard installed separately (
apt install wireguardetc.) - optionally install
wireguard-tools
Download the appropriate wgadmin binary for your architecture and place is in /usr/local/bin
Download the wgadmin.service file and place it in /lib/systemd/system
Enable and start it
sudo chown root:root /usr/local/bin/wgadmin
sudo chmod 755 /usr/local/bin/wgadmin
sudo systemctl daemon-reload
sudo systemctl enable wgadmin.service
sudo systemctl start wgadmin.service
There are a few additional things that need to be configured manually before WireGuard can work on your network.
If you want to reach other devices on your home network, you must enable IP Forwarding.
Check to see if forwarding is enabled (1 = enabled, 0 = disabled). At a Linux command prompt...
$ sysctl net.ipv4.ip_forward
net.ipv4.ip_forward = 0
To enable...
$ sudo -i
password: ********
# echo net.ipv4.ip_forward = 1 > /etc/sysctl.d/98-wgadmin.conf
# sysctl -p /etc/sysctl.d/98-wgadmin.conf
net.ipv4.ip_forward = 1
# exit
If you want to use this device as a gateway to route all traffic beyond your home network, you must set up Masquerading.
Instructions to follow...
In order for return traffic on your network to find its way back to remote peers, you need to set up a static route on the network's gateway. If you just want to reach devices on your home network, this is not necessary.
Add a static route on the network's default gateway as follows: (examples, depending on your type of router): (where 192.168.1.99 is the address of the wgadmin device)
Destination: 192.168.99.0/24 Next hop: 192.168.1.99 (server device)
ip route add 192.168.99.0/24 via 192.168.1.99
route add dest 192.168.99.0 mask 255.255.255.0 gateway 192.168.1.99 metric 1
WireGuard traffic from outside needs to be able to reach this device.
Forward all external WireGuard connections from the Internet to this device. (example, depending on your type of router):
From: Any Port: 51821 To: 192.168.1.99 Port: 51821 Protocol: UDP
If you do not have a static IP address from your Internet provider, you will need a name to refer back to this network's gateway.
It's best to set up a Dynamic DNS name for your gateway. This way nothing will need to be reconfigured if your address changes.
The wgadmin app keeps its configuration in /etc/wgadmin.json. There are several additional user changeable parameters that are not represented in the GUI. Be sure to stop the wgadmin service before making changes or they risk being overwritten.
- WgInterface
- The WireGuard interface name. Defaults to `wg0`.
- HttpListen
- The IP and Port running the Web GUI. Defaults to 0.0.0.0:8000. Note: 0.0.0.0 means listen on all interfaces. The app runs as root so ports below 1024 are possible if they are free. e.g. 80
- Username
- A blank username will trigger the initialization page. Here you can create a new Username and Password. i.e. This is how you reset a forgotten password. Edit the Username field and set it to `"Username": "",`
- Password
- This stores a bcrypt hash of the password. Setting it to blank will trigger the initialization page as above.