Wireguard Deployment | The Garnet Wiki

WireGuard is a modern, fast, and secure VPN protocol designed for simplicity and performance. It excels in deploying encrypted, low-latency point-to-point or meshed network tunnels across diverse environments—on-premises, cloud, mobile, and edge devices. Deployment of WireGuard matters when you need to securely connect distributed services, enable remote access to internal resources, or build a resilient, self-healing network fabric. It is especially effective when bandwidth, latency, or configuration complexity are constraints.

Establishing a Basic WireGuard Tunnel

To deploy a WireGuard tunnel, configure a pair of peers: a server (often a cloud instance) and a client (a laptop, mobile device, or container). Each peer has a public key, a private key, and a network interface configured with an IP address and a WireGuard configuration.

Server Configuration

On the server, create /etc/wireguard/wg0.conf:

[Interface]
ListenPort = 51820
PrivateKey = <server-private-key>
Address = 10.0.0.1/24

[Peer]
PublicKey = <client-public-key>
AllowedIPs = 10.0.0.2/32

The ListenPort defines the UDP port on which the server listens for incoming WireGuard packets. The PrivateKey is a base64-encoded 32-byte secret. The Address assigns the server’s IP within the tunnel subnet.

Client Configuration

On the client, create /etc/wireguard/wg0.conf:

[Interface]
PrivateKey = <client-private-key>
Address = 10.0.0.2/32
DNS = 1.1.1.1, 1.0.0.1

[Peer]
PublicKey = <server-public-key>
Endpoint = <server-public-ip>:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

The DNS field configures the client’s DNS resolver to use Cloudflare’s public DNS. The Endpoint specifies the server’s public IP and port. AllowedIPs = 0.0.0.0/0 routes all traffic through the tunnel. PersistentKeepalive = 25 sends a keepalive packet every 25 seconds to maintain the connection through NATs.

Starting the Tunnel

After writing the config files, enable and start the WireGuard interface:

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

This command reads the .conf file, applies the interface settings via ip link, ip addr, and ip route, and starts the wg daemon. It also creates a systemd service [email protected] that manages the interface lifecycle.

Use wg show wg0 to verify the state:

interface: wg0
  public key: <server-public-key>
  private key: (hidden)
  listening port: 51820

peer: <client-public-key>
  endpoint: <client-public-ip>:51820
  allowed ips: 10.0.0.2/32
  latest handshake: 1 minute, 12 seconds ago
  transfer: 1.2 MiB received, 340 KiB sent
  persistent keepalive: every 25 seconds

Common Failure Modes

Connection fails with No route to host on wg show: The server’s ListenPort is not open. Verify sudo ufw allow 51820/udp or sudo iptables -A INPUT -p udp --dport 51820 -j ACCEPT.
Client shows handshake failed: The client’s Endpoint IP is incorrect or the server’s public IP changed. Check ip addr show on the server and ping from client to server.
Tunnel traffic not routed: The client’s AllowedIPs list is too narrow. 10.0.0.0/24 is not enough if the server serves multiple services. Use 0.0.0.0/0 for full routing.

Scaling to Multiple Clients

To support multiple clients, update the server configuration to allow more peers:

[Interface]
ListenPort = 51820
PrivateKey = <server-private-key>
Address = 10.0.0.1/24

[Peer]
PublicKey = <client1-public-key>
AllowedIPs = 10.0.0.2/32

[Peer]
PublicKey = <client2-public-key>
AllowedIPs = 10.0.0.3/32

Each client must be manually added to the server’s config or dynamically managed via a script.

Dynamic Peer Management with `wg set`

Use wg set to modify the configuration at runtime:

sudo wg set wg0 peer <client1-public-key> \
    endpoint <client1-ip>:51820 \
    allowed-ips 10.0.0.2/32 \
    persistent-keepalive 25

This command updates the peer without restarting the interface. It is ideal for automation and orchestration.

Automating Client Registration

Create a script register-client.sh that generates a client config and returns it:

#!/bin/bash


CLIENT_NAME="$1"
CLIENT_IP="10.0.0.$(( $(wg show wg0 | grep -c "AllowedIPs") + 1 ))"

# Generate keys
CLIENT_PRIVATE_KEY=$(wg genkey)
CLIENT_PUBLIC_KEY=$(echo "$CLIENT_PRIVATE_KEY" | wg pubkey)

# Update server config
cat >> /etc/wireguard/wg0.conf << EOF
[Peer]
PublicKey = $CLIENT_PUBLIC_KEY
AllowedIPs = $CLIENT_IP/32
EOF

# Create client config
cat > /etc/wireguard/clients/$CLIENT_NAME.conf << EOF
[Interface]
PrivateKey = $CLIENT_PRIVATE_KEY
Address = $CLIENT_IP/32
DNS = 1.1.1.1, 1.0.0.1

[Peer]
PublicKey = <server-public-key>
Endpoint = <server-public-ip>:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25
EOF

# Reload WireGuard
sudo wg syncconf wg0 /etc/wireguard/wg0.conf
sudo systemctl restart wg-quick@wg0

echo "Client $CLIENT_NAME registered with IP $CLIENT_IP"
echo "Configuration available at /etc/wireguard/clients/$CLIENT_NAME.conf"

This script ensures that every new client gets a unique IP, updates the server, and generates a ready-to-use config for the client.

Secure and Reliable Operation

Key Rotation

Rotate the server’s private key to enhance security:

# Generate new key pair
SERVER_NEW_PRIVATE_KEY=$(wg genkey)
SERVER_NEW_PUBLIC_KEY=$(echo "$SERVER_NEW_PRIVATE_KEY" | wg pubkey)

# Update server config
sudo sed -i "s/PrivateKey = .*/PrivateKey = $SERVER_NEW_PRIVATE_KEY/g" /etc/wireguard/wg0.conf

