Cycle's hosted MCP is live. Your AI tooling just learned DevOps.Read the announcement

Configuring WireGuard.

WireGuard is an encrypted tunnel built into the Linux kernel that runs over UDP and authenticates every peer by its public key. A full config is a private key, a listening port and one short block per peer. There's no certificate authority, no cipher negotiation and no daemon in the data path.

That makes it a good fit for one specific job: encrypting traffic between servers that talk over networks you don't control. Two VMs in different clouds, a bare metal box and a cloud database, or a handful of nodes across regions can each get a private address on a shared encrypted subnet. Applications connect to those addresses and never touch TLS config. When workloads need a shared layer-2 network on top, a VXLAN overlay can run over the tunnel addresses.

Encrypted server-to-server traffic by default on Cycle

Hand-built WireGuard works well for a few servers. It gets more expensive as the fleet grows, because every server needs every other server's public key, endpoint and address range, and every change has to land on all of them.

If that's not something you want to manage yourself, Cycle handles server-to-server encryption in the control plane. When a server joins a cluster, Cycle maps latency, reachability and topology to its neighbors. Nodes with a private link use it. Nodes without one get an encrypted link over the public internet, with keys Cycle generates and rotates.

Cycle builds those inter-node links with IPsec, not WireGuard. The IPsec approach is covered in Configuring IPsec. The result is one flat, encrypted private network per environment across AWS, GCP, bare metal and anything else in the cluster. See how Cycle networking works.

If you manage your own servers, the rest of this page walks through configuring WireGuard by hand.

How WireGuard works

WireGuard has a small set of moving parts:

Component

What it does

Key pair

A Curve25519 private key and its public key, a form of asymmetric encryption. The public key is the peer's identity.

Interface (wg0)

A kernel network device with a private key and a UDP listening port. 51820 is the convention, not a requirement.

Peer

A public key, the IP ranges it's allowed to use (AllowedIPs) and, optionally, where to reach it (Endpoint).

Handshake

A one-round-trip key exchange based on the Noise protocol framework. Session keys rotate every two minutes or so with no config.

WireGuard doesn't answer packets it can't authenticate. A port scan sees nothing, and an unreachable peer looks identical to a silent one. The only sign of life is a recent handshake.

AllowedIPs is a routing table and a filter

AllowedIPs does two jobs, and most WireGuard bugs come from forgetting one of them.

  • Outbound, it's a routing table. When a packet leaves wg0, WireGuard picks the peer whose AllowedIPs contains the destination and encrypts to that peer's key.
  • Inbound, it's a source filter. After decrypting a packet from a peer, WireGuard drops it unless the inner source address falls inside that peer's AllowedIPs.

WireGuard calls this cryptokey routing. Each prefix can belong to only one peer on an interface. For server-to-server links, give each peer its own /32 tunnel address and nothing broader. 0.0.0.0/0 sends all of a server's traffic to one peer, which is right for a laptop VPN and wrong for a server.

Before you start

The examples use three servers, starting with two and adding the third as a small mesh:

Host

Public IP

Tunnel IP (wg0)

server-a

203.0.113.10

10.100.0.1/24

server-b

198.51.100.20

10.100.0.2/24

server-c

192.0.2.30

10.100.0.3/24

You need root on each. WireGuard has been in the mainline kernel since 5.6, so current Ubuntu, Debian and RHEL releases ship the module. Red Hat ships it on RHEL as an unsupported Technology Preview. You only install the userspace tools: wg for keys and inspection, and wg-quick for bringing interfaces up from a config file.

Step 1: Install the tools

On Debian and Ubuntu:

sudo apt install wireguard-tools

On RHEL, Rocky and AlmaLinux:

sudo dnf install wireguard-tools

Step 2: Generate a key pair on each server

Run this on every server, as root, in /etc/wireguard:

sudo -i
cd /etc/wireguard
umask 077
wg genkey | tee private.key | wg pubkey > public.key

umask 077 makes the private key readable by root only. The private key never leaves the server. Copy each public.key to the other servers over a channel you already trust, such as SSH.

Step 3: Open the firewall

Each server must accept WireGuard from its peers. On server-a, with nftables and an existing inet filter table:

sudo nft add rule inet filter input ip saddr { 198.51.100.20, 192.0.2.30 } udp dport 51820 accept

That rule admits the encrypted packets. Decrypted traffic then arrives on wg0 and passes through the same input chain, so on a server whose input policy drops by default, accept it as well:

sudo nft add rule inet filter input iifname "wg0" accept

Mirror both rules on the other servers, and add them to /etc/nftables.conf with nftables.service enabled so they survive a reboot. Cloud security groups need the same UDP rule.

Step 4: Configure server-a

Create /etc/wireguard/wg0.conf on server-a:

[Interface]
Address = 10.100.0.1/24
ListenPort = 51820
PrivateKey = <contents of server-a's private.key>
[Peer]
# server-b
PublicKey = <contents of server-b's public.key>
AllowedIPs = 10.100.0.2/32
Endpoint = 198.51.100.20:51820

