WireGuard Tunnelling Guide

Introduction

WireGuard is a modern, fast, and secure VPN protocol designed to be simpler and more performant than traditional VPN solutions like IPsec and OpenVPN. WeOS includes WireGuard support to provide efficient and secure VPN tunnel services.

WireGuard offers several advantages:

  • Simple configuration: Minimal settings with sensible defaults
  • High performance: Low overhead and fast connection speeds
  • Modern cryptography: Uses state-of-the-art cryptographic algorithms
  • NAT traversal: Built-in support for operating behind NAT devices

For more information about WireGuard, visit https://www.wireguard.com.

For example use-cases and example setups, refer to:

Overview

WireGuard operates using a simple peer-to-peer model. Each device (peer) has a pair of cryptographic keys (private and public), and traffic is routed based on public keys rather than IP addresses. This cryptokey routing approach provides both routing and access control.

                       .--.-.
                      ( (    )__
                     (_,  \ ) ,_)  Internet/Public Network
                       '-'--`--'
                        |    |
     .------------------'    '--------------------.
     |                                            |
     |Public IP:                                  |Public IP:
     |203.0.113.1:51820                          |198.51.100.1:51820
 .---+----.                                   .---+----.
 |        |        WireGuard Tunnel           |        |
 | Peer A |===================================| Peer B |
 |  wg1   |                                   |  wg1   |
 '---+----'                                   '---+----'
     |                                            |
     |10.0.1.0/24                                 |10.0.2.0/24
  .--.-.                                       .--.-.
 ( (    )__                                   ( (    )__
(_,  \ ) ,_)                                 (_,  \ ) ,_)
  '-'--`--'                                    '-'--`--'
Site A Network                              Site B Network

Figure 1: WireGuard tunnel connecting two site networks.

WireGuard Concepts

  • Interface: A WireGuard interface (e.g., wg1, wg2) represents a VPN tunnel endpoint. Each interface has its own private/public key pair and listen port.

  • Peers: Each WireGuard interface can have multiple peers. A peer represents a remote endpoint that can communicate through the tunnel.

  • Public Key: The primary identifier for peers. Each peer is identified by its public key, which is used for authentication and encryption.

  • Allowed IPs: A list of IP addresses and subnets that define which traffic is routed to/from a specific peer. This provides both routing and access control (cryptokey routing).

  • Endpoint: The remote IP address and port of a peer.

  • Persistent Keepalive: An optional interval for sending keepalive packets to maintain NAT traversal and connection state.

  • Preshared Key: An optional additional symmetric key for post-quantum resistance and defense-in-depth security.

WireGuard Cryptography

WireGuard uses a fixed set of modern cryptographic algorithms:

  • Curve25519 for Elliptic Curve Diffie-Hellman (ECDH) key exchange
  • ChaCha20 for symmetric encryption
  • Poly1305 for message authentication
  • BLAKE2s for cryptographic hashing
  • HKDF for key derivation

The protocol uses the Noise protocol framework for handshakes, providing forward secrecy, identity hiding, and resistance to key compromise.

Configuration

This section provides information about configuring WireGuard tunnels in WeOS.

CLI Configuration

WireGuard configuration context is entered via the tunnel configuration context:

example:/config/#> tunnel
example:/config/tunnel/#> wireguard 1
example:/config/tunnel/wireguard-1/#>

Common Interface Options

[no] enable
Activate or deactivate this WireGuard interface. If deactivated, the configuration is preserved but the tunnel is not active.
[no] description STRING
A short text description of the tunnel. The description is displayed when listing tunnels using CLI or Web. It is limited to 64 characters.
[no] private-key KEY

The private key for this interface. Keys are base64-encoded strings generated using Curve25519. A private key is generated by default. Keys can also be generated externally using the wg command-line tool and copied into WeOS.

Important: Keep private keys secure and never share them.

public-key
Display the public key corresponding to the configured private key. This read-only value should be shared with peers that need to connect to this interface.
[no] listen-port PORT
The UDP port on which this interface listens for incoming connections. Default is 51820. If running multiple WireGuard interfaces, each must use a unique port.

Peer Configuration

Each WireGuard interface can have one or more peers configured:

