WireGuard is an easy-to-configure VPN: it builds an encrypted tunnel between two or more machines that can carry all of their network traffic. With a WireGuard server running on your own KVM VPS, your browsing stays encrypted even on public Wi-Fi (in a café, a hotel or an airport), and websites see you with the VPS’s IP address. This article covers installing the server, adding clients, checking the connection and common errors.
We tested the steps in November 2026 on Ubuntu 24.04, Debian 13.7, AlmaLinux 9.9 and AlmaLinux 10.3 as the server, with an Ubuntu 26.04 machine as the client; for the full tunnel we also used tcpdump on the server to check that the client’s traffic really leaves through the VPS. On Rocky Linux the steps are the same as on AlmaLinux, but we have not tested them there. If you are interested in how a VPN works in general, a comparison of OpenVPN and WireGuard, or a version running on your home router, see the post Setting up your own VPN server for home or remote access.
Why run your own VPN server on a VPS?
- Safe browsing on untrusted networks. All your traffic travels encrypted to the VPS, so the operator of the public Wi-Fi or another user cannot see which sites you open, nor tamper with the traffic. Websites see the VPS’s IP address.
- Access to internal services without a public port. An admin interface, a database or a monitoring page can listen on the VPN address only (
10.8.0.1in the example), so it cannot be reached from the internet at all, but it can from your own devices. - Connecting several machines. Your laptop, your phone and your other servers join a shared, encrypted internal network and reach each other through the VPS.
If you only want to route your browser’s traffic through the server, or open a web interface running on a single server, SSH is often enough, with nothing to install. An SSH SOCKS proxy is not a VPN, though: only the programs you configure it in use it (typically the browser), and it carries TCP connections only. WireGuard creates a network interface on the machine, so the traffic of every program and protocol (UDP, DNS and ping too) can go through it, on phones as well, and the connection recovers by itself after a network change.
WireGuard in brief
WireGuard has been part of the Linux kernel since version 5.6 in March 2020, so on current distributions you don’t need to compile or install a separate kernel module: installing the userspace tools, the wireguard-tools package (with the wg and wg-quick commands), is enough. WireGuard carries the encrypted IP packets over UDP. The examples in the official documentation use UDP port 51820, and this is the port usually used, but it is only a convention, not a mandatory default: the port is set by the ListenPort line of the configuration, and if that line is missing, wg picks a random port. The machines (peers in WireGuard terms) authenticate each other with Curve25519 key pairs: each has a secret, private key, and the others identify it by its public key, much like logging in with an SSH key. There is no username, password or certificate.
In Red Hat Enterprise Linux 9 and 10, WireGuard is a ‘Technology Preview’, meaning that Red Hat provides no product support for it; the RHEL 10.2 release notes list it that way too, not as deprecated. The AlmaLinux kernel even prints this when the module is loaded (sudo dmesg):
wireguard: WireGuard 1.0.0 loaded. See www.wireguard.com for information.
TECH PREVIEW: WireGuard may not be fully supported.
Even so, on AlmaLinux 9 and 10 the module is included in the stock kernel, and the wireguard-tools package is in the stock AppStream repository; in our test it worked without errors on both systems, with SELinux in Enforcing mode as well.
What do you need?
- A Linux VPS with root or
sudoprivileges, and SSH access to it (see How do I connect to my VPS via SSH?). - The public IP address of the VPS (
203.0.113.25in the examples). - A private internal address range for the VPN that does not clash with your home or office network. The example uses the
10.8.0.0/24range: the server gets10.8.0.1, the laptop10.8.0.2and the phone10.8.0.3.
WireGuard runs in the kernel, with no separate background process (wg-quick only sets up the interface, then exits), so a small VPS is enough; in our test, virtual machines with 1 GB of memory served as the servers. With heavy traffic, the encryption takes CPU time.
1. Installing wireguard-tools
On Ubuntu and Debian (nftables is needed for the address translation, see below; it was not installed on the Debian 13 cloud image, but it was on Ubuntu 24.04):
sudo apt update
sudo apt install wireguard-tools nftables
On AlmaLinux 9 and 10, and on Rocky Linux:
sudo dnf install wireguard-tools
In our test, version 1.0.20210914 of wireguard-tools was installed on Ubuntu 24.04, Debian 13 and AlmaLinux 9, and version 1.0.20250521 on AlmaLinux 10 and Ubuntu 26.04. You don’t need to load the kernel module separately: wg-quick loads it on the first start.
2. The server’s key pair
The keys go into the /etc/wireguard directory, which only root can read. umask 077 makes sure that the files created are readable only by root as well:
sudo sh -c 'umask 077; wg genkey | tee /etc/wireguard/server.key | wg pubkey > /etc/wireguard/server.pub'
sudo cat /etc/wireguard/server.pub
wg genkey creates the private key, and wg pubkey derives the public key from it. The public key printed (a 44-character string ending in =) goes into the clients’ configuration. Never give out the contents of server.key or copy them anywhere public.
3. The server configuration
First check which network interface the server uses to reach the internet:
ip route show default
default via 203.0.113.1 dev eth0 proto static
The name after dev (eth0 here; in our test it was enp0s1 on Ubuntu and Debian, eth0 on AlmaLinux) is needed for the address translation rule. Then create the /etc/wireguard/wg0.conf file, again with permissions that let only root read it:
sudo sh -c 'umask 077; nano /etc/wireguard/wg0.conf'
Ubuntu and Debian
[Interface]
# the server's address in the VPN
Address = 10.8.0.1/24
ListenPort = 51820
# the contents of /etc/wireguard/server.key
PrivateKey = <the server's private key>
# NAT: traffic from the VPN leaves with the server's IP address (replace eth0 with the name of your own interface)
PostUp = nft add table ip wgnat; nft add chain ip wgnat postrouting '{ type nat hook postrouting priority srcnat; }'; nft add rule ip wgnat postrouting ip saddr 10.8.0.0/24 oifname "eth0" masquerade
PostDown = nft delete table ip wgnat
When the tunnel starts, the PostUp line creates a separate wgnat nftables table with a single address translation (masquerade) rule, and PostDown deletes it when the tunnel stops. This table works alongside the ufw rules, and ufw reload does not delete it either.
If the nftables service also runs on the server (on Debian it is disabled by default), the first line of /etc/nftables.conf (flush ruleset) deletes every table when the service is restarted, the wgnat table included. In that case, restart WireGuard afterwards as well: sudo systemctl restart wg-quick@wg0.
AlmaLinux and Rocky Linux
Here firewalld does the address translation (see the next step), so the configuration is shorter:
[Interface]
# the server's address in the VPN
Address = 10.8.0.1/24
ListenPort = 51820
# the contents of /etc/wireguard/server.key
PrivateKey = <the server's private key>
4. IP forwarding and firewall
The server has to forward the packets arriving from the VPN towards the internet. Enable this in a sysctl file of its own so that it persists after a reboot (the same on every system):
echo 'net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system
The output must include the line * Applying /etc/sysctl.d/99-wireguard.conf .... Debian 13 has no /etc/sysctl.conf file, so there this drop-in directory is the only place.
ufw (Ubuntu)
If you don’t use ufw, skip this part: the nftables rule above is enough on its own. If ufw is enabled, by default it blocks all incoming and all forwarded (routed) traffic. Allow the WireGuard UDP port, and forwarding from the VPN towards the internet:
sudo ufw allow 51820/udp
sudo ufw route allow in on wg0 out on eth0
If you are enabling ufw for the first time now, allow SSH first (sudo ufw allow OpenSSH), or you will lock yourself out. The basics are covered in How do I set up a firewall on my VPS?.
firewalld (AlmaLinux, Rocky Linux)
sudo firewall-cmd --permanent --add-port=51820/udp
sudo firewall-cmd --permanent --add-masquerade
sudo firewall-cmd --reload
--add-masquerade translates the address of the traffic leaving through the public zone to the server’s address. In our test, firewalld (1.3.4 on AlmaLinux 9, 2.4.3 on AlmaLinux 10) forwarded the VPN clients’ internet traffic with these two rules alone. On the AlmaLinux cloud images firewalld was not installed; if you don’t have it either, run the commands above after sudo dnf install firewalld and sudo systemctl enable --now firewalld.
5. Starting WireGuard
sudo systemctl enable --now wg-quick@wg0
sudo wg show
The wg-quick@wg0 service uses /etc/wireguard/wg0.conf to create the wg0 interface, and it also starts at boot. At this point wg show shows only the server:
interface: wg0
public key: L/UC2CKSjsekZbOeHuiMS07rEo8ugu2uYzcvKU1Yc1U=
private key: (hidden)
listening port: 51820
You can check that the server is really listening with sudo ss -lunp | grep 51820 (on listing ports, see Check Open Ports on Linux: ss, lsof and netstat). On all four systems the tunnel came back up after a reboot, together with the address translation and the firewall rules.
6. Adding a client
Every device (laptop, phone, another server) gets its own key pair and its own VPN address. That way you can lock out a lost phone without touching the other devices.
The client’s key pair
On a Linux client, install the wireguard-tools package there too, and create the key pair on the client itself, so the private key never leaves the machine:
sudo sh -c 'umask 077; wg genkey | tee /etc/wireguard/laptop.key | wg pubkey > /etc/wireguard/laptop.pub'
sudo cat /etc/wireguard/laptop.pub
Adding the client to the server
At the end of wg0.conf on the server, add a [Peer] section with the client’s public key and VPN address:
# laptop
[Peer]
PublicKey = <the laptop's public key>
AllowedIPs = 10.8.0.2/32
On the server side, AllowedIPs means that the server accepts only packets with the source address 10.8.0.2 from this client, and sends packets addressed to 10.8.0.2 to this client. That is why each client gets its own /32 address.
To apply the change you don’t need to restart the tunnel, and clients already connected stay connected:
sudo systemctl reload wg-quick@wg0
In the background, reload runs the command wg syncconf wg0 <(wg-quick strip wg0): it applies only the difference between the file and the running state. With sudo wg set wg0 peer <public key> allowed-ips 10.8.0.3/32 you can also add a client without editing the file, but this applies to the running tunnel only: in our test, a client added this way disappeared after WireGuard was restarted. So always write it into the wg0.conf file.
The client configuration (Linux)
On the client, create the /etc/wireguard/wg0.conf file (sudo sh -c 'umask 077; nano /etc/wireguard/wg0.conf'):
[Interface]
# the contents of /etc/wireguard/laptop.key
PrivateKey = <the laptop's private key>
Address = 10.8.0.2/24
# DNS resolver through the tunnel (any resolver you trust will do)
DNS = 9.9.9.9
[Peer]
# the server's public key (server.pub)
PublicKey = <the server's public key>
# the VPS's public IP address and the WireGuard port
Endpoint = 203.0.113.25:51820
# full tunnel: all IPv4 and IPv6 traffic goes through the VPN
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25
What the lines do:
AllowedIPson the client side sets which addresses’ traffic goes into the tunnel.0.0.0.0/0, ::/0is the full tunnel: all traffic leaves through the VPS. If you only want to reach the VPN’s internal network (the server and the other clients) and keep your browsing on your own connection, writeAllowedIPs = 10.8.0.0/24. In our test, the10.8.0.xaddresses then went overwg0, and everything else over the local network.DNS: in a full tunnel, name resolution should go through the tunnel too; otherwise the queries go to the local network’s resolver, outside the VPN (see Common errors). TheDNSline needsresolvconfon the client; on Ubuntu and Debian thesystemd-resolvedpackage provides it.PersistentKeepalive = 25: the client sends a small packet every 25 seconds so that NAT devices in between (your home router, the mobile operator) don’t forget the connection. The WireGuard documentation recommends this value too; it is not needed on the server side.Endpoint: instead of an IP address, a domain name can go here (for examplevpn.pelda.hu:51820) if anArecord points to the VPS’s address.- The client’s
[Interface]section has noListenPort, so it gets a random port (38802 in our test, for example).
Starting and stopping:
sudo wg-quick up wg0
sudo wg-quick down wg0
If the client should always be connected too, you can set it up as a service in the same way: sudo systemctl enable --now wg-quick@wg0.
Phone: configuration by QR code
On a phone, the official WireGuard app (Android, iOS) can also read the configuration from a QR code, and on Windows and macOS the official app imports the .conf file. In that case you can also create the key pair on the server and then show the finished configuration as a QR code in the terminal. This needs the qrencode package: on Ubuntu and Debian sudo apt install qrencode; on AlmaLinux it can be installed from the EPEL repository (sudo dnf install epel-release, then sudo dnf install qrencode; in detail: Installing the EPEL repository on AlmaLinux).
sudo sh -c 'umask 077; wg genkey | tee /etc/wireguard/telefon.key | wg pubkey > /etc/wireguard/telefon.pub'
Add the phone to the server’s wg0.conf file as a [Peer] (AllowedIPs = 10.8.0.3/32), run sudo systemctl reload wg-quick@wg0, then write the phone’s configuration to the /etc/wireguard/telefon.conf file, with the same structure as the laptop’s (PrivateKey is the contents of telefon.key, Address = 10.8.0.3/24). The QR code:
sudo qrencode -t ansiutf8 -r /etc/wireguard/telefon.conf
Because of the -r option, qrencode reads the file itself; the form sudo qrencode ... < file does not work, because the input would be opened by your own user, who has no permission to read it. After scanning, delete the phone’s key and configuration from the server; only its public key remains in the server’s wg0.conf file:
sudo rm /etc/wireguard/telefon.key /etc/wireguard/telefon.conf
The QR code contains the private key: don’t photograph it, and don’t display it where others can see it.
7. Checking the connection
On the client, sudo wg show indicates a successful connection with the latest handshake line:
interface: wg0
public key: 509FXrsngphGeLkubh6MsZDTkwa3Y2md9Jj8CRBMekU=
private key: (hidden)
listening port: 44606
fwmark: 0xca6c
peer: L/UC2CKSjsekZbOeHuiMS07rEo8ugu2uYzcvKU1Yc1U=
endpoint: 203.0.113.25:51820
allowed ips: 0.0.0.0/0, ::/0
latest handshake: 3 seconds ago
transfer: 52.78 KiB received, 4.95 KiB sent
persistent keepalive: every 25 seconds
On the server, sudo wg show shows for each client where it connected from (endpoint), when the last handshake took place and how much data has passed. A client that has not connected yet appears only with the peer and allowed ips lines.
In a full tunnel, the client reaches the internet through the VPS. You can check this on the client as follows:
ping -c 2 10.8.0.1
ip route get 1.1.1.1
curl -4 ifconfig.me
1.1.1.1 dev wg0 table 51820 src 10.8.0.2 uid 1000
In the response of ip route get, dev wg0 shows that the traffic goes into the tunnel, and curl -4 ifconfig.me prints the VPS’s IP address (203.0.113.25 in the example), not that of your own internet connection. Don’t look for the default route on wg0 in the plain ip route output: for a full tunnel, wg-quick uses a separate routing table (51820) and rules, which ip rule shows. On the server, while sudo tcpdump -ni any host 1.1.1.1 is running, you can see the packet arrive on wg0 from the client’s VPN address (10.8.0.2) and leave on the outgoing interface with the server’s address. Network troubleshooting tools are covered in Network troubleshooting: ping, traceroute, mtr, dig and curl.
Internal services and client-to-client access
If a service on the server listens on the VPN address only (for example an admin interface on 10.8.0.1:8080), or the clients should reach each other, the firewall has to allow that too. In our test, neither worked without an extra rule.
On Ubuntu with ufw, a given port from the VPN, and traffic between clients:
sudo ufw allow in on wg0 to any port 8080 proto tcp
sudo ufw route allow in on wg0 out on wg0
Careful: by default ufw lets forwarded ping through, so ping may work between clients even while a TCP connection (SSH or HTTP, for example) is still blocked. In that case the log (sudo journalctl -k | grep UFW) shows [UFW BLOCK] IN=wg0 OUT=wg0 lines.
On AlmaLinux, the simplest way is to put the wg0 interface into the trusted zone:
sudo firewall-cmd --permanent --zone=trusted --add-interface=wg0
sudo firewall-cmd --reload
This lets the VPN clients reach every service on the server and each other, and the address translation of their internet traffic keeps working; in our test the setting persisted after a reboot as well. Only choose this if you let nothing but your own, trusted devices into the VPN; otherwise allow the ports you need one by one instead of using the trusted zone.
IPv6
Our KVM VPS servers get both an IPv4 and an IPv6 address by default. The example in this article uses IPv4 addresses only inside the tunnel, yet the client’s AllowedIPs line includes ::/0, and for a reason: without it, on an IPv6-capable network the client’s IPv6 traffic would bypass the tunnel and leave over the local connection. In our test, without ::/0, ip -6 route get showed the local interface, and with it, wg0; this way IPv6 traffic goes into the tunnel, and as the server does not forward it, it does not leak past the VPN. To route IPv6 through the tunnel as well, you need IPv6 addresses in the VPN and IPv6 forwarding on the server; this article does not cover that.
If you run WireGuard on a VPS that has an IPv6 address only, the Endpoint line takes the server’s IPv6 address in square brackets (Endpoint = [2001:db8::25]:51820), and you can connect only from networks that have IPv6 connectivity. For more on this, see IPv6-only VPS: pros, cons and workarounds.
Common errors
- No handshake: the client’s
wg showoutput has nolatest handshakeline, and thetransferline says0 B received. The most common cause is that the server’s firewall does not allow the UDP port: in our test, with ufw the log then showed[UFW BLOCK] ... PROTO=UDP ... DPT=51820lines, and with firewalld the client’s packets went unanswered. Also check that the client’sEndpointline has the VPS’s IP address and the port that matchesListenPort, and that the keys are not swapped: the client’s configuration takes the server’s public key, the server’s takes the client’s. WireGuard does not respond to packets with a wrong key and does not log them either, so with a wrong key nothing shows on the server. - There is a handshake and
ping 10.8.0.1works, but there is no internet: the server is not forwarding or not translating the traffic. Check thatcat /proc/sys/net/ipv4/ip_forwardreturns1, and that the address translation rule exists (sudo nft list table ip wgnat, orsudo firewall-cmd --list-allshowingmasquerade: yes). In our test, a wrong interface name in the nftables rule (eth0instead of the realenp0s1) caused the same: the packets left with the source address10.8.0.2instead of the server’s address, and no reply came back. With ufw, a missingroute allowrule causes this too; the log then shows[UFW BLOCK] IN=wg0 OUT=eth0. - No connection for a while after WireGuard is restarted on the server: after
systemctl restart wg-quick@wg0(or a server reboot) the clients reconnect by themselves, but not immediately; in our test it took 17 seconds.systemctl reloaddoes not drop connections, so use that to add or remove clients. - A client no longer connects after the server is restarted: you probably added it with
wg set, and it is not in thewg0.conffile. Add it to the file and runsudo systemctl reload wg-quick@wg0. - DNS queries bypass the VPN: if the client configuration has no
DNSline, the machine asks the local network’s resolver; as that resolver is on the local network, the queries go over the local connection even with a full tunnel. In our test, with theDNS = 9.9.9.9line,resolvectl dnsassigned the resolver towg0, and on the server the DNS queries arrived onwg0. Ifwg-quick upfails becauseresolvconfis missing, install thesystemd-resolvedpackage (on Ubuntu and Debian), or delete theDNSline. - Some pages don’t load, or larger downloads stall: this may point to the tunnel’s packet size (MTU). By default
wg-quicksets 1420 bytes (as it did in our test), which is fine on most connections; some mobile or PPPoE connections may need a smaller value. In the client’s[Interface]section, try the lineMTU = 1380. This problem did not occur in our test.
wg-quick prints every command it runs ([#] ip link add dev wg0 type wireguard and so on); sudo journalctl -u wg-quick@wg0 shows the service’s log.
Security
- Protecting the private keys: the
/etc/wireguarddirectory and the files in it should be readable only by root (that is whatumask 077is for). Anyone who obtains a private key can connect as that device. Don’t send the configuration files by email or chat, and don’t put them into version control. - Locking out a device: if a phone is lost, or you no longer use a device, delete its
[Peer]section from the server’swg0.conffile, then runsudo systemctl reload wg-quick@wg0. In our test, the deleted client disappeared from thewg showlist immediately, and the other clients stayed connected. The key on the device is then useless, and the other devices don’t need new keys. - Open port: the WireGuard port does not ‘talk’: the server does not respond to unauthenticated packets at all, so a port scanner cannot tell whether anything is running on it. The server’s other services, above all SSH, still need protecting: SSH server security settings.
- Updates: WireGuard is part of the kernel, so you get its security fixes with the system’s usual kernel updates.