WireGuard
You want to reach your services from anywhere, without exposing them to the whole Internet. Let's dig a private tunnel between your computer and your server with WireGuard, using one settings file on each side.
- Course
- Tutorial 26 of 35
- Time
- 30 min to read
- Tested with
- wireguard-tools 1.0.20210914 (Debian 13.7)
What you will be able to do
- Explain what a personal VPN is and what WireGuard brings.
- Generate the keys, then write the two wg0.conf files.
- Open the UDP port in ufw and bring the tunnel up.
- Check the handshake with wg show, then stop or restart the tunnel.
Before you start: Secure SSH: turn off passwords, A firewall with ufw.
Contents
How do you install WireGuard on Debian to get a personal VPN? You have a server on the Internet and devices at home, and you want them to talk without the whole world listening in. WireGuard digs a private tunnel between them, with one small settings file on each side. Plan on half an hour, a good part of it spent copying keys without a typo.
What a personal VPN is
A VPN, or virtual private network, links distant machines as if they were plugged into the same network. A personal VPN is a private tunnel between your devices and your server, dug by you. What travels through the tunnel is encrypted, so nobody on the way can see it. The rest of your traffic follows your usual connection.
WireGuard is the software that digs this tunnel. Debian 13 already includes its engine in the kernel, the core of the system, so only the tools are left to install.
Inside the tunnel, each machine gets an address that exists only there: 10.77.0.1 for the server, 10.77.0.2 for your computer. The tunnel gives you three things:
- Reach the server privately. A service that listens only on
10.77.0.1stays invisible from the Internet and can be reached only through the tunnel. - Link your devices. Your computer, your phone and other machines meet on a network of your own, wherever you are.
- Send all your traffic through the server, if you want. You don't need it for what follows, so we keep it for a box at the end of step 7.
Each end of the tunnel is called a peer. Here there are two: the server, which waits for calls, and your computer, which makes them. Let's install WireGuard on both.
1Install WireGuard
Both machines need the same tools. In this article, your computer runs Linux from the Debian or Ubuntu family. A phone or another system follows the same logic, as a box in step 5 explains. Run this command on the server, then on your computer.
sudo apt install -y wireguard wireguard-toolsThe wireguard-tools package brings the two commands we use. wg makes the keys and shows the state of the tunnel, and wg-quick brings the tunnel up and down. The wireguard package is a shortcut that bundles everything. Now you need keys.
2Generate the keys
Each peer has its own key pair, two numbers linked to each other. The private key stays secret, on the machine that made it. The public key is computed from it, and you hand it to the other peer, like a lock you give away while keeping the key. It's the same idea as the SSH keys in Secure SSH: turn off passwords.
The command below chains five pieces, and each has its job:
wg genkeymakes the private key, andwg pubkeydraws the public key from it.teewrites the private key to a file while letting it carry on towg pubkey.sudoacts as root, the administrator account that can read and write everything, so the files will belong to it.sh -cstarts a small command interpreter as root for the whole quoted part.umask 077sets that interpreter so that the files it creates afterwards can be read only by their owner.
Let's run it on the server first.
sudo sh -c 'umask 077; wg genkey | tee /etc/wireguard/server.key | wg pubkey > /etc/wireguard/server.pub'
sudo cat /etc/wireguard/server.pubi//dgJDIO/GtBrxenXnVCcWNcUKVfJb2QIl63ItYPFU=The line shown is the server's public key: 44 characters that end with an = sign. The keys in this article are throwaway examples, made for the occasion. Don't reuse them, because yours will be different. Do the same thing on your computer.
sudo sh -c 'umask 077; wg genkey | tee /etc/wireguard/client.key | wg pubkey > /etc/wireguard/client.pub'
sudo cat /etc/wireguard/client.pubSaURc9GeiHt6LO1wPzJu4cnt5xPEWp7C/LJ4sKzUoTE=Keep these two public keys handy: each machine needs the other's. Let's start with the server.
3Configure the server
The server reads its settings from /etc/wireguard/wg0.conf, where wg0 is the name of the tunnel. The file has an [Interface] section for the server itself, and a [Peer] section for each peer allowed in.
It contains the private key. So it's created with 600 permissions, read and write for its owner alone, and it belongs to root. The other accounts on the server can't read it, but you can with sudo.
In the command below, replace the value written after CLIENT_PUB= with the public key of your computer, the one from step 2. The value shown is our example.
sudo env CLIENT_PUB='SaURc9GeiHt6LO1wPzJu4cnt5xPEWp7C/LJ4sKzUoTE=' sh -c 'umask 077; cat > /etc/wireguard/wg0.conf <<EOF
[Interface]
Address = 10.77.0.1/24
ListenPort = 51820
PrivateKey = $(cat /etc/wireguard/server.key)
[Peer]
PublicKey = $CLIENT_PUB
AllowedIPs = 10.77.0.2/32
EOF'Every line has a precise job:
Address: the server's address in the tunnel. The/24means the first three numbers (10.77.0) are fixed and only the last one varies, so the whole10.77.0.xnetwork is in this tunnel. Choose a range different from your home router's, often192.168.x.x, to avoid mix-ups.ListenPort: the port where the server waits for calls. 51820 is the usual choice for WireGuard.PrivateKey: the server's private key. The command reads it from its file, so you don't have to copy it.PublicKey: the peer's public key, here your computer's.AllowedIPs: the addresses allowed for this peer, explained just below.
AllowedIPs works twice, a bit like a doorman with an address book. A packet is a small piece of data. For an outgoing packet, the tunnel checks the list and sends it to the peer whose list contains its destination. For an incoming packet, it lets it through only if the sender is on that peer's list. Here, 10.77.0.2/32 means exactly one address, your computer's, because the /32 fixes all four numbers. The peer can't pose as another machine.
The server is set up, but its firewall doesn't let it answer yet.
4Open the port in ufw and start the server
WireGuard talks over UDP, a protocol that sends packets without opening a conversation first. The firewall (see A firewall with ufw) refuses everything you haven't allowed, so you must allow port 51820 over UDP.
This port is open to the whole Internet, but it answers nobody who lacks the right key. WireGuard silently ignores any packet that doesn't carry one. The services themselves stay behind the tunnel, out of sight.
sudo ufw allow 51820/udpRule added
Rule added (v6)There are two lines because ufw writes the rule for IPv4 and for IPv6. The port is open, so the server can start its tunnel.
sudo wg-quick up wg0[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 10.77.0.1/24 dev wg0
[#] ip link set mtu 1420 up dev wg0Each [#] line is a command that wg-quick runs for you. It creates the wg0 interface (the tunnel's virtual network card), loads your settings, gives it its address, then sets the MTU, the maximum size of a packet (1420 leaves room for the tunnel's wrapping), and switches it on. You don't need to remember these lines, except that they show no error.
The server now waits for the call. Next, write your computer's file.
5Configure the client and bring the tunnel up
The client's file follows the server's, with a few differences:
- No
ListenPort: the client calls instead of waiting. Address: its own,10.77.0.2.PublicKey: the server's, since the peer is now the server.AllowedIPs: the whole tunnel network,10.77.0.0/24.Endpoint: the server's public address and port, since the client must know where to call.PersistentKeepalive = 25: a small sign of life every 25 seconds, which keeps the tunnel open even behind a home router.
Like the server's, this file is created with 600 permissions, owned by root.
In the command below, replace the value written after SERVER_PUB= with the server's public key, the one from step 2. Also replace 203.0.113.10 with your server's public IP address.
sudo env SERVER_PUB='i//dgJDIO/GtBrxenXnVCcWNcUKVfJb2QIl63ItYPFU=' sh -c 'umask 077; cat > /etc/wireguard/wg0.conf <<EOF
[Interface]
Address = 10.77.0.2/24
PrivateKey = $(cat /etc/wireguard/client.key)
[Peer]
PublicKey = $SERVER_PUB
Endpoint = 203.0.113.10:51820
AllowedIPs = 10.77.0.0/24
PersistentKeepalive = 25
EOF'Here, AllowedIPs = 10.77.0.0/24 means "send into the tunnel everything meant for the 10.77.0.x network". The rest of your traffic, your usual websites, keeps using your normal connection. Let's bring the tunnel up.
sudo wg-quick up wg0[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 10.77.0.2/24 dev wg0
[#] ip link set mtu 1420 up dev wg0What about my phone, or a Windows or macOS computer?
WireGuard apps exist for these systems. Each device has its own key pair, its own address in the tunnel (10.77.0.3, 10.77.0.4, and so on) and its own [Peer] block in the server's file. The client file looks the same as above, with the device's key and address.
The tunnel is up on both sides. Let's see whether it really works.
6Test the handshake
When two peers meet, they first do a handshake: a short exchange where each one checks the other's public key. Without it, no packet gets through. The quickest way to check it is to ask the server for a sign of life through the tunnel.
ping -c 3 10.77.0.1PING 10.77.0.1 (10.77.0.1) 56(84) bytes of data.
64 bytes from 10.77.0.1: icmp_seq=1 ttl=64 time=0.154 ms
64 bytes from 10.77.0.1: icmp_seq=2 ttl=64 time=0.241 ms
64 bytes from 10.77.0.1: icmp_seq=3 ttl=64 time=0.158 ms
--- 10.77.0.1 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2046msThe three replies prove that your packets cross the tunnel. Your times will be longer, because they include the trip to the server. Next, wg show displays the state of the tunnel, on the server as on the client.
sudo wg showinterface: wg0
public key: i//dgJDIO/GtBrxenXnVCcWNcUKVfJb2QIl63ItYPFU=
private key: (hidden)
listening port: 51820
peer: SaURc9GeiHt6LO1wPzJu4cnt5xPEWp7C/LJ4sKzUoTE=
endpoint: 198.51.100.7:35515
allowed ips: 10.77.0.2/32
latest handshake: 7 seconds ago
transfer: 564 B received, 476 B sentThree lines matter. latest handshake gives the time of the last handshake. transfer counts the bytes exchanged, and endpoint shows where the client calls from, here an example address. Your output will show other durations and numbers. On the computer, sudo wg show prints the same thing from the client's point of view.
An old handshake doesn't mean the tunnel is dead. With no traffic it sleeps, and the handshake happens again on the first packet. To know whether it's alive, trigger an exchange with a ping, then read wg show again. The latest handshake time must be recent, under two minutes, and transfer must have grown.
The tunnel works. What's left is stopping it, restarting it and making it start on its own.
7Stop, restart, start at boot
wg-quick down takes the tunnel down, and wg-quick up brings it back. The file is read only when the tunnel comes up, so after any change to wg0.conf, run a down then an up. Let's take down your computer's tunnel first.
sudo wg-quick down wg0[#] ip link delete dev wg0For the server to bring its tunnel back after every reboot, hand it to systemd, Debian's service manager. On the server, first take down the tunnel you started by hand, or the name wg0 would already be taken. The second command starts it right now, then at every boot.
sudo wg-quick down wg0
sudo systemctl enable --now wg-quick@wg0Your computer's tunnel is already down, so there is nothing to undo on that side. If you want the tunnel to be always up, run only the second command. Otherwise, bring it up on demand with wg-quick up wg0.
sudo systemctl enable --now wg-quick@wg0Send all your traffic through the server
By default, only traffic to 10.77.0.x goes through the tunnel. If you want the whole Internet to go through the server, for example to keep a public Wi-Fi from seeing your traffic, you need three steps. First step: the server must agree to relay packets for other machines, which the kernel's ip_forward option controls. The sysctl command reads and changes these options.
echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --systemSecond step: it must send those packets on to the Internet under its own address. That is the job of MASQUERADE, a rule of iptables (the tool that tells the kernel what to do with packets). It replaces the sender's 10.77.x.x address with the server's on the way out (POSTROUTING). ufw must also let these packets through. First find the name of the server's network card, eth0 in our examples, with ip route show default. In the [Interface] section of wg0.conf, add these two lines with the right name.
PostUp = iptables -t nat -A POSTROUTING -s 10.77.0.0/24 -o eth0 -j MASQUERADE
PostDown = iptables -t nat -D POSTROUTING -s 10.77.0.0/24 -o eth0 -j MASQUERADEsudo ufw route allow in on wg0 out on eth0
sudo wg-quick down wg0
sudo wg-quick up wg0Third step: in the client file, replace AllowedIPs = 10.77.0.0/24 with AllowedIPs = 0.0.0.0/0, which means "all IPv4 addresses" (IPv4 is the common address format, like 203.0.113.10). Then restart the client's tunnel. IPv6 addresses, the newer format, aren't in that list. If your connection has them, that traffic still leaves outside the tunnel. To stop that, turn off IPv6 on the client with the command below. Keep an SSH connection open during the test. A mistake cuts your Internet access, and wg-quick down wg0 restores it.
sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1net.ipv6.conf.all.disable_ipv6 = 1This setting disappears at reboot. Set it back to 0 to turn IPv6 on again.
If it fails
Three situations are worth knowing:
wg-quick: `wg0' already exists. The tunnel is already up on this machine. Runsudo wg-quick down wg0, thenupif you want to recreate it with a changed file.- The
pingstays silent andwg showshows nolatest handshake. On thetransferline, you read0 B received: the client calls, but nobody answers. First check thatsudo ufw statuslists51820/udpon the server. Then reread theEndpointand the two public keys, which must cross over: the client's in the server's file, the server's in the client's file. - A change to
wg0.confhas no effect. The file is read only when the tunnel comes up. Run awg-quick down wg0then awg-quick up wg0.
What's next
Your computer and your server now share a private network, with its own addresses. A third machine can join the same way: the one that keeps your files at home, a NAS, which is a small storage box plugged into your network. The next article, Connect your NAS, links your NAS to the server through this tunnel.