WireGuard is an extremely fast, modern, and cryptographically secure virtual private network protocol integrated directly into the upstream Linux kernel. While high-level helper scripts such as wg-quick provide convenient wrappers for quick single-peer setups, relying on them abstracts away the underlying Linux network stack. For system administrators, network engineers, and DevOps professionals managing automated infrastructure, container environments, and advanced routing engines, configuring WireGuard via the native iproute2 suite (ip link, ip address, ip route) and the low-level wg command is the industry standard approach.
Operating WireGuard directly at the kernel link layer eliminates unnecessary dependencies, allows dynamic reconfiguration without tearing down network interfaces, and integrates cleanly with complex routing topologies. This comprehensive guide walks you through creating, configuring, securing, and routing traffic over native WireGuard interfaces in Linux using ip link and wg.
Prerequisites and Kernel Module Verification
Because WireGuard operates directly within the Linux kernel (since version 5.6), you must ensure that the kernel module is active and that the low-level user-space utility is installed:
- Open a root or elevated terminal shell.
- Ensure the
wireguard-toolspackage is installed:# On Debian/Ubuntu: sudo apt update && sudo apt install wireguard-tools -y # On RHEL/Fedora/Rocky Linux: sudo dnf install wireguard-tools -y - Confirm that the kernel module loads automatically:
sudo modprobe wireguard && lsmod | grep wireguard
If your system utilizes advanced hardware offloading or custom link types, you can verify your physical adapters beforehand by consulting our tutorial on how to inspect and configure network hardware in Linux using devlink.
Step 1: Generating WireGuard Cryptographic Keypairs
WireGuard authenticates peers using Noise protocol curve25519 public-key cryptography. Before instantiating interfaces, generate private and public keys for your local host:
- Create a dedicated, restricted directory to store cryptographic materials:
sudo mkdir -p /etc/wireguard sudo chmod 700 /etc/wireguard cd /etc/wireguard - Generate the private key with strict
umaskpermissions, and derive its corresponding public key:umask 077 wg genkey | tee privatekey | wg pubkey > publickey - Inspect the generated public key, which you will share with remote peers:
cat publickey
Step 2: Creating the WireGuard Kernel Interface Using ip link
Unlike legacy VPN technologies that rely on user-space TUN/TAP daemons, WireGuard creates native network interfaces recognized directly by the kernel’s routing subsystem:
- Add a new network interface of type
wireguard:sudo ip link add dev wg0 type wireguard - Assign a static internal IP address and subnet mask to the interface:
sudo ip address add 10.100.0.1/24 dev wg0 - Verify that the unconfigured interface exists in the link state:
The link will report stateip link show wg0DOWN, ready to receive its cryptographic and endpoint parameters.
This streamlined link creation mirrors modern tunneling architectures. If you work with hardware-accelerated IPSec tunnels, compare this methodology against our guide on how to create and configure IPsec XFRM interfaces in Linux using ip link.
Step 3: Configuring the Interface with the wg Tool
With the physical device created, bind the host’s private key and assign a dedicated UDP listening port using the low-level wg command:
- Set the private key and listening port (typically
51820):sudo wg set wg0 listen-port 51820 private-key /etc/wireguard/privatekey - Bring the interface up using
ip link:sudo ip link set up dev wg0 - Audit the active interface status:
The terminal output will display your public key, listening port, and zero active peers.sudo wg show wg0
Step 4: Registering and Authorising Remote Peers
In WireGuard, connections are strictly peer-to-peer without server/client dichotomy. To establish connectivity with a remote endpoint, bind the remote peer’s public key, allowed IP range, and physical network endpoint:
- Execute
wg setspecifying the peer parameters:sudo wg set wg0 peer <REMOTE_PEER_PUBLIC_KEY> \ allowed-ips 10.100.0.2/32 \ endpoint 203.0.113.50:51820 \ persistent-keepalive 25 - Examine the breakdown of parameters:
- peer: The base64 public key of the remote node.
- allowed-ips: The internal tunnel IP addresses that this peer is authorised to send from and receive. WireGuard uses Cryptokey Routing; packets addressed to this IP will be encrypted and routed exclusively to this peer.
- endpoint: The public IPv4/IPv6 address and UDP port of the remote host.
- persistent-keepalive: Sends an authenticated heartbeat packet every 25 seconds, maintaining state across stateful NAT firewalls and routers.
- Confirm that the peer is registered:
sudo wg show wg0
Step 5: Routing Traffic Across the WireGuard Tunnel
While WireGuard’s Cryptokey Routing handles packet encapsulation based on allowed-ips, the Linux kernel must also know to dispatch outbound packets towards wg0:
- For communication between internal tunnel addresses (e.g.
10.100.0.2), the kernel automatically routes via the interface subnet created in Step 2. Test ping connectivity:ping -c 4 10.100.0.2 - To route a remote subnet (e.g.,
192.168.50.0/24) located behind the peer through the tunnel:# Update peer allowed-ips first sudo wg set wg0 peer <REMOTE_PEER_PUBLIC_KEY> allowed-ips 10.100.0.2/32,192.168.50.0/24 # Add the kernel routing entry sudo ip route add 192.168.50.0/24 dev wg0
For large enterprise clusters with redundant gateways, you can link WireGuard routes to next-hop tables by following our tutorial on how to manage multipath routing objects in Linux using ip nexthop.
Step 6: Real-Time Monitoring and Interface Teardown
Real-Time Interface Telemetry
To inspect active cryptographic handshakes, transmitted bytes, and endpoint connectivity in real time, run:
sudo wg show wg0
# Or monitor live transfer rates continuously:
watch -n 1 sudo wg show wg0
A healthy link will display latest handshake: X seconds ago along with incrementing transfer counters.
Dynamically Removing a Peer
To revoke access for a peer without restarting the interface or interrupting other connections:
sudo wg set wg0 peer <REMOTE_PEER_PUBLIC_KEY> remove
Destroying the Interface
When decommissioning a tunnel, tearing down the interface cleanly removes all kernel routes and frees associated network resources:
sudo ip link delete dev wg0
Troubleshooting Common WireGuard Handshake Failures
1. “No Handshake Completed” After Bringing Link Up
WireGuard is silent by design; it produces no responses to unauthenticated packets and will not throw connection timeout errors. If wg show shows no handshake:
- Verify that upstream firewalls (
ufw,nftables, or cloud security groups) permit UDP traffic on the specified listen port (e.g.,51820/udp). - Confirm that the remote host has your correct public key configured under its peer table.
- Ensure that
persistent-keepalive 25is enabled if either node is behind Network Address Translation.
2. Packets Drop When Sending to Valid Remote Subnets
If you can ping the tunnel IP but cannot reach nodes behind the peer, verify that IP forwarding is enabled on the remote router node:
sudo sysctl -w net.ipv4.ip_forward=1
Furthermore, confirm that the target subnet is explicitly listed under the peer’s allowed-ips list on your local host.