# Reload the interface
sudo wg set wg0 private-key $SERVER_NEW_PRIVATE_KEY

# Notify peers of new public key
sudo wg set wg0 peer <client-public-key> public-key $SERVER_NEW_PUBLIC_KEY

Clients should use Update in their config to adopt the new public key. For zero-downtime key rotation, deploy a new server instance with the new key and switch traffic via DNS or load balancer.

Monitoring with `wg show` and `journalctl`

Use wg show wg0 json to get structured output for scripting:

{
  "interface": "wg0",
  "private_key": "base64-encoded-private-key",
  "public_key": "base64-encoded-public-key",
  "listen_port": 51820,
  "fwmark": 0,
  "peers": [
    {
      "public_key": "client1-pubkey",
      "preshared_key": null,
      "endpoint": "198.51.100.10:51820",
      "allowed_ips": [
        "10.0.0.2/32"
      ],
      "latest_handshake": 1674283200,
      "transfer": {
        "rx_bytes": 12582912,
        "tx_bytes": 340768
      },
      "persistent_keepalive": 25
    }
  ]
}

Parse this JSON with jq to monitor health:

journalctl -u wg-quick@wg0 -f

Watch for Handshake failed messages, Connection timed out, or Failed to set private key.

Handling NAT Traversal

WireGuard relies on UDP and is NAT-friendly. However, clients behind NATs may experience handshake delays or packet loss.

Ensure PersistentKeepalive is set on the client. The server should be behind a NAT with a static public IP. Use iptables to forward UDP port 51820:

sudo iptables -A PREROUTING -p udp --dport 51820 -j DNAT --to-destination 10.0.0.1:51820
sudo iptables -A POSTROUTING -s 10.0.0.0/24 -j SNAT --to-source <server-public-ip>

Failure Mode: Handshake Timeout

When a client fails to complete the handshake, check:

Client has correct Endpoint IP and port.
Server’s firewall allows UDP 51820.
PersistentKeepalive is set and Endpoint is reachable.
The client’s ListenPort is configured (defaults to 51820, but can be overridden).

Use tcpdump to capture the handshake:

sudo tcpdump -i any -n -s 0 -v -X udp port 51820

Look for:

SYN packets from client to server on port 51820.
ACK and INIT messages in the WireGuard handshake exchange.
Handshake failed logs in journalctl.

Config Validation

Use wg showconf wg0 to validate the configuration:

sudo wg showconf wg0

This command outputs the full configuration as a wg set script, useful for validating and debugging:

[Interface]
ListenPort = 51820
PrivateKey = <server-private-key>
Address = 10.0.0.1/24

[Peer]
PublicKey = <client-public-key>
Endpoint = 198.51.100.10:51820
AllowedIPs = 10.0.0.2/32
PersistentKeepalive = 25

Compare this output with the file to catch config drift.

High Availability and Failover

For high availability, run multiple WireGuard servers behind a load balancer. Use LoadBalancer or VRRP (e.g., keepalived) to provide a virtual IP (VIP) for the service.

Clients connect to the VIP. When one server fails, the load balancer routes traffic to the remaining server.

Failover and Stateful Routing

Each server maintains its own wg0.conf. When a client connects, the server adds it to its peer list. Use wg set to update the configuration dynamically.

In a cluster, use a centralized database (e.g., PostgreSQL) to store peer metadata:

CREATE TABLE wireguard_peers (
    public_key BYTEA PRIMARY KEY,
    endpoint TEXT,
    allowed_ips CIDR[],
    last_handshake TIMESTAMP WITH TIME ZONE,
    persistent_keepalive INTEGER
);

A periodic job syncs this table with the current state of each server via wg show wg0 json and wg set.

Advanced Configuration Patterns

Split Tunneling

For clients that only route specific traffic through the tunnel:

[Peer]
PublicKey = <server-public-key>
Endpoint = <server-public-ip>:51820
AllowedIPs = 10.0.0.0/24, 192.168.1.0/24
PersistentKeepalive = 25

This routes traffic to 10.0.0.0/24 (the WireGuard network) and 192.168.1.0/24 (internal LAN) through the tunnel, while all other traffic uses the local network.

Multipath and Load Balancing

Use multiple Peer entries with the same public key to enable multipath routing:

[Peer]
PublicKey = <server-public-key>
Endpoint = <server1-ip>:51820
AllowedIPs = 10.0.0.1/32
PersistentKeepalive = 25

[Peer]
PublicKey = <server-public-key>
Endpoint = <server2-ip>:51820
AllowedIPs = 10.0.0.1/32
PersistentKeepalive = 25

Clients can now reach the server via two paths. The kernel’s multipath routing resolves traffic across both links.

Configuration Management

Use git to version the configuration:

cd /etc/wireguard
git init
git add .
git commit -m "Initial WireGuard configuration"

Deploy changes with git push to a central repository. Use git hooks or CI/CD to validate and apply changes.

Auto-Discovery with DNS

Publish the server’s public IP in DNS:

wg.example.com.    IN A    198.51.100.10

Clients use Endpoint = wg.example.com:51820 in their config. When the server IP changes, clients automatically reconnect.

Summary

WireGuard deployment is about creating secure, performant, and resilient network tunnels using a minimal, declarative configuration. The core workflow involves creating wg0.conf files, enabling wg-quick@wg0, and monitoring with wg show. Key patterns include dynamic peer registration, persistent keepalives, split tunneling, and configuration versioning. Failure modes center on NAT, handshake timeouts, and configuration drift. The protocol’s simplicity belies its depth: understanding how wg set, wg show, and journalctl interact is essential for diagnosing issues. Deploying WireGuard is not just setting up a tunnel—it is building a self-managing network fabric.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.