Before you start
This guide connects one client to one Ubuntu server. When you’re done, the client reaches the server at 10.8.0.1 through an encrypted tunnel, while its normal internet traffic goes out the way it always has.
You’ll need
- An Ubuntu 24.04 LTS server with a public IP address and SSH access
- A user with sudo rights on the server, and on the client if it runs Ubuntu
- Permission to open UDP port 51820, including in any cloud provider firewall
- A client: another Ubuntu machine, or any device that runs the official WireGuard app
Address plan
| Role | Host | Tunnel address | Listens on | Key files |
|---|---|---|---|---|
| Server | vpn-01 · 203.0.113.10 | 10.8.0.1/24 | UDP 51820 | server.key · server.pub |
| Client | laptop | 10.8.0.2/32 | connects out | client.key · client.pubkept inside the app |
203.0.113.0/24 is reserved for documentation (RFC 5737). Replace it with your server’s real public address, and choose a tunnel subnet that doesn’t overlap any network the client joins.
Install the WireGuard tools
Connect to the server over SSH and install the userspace tools. Nothing starts or listens yet; this only adds the commands the next steps use.1
WireGuard itself is part of the Linux kernel Ubuntu ships. The wireguard package adds the wg and wg-quick commands.
sudo apt update
sudo apt install wireguardConfirm the tools are on the path:
wg --versionwireguard-tools v1.0.<date> - https://git.zx2c4.com/wireguard-tools/
Illustrative. The version on your system will differ; any version line means the tools are installed.
Generate the server’s key pair
Each WireGuard peer has a private key it keeps and a public key it hands to others. Generate the server’s pair straight into /etc/wireguard, so the private key never sits in your home directory.2
The public key is safe to share; it is how peers recognize the server. The private key should exist in exactly one place.
sudo install -d -m 700 /etc/wireguard
wg genkey | sudo tee /etc/wireguard/server.key | wg pubkey | sudo tee /etc/wireguard/server.pub
sudo chmod 600 /etc/wireguard/server.key<server public key: 44 characters ending in =>
Illustrative. The command prints the public key once. This page never shows a real key.
Create the client’s key pair
On the client, install the same package and generate a separate pair. Every device gets its own keys; never reuse the server’s.3
Only public keys travel between machines. Move them however you like: they aren’t secret.
sudo apt install wireguard
sudo install -d -m 700 /etc/wireguard
wg genkey | sudo tee /etc/wireguard/client.key | wg pubkey | sudo tee /etc/wireguard/client.pub
sudo chmod 600 /etc/wireguard/client.key- Copy the public key the command printed. You’ll paste it into the server’s configuration in step 4.
On another operating system, the official WireGuard app creates the key pair for you when you add a tunnel. Its private key stays inside the app.3
Only public keys travel between machines. Move them however you like: they aren’t secret.
- Install the official app for your operating system from
wireguard.com/install. - Create a new, empty tunnel. The app generates a key pair for it.
- Copy the public key the app shows. Leave the tunnel unsaved; you’ll finish it in step 7.
Write the server configuration
wg-quick reads one file per interface, and the interface takes its name from the file. wg0.conf creates wg0.4
On the server, AllowedIPs works as a routing rule and an access rule at once: this peer is accepted only from 10.8.0.2.
sudo nano /etc/wireguard/wg0.conf[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = <paste the contents of server.key>
[Peer]
# laptop
PublicKey = <paste the client’s public key>
AllowedIPs = 10.8.0.2/32- Replace both values in angle brackets, brackets included.
- To read the private key, run
sudo cat /etc/wireguard/server.keyand paste it in. - Save the file, then restrict it:
sudo chmod 600 /etc/wireguard/wg0.conf.
Open the port in the firewall
The server has to accept UDP packets on port 51820. If you use ufw, allow SSH first, so turning the firewall on can’t cut off your session.5
Cloud providers often run a second firewall outside the server. If yours does, allow UDP 51820 there as well.
sudo ufw allow OpenSSH
sudo ufw allow 51820/udp
sudo ufw enable
sudo ufw statusStatus: active To Action From -- ------ ---- OpenSSH ALLOW Anywhere 51820/udp ALLOW Anywhere OpenSSH (v6) ALLOW Anywhere (v6) 51820/udp (v6) ALLOW Anywhere (v6)
Illustrative. Rules that already exist on your server will be listed too.
Start the tunnel and enable it at boot
Bring the interface up through systemd, so it comes back on its own after a reboot.6
wg-quick@wg0 is a systemd template unit. The part after @ is the name of the configuration file.
sudo systemctl enable --now wg-quick@wg0
sudo wg showinterface: wg0 public key: <server public key> private key: (hidden) listening port: 51820 peer: <client public key> allowed ips: 10.8.0.2/32
Illustrative. There’s no handshake line yet because the client hasn’t connected.
Configure the client and connect
Create the client’s own wg0.conf. Endpoint tells the client where to find the server; AllowedIPs decides which traffic goes into the tunnel.7
AllowedIPs = 10.8.0.0/24 sends only tunnel traffic through WireGuard. Everything else on the client is unchanged.
sudo nano /etc/wireguard/wg0.conf[Interface]
Address = 10.8.0.2/24
PrivateKey = <paste the contents of client.key>
[Peer]
PublicKey = <paste the contents of server.pub>
Endpoint = 203.0.113.10:51820
AllowedIPs = 10.8.0.0/24
PersistentKeepalive = 25sudo chmod 600 /etc/wireguard/wg0.conf
sudo wg-quick up wg0Finish the tunnel you started in step 3. Keep the [Interface] section the app generated, and add the address and the server as a peer.7
AllowedIPs = 10.8.0.0/24 sends only tunnel traffic through WireGuard. Everything else on the client is unchanged.
- In the [Interface] section, add
Address = 10.8.0.2/24. - Below it, add the [Peer] section shown next.
- Save the tunnel and activate it.
[Peer]
PublicKey = <paste the contents of server.pub>
Endpoint = 203.0.113.10:51820
AllowedIPs = 10.8.0.0/24
PersistentKeepalive = 25Verify the handshake and the route
Two checks: the peers have completed a handshake, and traffic really crosses the tunnel. Do both, because either can pass while the other fails.8
PersistentKeepalive sends a small packet every 25 seconds, which keeps the path open through NAT routers that forget idle connections.
ping -c 3 10.8.0.1ping 10.8.0.1sudo wg showpeer: <client public key> endpoint: <client public IP>:<port> allowed ips: 10.8.0.2/32 latest handshake: 14 seconds ago transfer: 1.24 KiB received, 1.02 KiB sent
Illustrative. The timing and byte counts will differ. What matters is that a latest handshake line appears.
Before you rely on it
0 of 6 doneRun through this once the tunnel works. Your ticks are saved in this browser only.
Troubleshooting
Check that the server firewall and any cloud firewall allow UDP 51820, that Endpoint holds the server’s public address and port, and that each side has the other’s public key, not its own. A key pasted without its trailing = also fails quietly.
Check that the client’s address sits inside the AllowedIPs the server lists for that peer (10.8.0.2/32), and that the client’s AllowedIPs include 10.8.0.1. If ufw filters traffic arriving on the tunnel, allow it.
sudo ufw allow in on wg0The file is readable by other users. Restrict it, then restart the interface.
sudo chmod 600 /etc/wireguard/wg0.conf
sudo systemctl restart wg-quick@wg0Read the most recent log lines for the unit. A mistyped key or a missing = is the usual cause.
journalctl -u wg-quick@wg0 -n 30A NAT router between client and server is forgetting the connection. Keep PersistentKeepalive = 25 in the client’s [Peer] section.
Another interface or service is listening on it. Find out which, then change ListenPort and the client’s Endpoint to match.
sudo ss -ulpn | grep 51820