example:/config/tunnel/wireguard-1/#> peer 1
example:/config/tunnel/wireguard-1/peer-1/#>
[no] peer INSTANCE
Add a peer identified by its public key, or enter the configuration context of an existing peer. no peer PUBLIC-KEY removes the peer configuration.
[no] description STRING
A short text description of the peer. The description is displayed when listing peers using CLI or Web. It is limited to 64 characters.
[no] enable
Activate or deactivate this WireGuard peer. If deactivated, the configuration is preserved but the peer connection is not active.
[no] public-key KEY
The public key of the peer. This identifies and authenticates the peer.
[no] preshared-key KEY
An optional symmetric key shared with this peer for additional security and post-quantum resistance. Same key must be used on both sides.
[no] endpoint IP
The remote endpoint IP address, hostname or FQDN for this peer.
[no] listen-port PORT
The UDP port on which the peer listens for incoming connections.
[no] persistent-keepalive SECONDS
Send keepalive packets every N seconds to maintain NAT traversal. Typical values are 25 seconds. Set to 0 to disable (default). This is useful for peers behind NAT or with stateful firewalls.
[no] allowed-ip IP/MASK

Add an IP address or subnet that is allowed to communicate with this peer. This command can be used multiple times to add multiple allowed IP ranges.

Allowed IPs serve two purposes: - Outbound: Traffic destined to these IPs is routed to this peer - Inbound: Only packets with source IPs in this list are accepted from this peer

Key Management

WireGuard in WeOS uses autogenerated Curve25519 key pairs. Keys can also be generated externally using the wg command-line tool and imported into WeOS.

Generate private/public key pair

$> wg genkey | tee privatekey | wg pubkey > publickey

Generate preshared key

$> wg genpsk > presharedkey

Important: Keep private keys secure and never share them.

Monitoring and Statistics

CLI Show Commands

View WireGuard tunnel status and statistics:

show tunnel wireguard
Display summary information for all configured WireGuard interfaces, including interface name, public key, and listen port. Also shows peer information including endpoints, transfer statistics, and handshake status.
show tunnel wireguard IFACE
Display detailed information for a specific WireGuard interface, including: - Interface configuration - Public key - Listen port - Peer details (public key, endpoint, allowed IPs) - Latest handshake time - Data transfer (bytes sent/received) - Persistent keepalive setting

Security Considerations

Key Management

  • Protect private keys: Private keys should never be shared or transmitted insecurely
  • Regular key rotation: Consider rotating keys periodically for enhanced security
  • Preshared keys: Use preshared keys for additional post-quantum resistance

Network Security

  • Firewall rules: Configure firewall rules to restrict access to WireGuard ports
  • Allowed IPs: Use restrictive allowed-ip configurations to limit peer access
  • Network segmentation: Consider using separate WireGuard interfaces for different security zones
  • Monitoring: Regularly review tunnel statistics and handshake times

Best Practices

  • Use strong, randomly generated keys
  • Limit allowed-ip ranges to only necessary networks
  • Enable persistent keepalive only when needed (NAT traversal)
  • Regularly review and audit peer configurations
  • Use descriptive names for tunnels and peers for easier management

Troubleshooting

Common Issues

No handshake occurring: - Verify that the public keys are correctly configured on both peers - Check that the endpoint address and port are correct and reachable - Ensure UDP port (default 51820) is not blocked by firewalls - Verify that private keys are correctly configured

Handshake succeeds but no traffic flows: - Check the allowed-ip configuration on both peers - Verify that routing is correctly configured for the tunnel network - Ensure that IP forwarding is enabled if routing between networks - Check firewall rules on both peers

Connection drops frequently: - Enable persistent-keepalive (typically 25 seconds) to maintain NAT mappings - Check for network stability issues - Verify that no aggressive firewall timeout settings are interfering

Cannot reach specific IPs through tunnel: - Verify that the destination IPs are in the peer’s allowed-ip list - Check routing tables to ensure traffic is routed to the WireGuard interface - Confirm that the remote peer has appropriate routing configured

Debug Commands

show tunnel wireguard [INTERFACE]
Display current tunnel status, peer information, and statistics
show log
Check system logs for WireGuard-related errors or warnings
show interface [INTERFACE]
Verify that the WireGuard interface is up and has the correct IP configuration
ping iface [INTERFACE] [DESTINATION]
Test connectivity through a specific WireGuard interface

References