What the key lines do:

  • Address is this server's tunnel IP. wg-quick assigns it to wg0.
  • ListenPort fixes the UDP port so peers and firewall rules can rely on it.
  • AllowedIPs = 10.100.0.2/32 routes packets for 10.100.0.2 to server-b and accepts only that source from it.
  • Endpoint is where to send the first handshake. If the peer roams, WireGuard updates the endpoint from authenticated packets it receives.

Lock down the file, since it holds the private key:

sudo chmod 600 /etc/wireguard/wg0.conf

Step 5: Configure server-b

On server-b, the mirror image:

[Interface]
Address = 10.100.0.2/24
ListenPort = 51820
PrivateKey = <contents of server-b's private.key>
[Peer]
# server-a
PublicKey = <contents of server-a's public.key>
AllowedIPs = 10.100.0.1/32
Endpoint = 203.0.113.10:51820

Step 6: Bring up the tunnel

On both servers:

sudo systemctl enable --now wg-quick@wg0

The wg-quick@ unit reads /etc/wireguard/wg0.conf, creates the interface, adds routes for each peer's AllowedIPs and brings it up at every boot. wg-quick also sets the MTU, defaulting to 1420 on a 1500-byte underlay to leave room for WireGuard's overhead.

Step 7: Verify the tunnel

Send traffic first. WireGuard only handshakes when there's something to send.

ping -c 3 10.100.0.2

Then check the interface state:

sudo wg show

A working tunnel looks like this:

interface: wg0
public key: <server-a public key>
private key: (hidden)
listening port: 51820
peer: <server-b public key>
endpoint: 198.51.100.20:51820
allowed ips: 10.100.0.2/32
latest handshake: 6 seconds ago
transfer: 1.12 KiB received, 1.30 KiB sent

latest handshake is the line that matters. If it's missing, the peers have never completed a handshake. To confirm the traffic is encrypted, capture the underlay with sudo tcpdump -ni eth0 udp port 51820. You should see UDP datagrams between the two public IPs and nothing readable inside them.

Step 8: Grow to a small mesh

For three servers, every server lists the other two as peers. On server-a, add a second [Peer] block:

[Peer]
# server-c
PublicKey = <contents of server-c's public.key>
AllowedIPs = 10.100.0.3/32
Endpoint = 192.0.2.30:51820

server-c gets a config with server-a and server-b as peers, and server-b adds server-c. Apply a changed config without dropping existing sessions:

sudo bash -c 'wg syncconf wg0 <(wg-quick strip wg0)'

wg-quick strip removes the wg-quick-only fields like Address, and wg syncconf applies only the peer differences. A new peer's routes aren't added by syncconf, but with Address set to a /24, the whole tunnel subnet already routes through wg0.

Peers behind NAT

When a server has no public IP, it can still reach peers that do. On the server behind NAT, set the public peer's Endpoint as usual and add:

PersistentKeepalive = 25

This sends an empty authenticated packet every 25 seconds so the NAT mapping stays open and the public peer can send traffic back. Leave Endpoint off on the public side, since it learns the address from incoming packets. Keepalives are off by default and servers with public IPs don't need them.

Troubleshooting

WireGuard logs nothing by default. journalctl -u wg-quick@wg0 shows errors from bringing the interface up, and for handshake detail you can enable kernel debug output with echo 'module wireguard +p' | sudo tee /sys/kernel/debug/dynamic_debug/control, then read dmesg.

Symptom

Likely cause

Fix

No latest handshake line

UDP 51820 blocked, wrong Endpoint or a public key pasted onto the wrong peer

Check the firewall on both sides and compare each PublicKey against the peer's public.key

Handshake succeeds, ping fails

The receiver's AllowedIPs for the sender doesn't include the sender's tunnel IP, or the receiver's firewall drops traffic arriving on wg0

Give each peer its own /32 on the other side, and accept iifname "wg0" in the input chain

Traffic meant for one peer reaches another

The same prefix is listed under two peers, and WireGuard silently keeps it only on the last one

Make every prefix belong to exactly one peer

Tunnel dies after a few idle minutes

NAT mapping expired on a server behind NAT

Add PersistentKeepalive = 25 on that server

Small requests work, large transfers stall

Path MTU smaller than the tunnel assumes, often from a nested tunnel

Set MTU = 1380 under [Interface] and lower it further if needed

wg-quick up fails with Unable to access interface: Protocol not supported

The WireGuard kernel module isn't loaded or isn't available

Run sudo modprobe wireguard, and if that fails, move to a kernel 5.6 or newer that includes it

Running WireGuard past a few servers

A full mesh of n servers is n(n-1)/2 peer relationships, and each one is written twice. Ten servers is 90 [Peer] blocks. Every new server means distributing its public key and endpoint to every existing server, and every changed IP means editing every config that lists it.

The session keys rotate on their own. The static key pairs don't, and nothing in WireGuard tracks who has which public key, which tunnel IPs are taken or when a key should be retired. That inventory is a configuration management problem you now own, alongside the firewall rules and the MTU on every path.

That's the operational layer Cycle's control plane takes off your plate, using IPsec between nodes instead of hand-maintained peer lists.

The tunnel is a few lines of config. The peer list is the part that grows.

Cookies

Cookies Preferences

We run basic, anonymous analytics by default to measure site traffic. By clicking "Accept," you allow additional cookies for advanced app improvements and tailored advertising. Choose what you share by clicking "Customize."