WireGuard is an awesome tool for securely accessing your Raspberry Pi computers even behind mobile networks that don’t provide a public IP address. It has client applications for iOS, macOS, Windows and all flavors of Linux.
Devices connected to the same WireGuard network can access all other devices on the same network. You can safely view webcam feeds or internet connected device configuration pages without exposing them to the public web. WireGuard is awesome!
Requirements and System Overview
WireGuard nodes require at least one publicly accessible node or peer which acts as a “bounce server” for all other nodes that are behind private networks that use NAT. The public node can be a Raspberry Pi connected to your home internet with a real (and potentially dynamic) IP address or the cheapest virtual private server on DigitalOcean with WireGuard installed and all peers listed in the network config file.
Important WireGuard History
In March 2020 WireGuard module was included in the Linux kernel version 5.6. Here are instructions for installing WireGuard while you’re running a Linux distribution that is based on an earlier version of Linux kernel.
uname -a to determine the current Linux kernel version. It should return something like this:
Linux raspi 4.19.118-v7+ #1311 SMP Mon Apr 27 14:21:24 BST 2020 armv7l GNU/Linux
4.19.118-v7+ is the version of the Linux kernel on your device.
Install using Package Manager
WireGuard isn’t included in the official Raspbian distribution, yet. You can verify that by trying to install WireGuard from the package repository:
sudo apt-get install wireguard
If that fails, you need to install and compile it from the source files as described below. There are tutorials that suggest using packages from the Debian repository but I wouldn’t recommend that.
Install from Source
The official instructions for compiling WireGuard from source files have been updated in early 2020 after the introduction of a separate package
wireguard-linux-compat for the WireGuard Linux kernel module which has been decoupled from the user-space tools
We need to install the following two packages:
- WireGuard kernel module only for systems with Linux kernel below version 5.6, and
- WireGuard command-line tools for interacting with the application.
First, install the build process dependencies:
sudo apt-get install raspberrypi-kernel-headers libmnl-dev libelf-dev build-essential git
Clone and build the kernel module only if you’re running a Linux kernel version 3.10 to 5.5:
git clone https://git.zx2c4.com/wireguard-linux-compat make -C wireguard-linux-compat/src -j$(nproc) sudo make -C wireguard-linux-compat/src install
Clone and build the
wg-quick command-line tools:
git clone https://git.zx2c4.com/wireguard-tools/ make -C wireguard-tools/src -j$(nproc) sudo make -C wireguard-tools/src install
That’s it! Now you need to configure the WireGuard to automatically start during the boot and which peers and servers to connect to.
See this excellent and elaborate guide for configuring WireGuard or follow the quick instructions below.
1. Generate the Authentication Keys
A pair of a private and a matching public key is used to communicate and authenticate the current instance of WireGuard with the rest of your WireGuard network. Use the
wg utility to generate those keys.
First, set the file permissions mode for all following operations to 077 using
umask 077 which translates to “only allow the current user to read the created files”:
Then generate the private key and store it in
privatekey file in the current directory:
wg genkey > privatekey
The generate the matching public key to be referenced in all your WireGuard network peers from the
privatekey that we generated previously:
wg pubkey > publickey < privatekey
< operators are used to send the output from one command as an input for another command. In this case we’re sending the contents of
wg pubkey which then produces the
publickey file in the current directory.
cat privatekey and
cat publickey to output both keys to the terminal for reference.
2. Configure the WireGuard Network Interface
Your WireGuard installation can be associated with multiple WireGuard networks and each of them needs a dedicated network interface that is configured by adding
*.conf files under the
For example, we’ll add a network called
wg0 by creating
/etc/wireguard/wg0.conf with the following contents:
[Interface] Address = 10.200.200.X/32 PrivateKey = <Your Private Key> [Peer] PublicKey = <Server Public Key> AllowedIPs = 10.200.200.0/24 Endpoint = <Server IP address or FQDN>:51820 PersistentKeepalive = 25
[Interface] section is where we define this computer on the network:
<Peer Private Key>with the contents of the
privatekeywe generated earlier. This string should never leave the device or be shared publicly. The contents of the
publickeycan be shared publicly and has to be known by all other peers that need to connect to your computer.
- Set the
Addressto an IP address to be associated with this device on your network. Notice the
/32suffix which provides some additional context for how the address is used.
[Peer] section we define other WireGuard nodes or servers that we want to connect to:
PublicKeyis the public key of the server we’re connecting to (not the one we generated above).
Endpointis the public hostname (if the peer is able to resolve the IP address) or the public IP address of the server.
See this WireGuard configuration reference for the explanation of all configuration parameters.
We can also use the
wg command line tool to generate the same file:
sudo wg set wg0 \ private-key <file path> \ peer <Server Public Key> \ endpoint <Server IP address or FQDN>:51820 \ allowed-ips 10.200.200.0/24 persistent-keepalive 25
3. Enable the WireGuard Interface
wg0 interface we configured:
sudo wg-quick up wg0
wg-quick down wg0 to stop the interface.
4. Start WireGuard on Boot
Register a script that came with the WireGuard utilities to start the WireGuard service automatically using Systemd during boot:
sudo systemctl enable wg-quick@wg0
wg0 is the name of the interface to start during the boot.
To start the service right away:
sudo systemctl start wg-quick@wg0
To see the current status of the service:
sudo systemctl status wg-quick@wg0
5. Debug WireGuard
Use the following commands to debug the WireGuard connection:
sudo wg showto monitor the connections.
journalctl --follow wg-quick@wg0to monitor the WireGuard startup.