Tip

This is the documentation for the 23.06 version. Looking for the documentation of the latest version? Have a look here.

Required Information¶

Before attempting to configure a WireGuard instance, several pieces of information are required in order for both sides to build a tunnel.

At a minimum, these pieces of information should be known before attempting to configure a WireGuard.

Public keys for each peer
Endpoint IP addresses and ports for each peer (if static)
A subnet to use for communication between peers
Lists of remote networks on each peer

WireGuard Keys¶

Every WireGuard peer, including this router, needs a private and public key pair.

Each peer should generate its own keys and the private key should not leave that peer if possible.

Warning

While keeping a backup of the keys is a good idea, do not copy the private key contents unnecessarily. Other peers do not need to know the private key, they only need the public key.

To generate a key pair, use the wg command from any system which has the WireGuard tools installed.

$ wg genkey | tee tnsr1.prv.key | wg pubkey > tnsr1.pub.key
$ cat tnsr1.prv.key
6CdptoVJkKPG3Bc5gKLIps3LC0D+2ga8Nfxh31Bhp0o=
$ cat tnsr1.pub.key
gJHc9lDjcM3KfOO4BdRP3tZWttZld23nvZoDy8FYQlE=

Note

These tools are installed by default on TNSR. They can be installed on other systems using the OS package manager (e.g. sudo apt install wireguard-tools.)

Most graphical WireGuard clients (e.g. Windows, Android, iOS) also include their own mechanism to generate keys.

Distribute the public keys to the other peers as needed via some means (e.g. e-mail). Since the public keys are not secret knowledge, they can be delivered by unprotected communication methods.

Endpoint IP Addresses¶

At least one peer must have a static endpoint address, as outlined in Design Style.

WireGuard Interface Subnet¶

Choose a subnet for the WireGuard interface itself. WireGuard will use this to communicate between peers. For tunnels with one peer on each end, this can be a /30 prefix for IPv4. For a setup with many peers, use a large enough subnet to contain all peers.

Within this subnet, decide which addresses will be used by each peer.

Note

Addresses must be allocated to peers manually in the configuration, WireGuard does not have a mechanism to dynamically assign addresses to client.

WireGuard Next Hops¶

The dataplane requires an additional per-peer next hop configuration for WireGuard tunnels to locate a peer adjacency. This is due to the fact that WireGuard interfaces are non-broadcast interfaces and get handled differently internally by the dataplane.

There are currently two ways to implement this configuration, each with different advantages.

Peer Route Table Entries – Easiest to setup, less likely to have problems with routing changes related to endpoints. Handles dynamic peers well, such as for Remote Access VPNs.
Tunnel Endpoint Next Hop Entries – Can improve behavior with static peers which require dynamic routing protocols.

Peer Route Table Entries¶

The best method to inform the Dataplane about peer locations is with a special route table entry for every peer interface address.

This method is more robust in the majority of cases, where it allows the dataplane to accommodate changes to endpoint routing with less potential for problems. This is especially important for dynamic remote peers where their endpoint address is unknown.

tnsr(config)# route table ipv4-VRF:0
tnsr(config-route-table)# route 10.31.111.2/32
tnsr(config-rttbl4-next-hop)# next-hop 0 via 0.0.0.0 wg1
tnsr(config-rttbl4-next-hop)# exit
tnsr(config-route-table)# exit

This type of route entry allows the dataplane to locate the neighbor adjacency using the WireGuard interface without the need for hardcoding a peer address. Peers with dynamic endpoint addresses can roam to new addresses and WireGuard can maintain communication.

Using Dynamic Routing Protocols with Peer Route Table Entries¶

This method is not ideally suited for use with dynamic routing protocols in most cases. It can be made to work with BGP, but it is not compatible with OSPF at all.

While the peers can communicate with the peer route table entries in place, the route method makes dynamic routing protocols see the peer as non-adjacent. As a result, OSPF will refuse to form neighbor relationships. BGP can work this way, but it must be configured to allow peers to be multiple hops away.

tnsr(config)# route dynamic bgp
tnsr(config-frr-bgp)# server vrf default
tnsr(config-bgp)# neighbor 10.2.222.2
tnsr(config-bgp-neighbor)# ebgp-multihop hop-maximum 2

Alternately, disable-connected-check can be used instead:

tnsr(config)# route dynamic bgp
tnsr(config-frr-bgp)# server vrf default
tnsr(config-bgp)# neighbor 10.2.222.2
tnsr(config-bgp-neighbor)# disable-connected-check

Tunnel Endpoint Next Hop Entries¶

An alternate method to inform the dataplane about peer locations is with tunnel endpoint next hop entries which define a relationship between a peer interface address inside the tunnel with the external endpoint address.

This method works with dynamic routing protocols such OSPF, and improves compatibility with BGP, but it requires the initial peer endpoint address to be known before the tunnel is established. This means that it does not work well with dynamic peers with unknown endpoint addresses.

Note

Peers can roam to a new external endpoint address after the tunnel is established, but the initial address must be known.

Remote Networks¶

TNSR must know which networks exist at each peer. For site-to-site style VPNs, this would include all of the local network(s) behind each peer as well as the WireGuard interface addresses of the peer. For remote access style VPNs, the server primarily needs to know the network used for the peer addresses while the client(s) need to either have a list of all networks reachable through the server, or be configured to route all traffic through the server.

WireGuard requires the peer networks for two reasons:

WireGuard must have the peer network(s), including their designated interface address, defined as allowed prefixes. This configures an association between keys and addresses for cryptokey routing internal to WireGuard.
TNSR must have routes in the route table for the networks so it knows to send traffic to these networks across a specific WireGuard interface.

This can be simplified in cases where there is only one peer per instance, as all networks can be allowed from a single peer and the routes can then be managed dynamically by a routing protocol.