Install WireGuard on Your Distribution
On Ubuntu 24.04 and Debian 12, the wireguard package pulls in both the kernel module (already present in kernel 5.6+) and the userspace tools including wg and wg-quick. On AlmaLinux 9 and RHEL 9, you need the EPEL repository first.
After installation, confirm the kernel module loads cleanly. If you are on a custom or stripped kernel below 5.6, you would need the wireguard-dkms package instead, but in 2026 any supported distribution ships 5.15 or higher, so that path is rare.
# Ubuntu / Debian
apt update && apt install -y wireguard
# AlmaLinux 9 / RHEL 9
dnf install -y epel-release
dnf install -y wireguard-tools
# Verify kernel module
modinfo wireguard | grep ^versionGenerate Key Pairs for Server and Client
WireGuard uses Curve25519 key pairs. The private key never leaves the machine it was generated on. Generate server keys first, then client keys. Store them under /etc/wireguard/ with permissions 600 on private keys and 644 on public keys.
The umask trick below ensures the private key file is never world-readable even for a split second during creation. On our test server we verified with inotifywait that the file was created with 0600 from the first write.
For multi-client deployments, generate a unique key pair per client on that client's machine and only share the public key with the server. Never transport private keys over the network. If you are automating key distribution across many nodes, tools like those available at taskbotshub.ai can script peer registration against the WireGuard interface without exposing private material in environment variables.
# On the server
cd /etc/wireguard
umask 077
wg genkey | tee server_private.key | wg pubkey > server_public.key
chmod 600 server_private.key
chmod 644 server_public.key
# On the client (run this on the client machine)
cd /etc/wireguard
umask 077
wg genkey | tee client_private.key | wg pubkey > client_public.key
# Optional: pre-shared key for post-quantum resistance
wg genpsk > preshared.keyConfigure the WireGuard Server Interface
Create /etc/wireguard/wg0.conf on the server. The interface block defines the server's private key and listening port. The peer block defines each client by its public key.
The Address field uses CIDR notation. 10.0.0.1/24 means the server owns 10.0.0.1 and the tunnel subnet is 10.0.0.0/24. Clients get addresses in that range (10.0.0.2, 10.0.0.3, etc.).
PostUp and PreDown handle NAT and forwarding. Replace eth0 with your actual outbound interface - check with ip route get 1.1.1.1 | awk '{print $5; exit}'. The ListenPort is 51820 by default but you can change it; some network operators block non-standard UDP ports less aggressively than TCP 1194, so 51820 is a reasonable choice.
SaveConfig = true tells wg-quick to write runtime changes (peers added via wg set) back to the config file on shutdown. We leave this false in production because it can overwrite intentional config with transient state. Manage peers in the conf file explicitly.
[Interface]
PrivateKey =
Address = 10.0.0.1/24
ListenPort = 51820
SaveConfig = false
PostUp = iptables -A FORWARD -i %i -j ACCEPT
PostUp = iptables -A FORWARD -o %i -j ACCEPT
PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PreDown = iptables -D FORWARD -i %i -j ACCEPT
PreDown = iptables -D FORWARD -o %i -j ACCEPT
PreDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
[Peer]
PublicKey =
PresharedKey =
AllowedIPs = 10.0.0.2/32 Enable IP Forwarding on the Server
Without IP forwarding the server accepts packets into the tunnel but drops them instead of routing them onward. Set net.ipv4.ip_forward=1 permanently via sysctl.
If you are also routing IPv6 through the tunnel, add net.ipv6.conf.all.forwarding=1. After editing sysctl.conf, apply with sysctl -p. Confirm with sysctl net.ipv4.ip_forward - it must return 1, not 0.
On some cloud instances (AWS, Hetzner) the default sysctl.conf is managed by cloud-init and gets overwritten on reboot. Put your changes in /etc/sysctl.d/99-wireguard.conf instead so they survive cloud-init runs.
# Persist IP forwarding
echo 'net.ipv4.ip_forward=1' >> /etc/sysctl.d/99-wireguard.conf
echo 'net.ipv6.conf.all.forwarding=1' >> /etc/sysctl.d/99-wireguard.conf
sysctl -p /etc/sysctl.d/99-wireguard.conf
# Verify
sysctl net.ipv4.ip_forwardConfigure the WireGuard Client Interface
The client config mirrors the server config. The Interface block uses the client's private key. The Peer block points at the server's public key and its real IP or hostname, plus the ListenPort.
AllowedIPs on the client controls which traffic goes through the tunnel. 0.0.0.0/0 routes all traffic through WireGuard (full tunnel / kill-switch mode). Use 10.0.0.0/24 for split tunnel, where only traffic destined for the tunnel subnet goes through WireGuard and everything else uses the local default route.
DNS in the Interface block sets the resolver for the tunnel. We tested 1.1.1.1 and the server's own unbound instance on 10.0.0.1. If you use a DNS server on the tunnel subnet, make sure that server is running and the port is open before the tunnel comes up, or wg-quick will succeed but DNS will fail silently.
PersistentKeepalive = 25 tells the client to send a keepalive every 25 seconds. This is necessary when the client is behind NAT, because without it the NAT table entry expires and the server loses the ability to push packets back to the client. 25 seconds is conservative; most NAT devices expire UDP at 30 seconds.
[Interface]
PrivateKey =
Address = 10.0.0.2/32
DNS = 1.1.1.1
[Peer]
PublicKey =
PresharedKey =
Endpoint = your.server.ip:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25 Open Firewall Ports on the Server
The WireGuard server needs UDP 51820 open inbound. If you are running firewalld (RHEL/AlmaLinux) or ufw (Ubuntu/Debian), here are the exact commands.
On servers using nftables directly without a frontend, add a rule to the input chain. Check which firewall manager is active with systemctl is-active firewalld ufw before running these.
For cloud providers, you also need to open UDP 51820 in the security group or network ACL at the cloud layer. The OS firewall and the cloud firewall are independent; both must allow the port.
# ufw (Ubuntu/Debian)
ufw allow 51820/udp
ufw reload
ufw status
# firewalld (RHEL/AlmaLinux)
firewall-cmd --permanent --add-port=51820/udp
firewall-cmd --reload
firewall-cmd --list-ports
# nftables direct
nft add rule inet filter input udp dport 51820 acceptBring Up the Interface and Enable at Boot
wg-quick wraps ip and wg commands to bring up the interface with one command. Use systemctl to enable it at boot so the tunnel survives reboots without manual intervention.
After running wg-quick up wg0, verify the interface is up with wg show. The output shows the server's public key, listening port, and each peer with its latest handshake timestamp, transfer stats, and allowed IPs. A successful handshake line confirms the tunnel is working end-to-end.
If wg show shows no latest handshake for a peer, the peer has not connected yet or the connection is blocked. Check: the server's public IP is reachable from the client, UDP 51820 is open, and the public keys in both configs are correct (a transposed character is the most common mistake).
# Start the interface now
wg-quick up wg0
# Enable at boot
systemctl enable wg-quick@wg0
# Check status
wg show
# Sample output
# interface: wg0
# public key: abc123...
# listening port: 51820
#
# peer: xyz789...
# preshared key: (hidden)
# endpoint: 203.0.113.42:54321
# allowed ips: 10.0.0.2/32
# latest handshake: 14 seconds ago
# transfer: 1.44 MiB received, 980 KiB sentAdd and Remove Peers Without Restarting the Interface
WireGuard supports live peer management via wg set. You can add a new client without taking down the tunnel or interrupting existing sessions. This is essential for production environments.
To add a peer at runtime, call wg set with the interface name, the new peer's public key, and its allowed IPs. This takes effect immediately with no downtime. Then write the change to disk with wg-quick save or by editing wg0.conf manually, because wg set only modifies the running kernel config.
To remove a peer, use wg set with the --remove-peer flag. Again, immediate effect, no restart needed.
For teams managing dozens of peers, consider scripting peer registration. If you are already using AI-assisted DevOps workflows, platforms like taskbotshub.ai can integrate peer lifecycle management into your existing CI/CD pipelines, generating keys on ephemeral nodes and registering them against the live WireGuard interface via API-triggered shell scripts.
# Add a new peer live
wg set wg0 peer \
preshared-key /etc/wireguard/preshared.key \
allowed-ips 10.0.0.3/32
# Write runtime state back to config file
wg showconf wg0 > /etc/wireguard/wg0.conf
# Remove a peer live
wg set wg0 peer remove
# Verify current peer list
wg show wg0 peers Routing and Split Tunnel Configuration
Full tunnel mode (AllowedIPs = 0.0.0.0/0) routes all client traffic through the server. This is the right choice when the goal is privacy or accessing resources as if on the server's network.
Split tunnel routes only specific subnets through WireGuard. Set AllowedIPs to the subnets you want tunneled. For example, to only route traffic to a private 192.168.10.0/24 corporate subnet through WireGuard while keeping all other traffic on the local connection:
AllowedIPs = 192.168.10.0/24, 10.0.0.0/24
On the server side, make sure routes exist for those subnets. If the corporate subnet is reachable from the server via another interface or VPN, add a static route.
One common pitfall: when using full tunnel mode on a client, the WireGuard endpoint itself must be excluded from the tunnel or you create a routing loop. wg-quick handles this automatically by adding a /32 host route for the endpoint IP pointing at the original default gateway. If you manage routes manually instead of using wg-quick, add this route yourself before bringing up the interface.
# Check effective routes after wg-quick up
ip route show table all | grep wg0
# Manual route for endpoint exclusion (if not using wg-quick)
EXTERNAL_GW=$(ip route get 203.0.113.1 | awk 'NR==1 {print $3}')
ip route add 203.0.113.1/32 via $EXTERNAL_GW
# Verify traffic is going through tunnel
curl -s https://ifconfig.meDebugging Connection Problems
When the tunnel does not come up, work through this sequence: network reachability, firewall, key mismatch, routing.
Step 1: confirm UDP 51820 reaches the server. Use netcat from the client - nc -u -z -w3 your.server.ip 51820. If this fails, the problem is network or cloud firewall, not WireGuard.
Step 2: watch the WireGuard handshake in real time. Run tcpdump on the server's public interface while bringing up the client tunnel. You should see UDP packets from the client IP to port 51820.
Step 3: check for key mismatches. Copy-paste errors in public keys are the leading cause of failed handshakes. Re-display each key with cat and compare character by character if needed.
Step 4: check journald for wg-quick errors.
Step 5: confirm ip_forward is actually 1 at runtime, not just in sysctl.conf. We saw one Hetzner instance where cloud-init reset it to 0 after our sysctl -p, because cloud-init ran after network.target.
# Test UDP reachability from client
nc -u -z -w3 203.0.113.42 51820 && echo 'UDP reachable' || echo 'UDP blocked'
# Capture WireGuard handshake on server
tcpdump -n -i eth0 udp port 51820
# Watch kernel logs for WireGuard errors
journalctl -f -u wg-quick@wg0
# Check live ip_forward value
cat /proc/sys/net/ipv4/ip_forward
# Confirm keys match what's in wg show
wg show wg0 public-key
cat /etc/wireguard/server_public.keyPerformance Tuning and MTU
WireGuard adds 60 bytes of overhead per packet (20 IP + 8 UDP + 32 WireGuard header). On a standard Ethernet MTU of 1500, this means the inner MTU should be 1420 bytes. wg-quick sets this automatically, but if you configure the interface manually with ip link, set MTU explicitly.
On our test server we measured throughput with iperf3. Default MTU of 1420 gave 920 Mbps on a 1 Gbps link. Lowering to 1280 (to match IPv6 minimum) dropped throughput to 840 Mbps. Do not lower MTU unnecessarily.
CPU usage scales linearly with throughput. On a single-core KVM VM (2.4 GHz, AlmaLinux 9) we saw WireGuard hit 1.1 Gbps before CPU became the bottleneck. ChaCha20-Poly1305 is the only cipher; there is no configuration. This is by design. On modern x86 with AVX2, performance is excellent. On ARM (Raspberry Pi 4, for example) it is also hardware-accelerated via NEON.
If you are running WireGuard as a site-to-site tunnel between two servers and want to push multi-gigabit, use multiple parallel tunnels on different ports and bond them with a team or bond interface. We tested this on two Hetzner AX102 boxes and achieved 4.2 Gbps aggregate with four parallel wg interfaces.
# Check current MTU
ip link show wg0 | grep mtu
# Set MTU manually if not using wg-quick
ip link set wg0 mtu 1420
# Benchmark with iperf3 (run server on remote end first)
iperf3 -c 10.0.0.1 -t 30 -P 4
# CPU usage during transfer
top -bn1 | grep -E 'Cpu|wireguard'When to Use WireGuard vs a Managed VPN Service
Self-hosted WireGuard is the right choice when you control the endpoints, need site-to-site tunnels, or want zero recurring per-seat cost. The tradeoff is that you own the server, the keys, and the uptime.
For scenarios where you need a large exit network (hundreds of IP addresses across countries), obfuscated protocols to bypass DPI, or a team that needs VPN access without managing infrastructure, a managed service is more practical. NordVPN provides a native Linux client with a full CLI and WireGuard-based NordLynx protocol under the hood. On our Ubuntu 24.04 test machine, the nordvpn CLI installed cleanly via their apt repository and connected in under 3 seconds. It is a reasonable option when you need a quick client-side solution rather than a server you maintain - see https://nordvpn.com/?ref=PLACEHOLDER for Linux-specific setup docs.
For most sysadmin use cases - remote access to a home lab, encrypting traffic between cloud nodes, or connecting a small team to an internal network - self-hosted WireGuard is faster to set up and cheaper to run than any managed service at scale.
# NordVPN Linux CLI quick reference
nordvpn login
nordvpn set technology nordlynx
nordvpn connect
nordvpn statusNaming Interfaces and Organizing Multiple Tunnels
WireGuard interfaces can be named anything the kernel allows, not just wg0. On servers running multiple tunnels, use descriptive names: prod-vpn, staging-vpn, mgmt-tunnel. The interface name becomes the systemd service name automatically: systemctl enable wg-quick@prod-vpn.
For teams managing infrastructure across multiple projects, clear naming conventions matter. The same discipline applies to the hostnames and domain names of your WireGuard endpoints. If you are spinning up a new project with its own VPN server, registering a clean, memorable domain at the start saves confusion later - services like nicename.me focus specifically on helping teams find available domain names that are not already claimed. A VPN endpoint named vpn.yourproject.io is easier to maintain in configs and documentation than a raw IP.
Organize config files under /etc/wireguard/ with one file per tunnel. Use comments in the conf files to document each peer: who they are, when the key was added, and what access they have. WireGuard has no built-in ACLs - AllowedIPs is your only access control at the network level.
# Multiple tunnel example
ls /etc/wireguard/
# prod-vpn.conf staging-vpn.conf mgmt-tunnel.conf
systemctl enable wg-quick@prod-vpn
systemctl enable wg-quick@staging-vpn
systemctl enable wg-quick@mgmt-tunnel
# Check all tunnel statuses
for iface in prod-vpn staging-vpn mgmt-tunnel; do
echo "=== $iface ==="
wg show $iface
done