Setup Docs Incomplete for Wireguard - Confused about terms? Having a challenging time setting up Wireguard? Read Here!

[micah]

I just spent a couple of hours trying to set up Wireguard and not understanding how it wasn't working. I followed the guide precisely several times.

https://docs.netgate.com/pfsense/en/latest/recipes/wireguard-ra.html

Here are the key items I needed to add to complete the task and some clarifications I learned.

0. Wireguard is a UDP protocol. This means it is a blind connection and, thus, does not have the same sort of logging as a TCP connection. It behaves more like a switch, where misconfiguration causes traffic to be misrouted (or blackholed), and it can be very difficult to diagnose issues. You must pay close attention to your initial configuration - and terms are reused to mean vastly different things depending on which device they are used on. So, read this guide carefully because a misconfiguration will not necessarily be diagnosable from logs or errors.

(This is not exactly techically correct. So read my postscript at the bottom for a more technically accurate explanation, if you like networking.)

1a. In Wireguard, a Tunnel is the same as a "Server" in OpenVPN - except all devices need one, so it can also mean a networking server running on localhost.
1b. In Wireguard, a Peer is the same as a "Client" in OpenVPN.
1c. In Wireguard, every device runs a Tunnel. Peer devices run tunnels on 127.0.0.1 and your endpoint (say a server) runs a tunnel that is accessible over the WAN.
1d. In Wireguard, routing is bidirectional, so it's important that you set your Allowed IPs and Interface Address on both ends correctly to prevent unwanted traffic routing.
1e. In Wireguard on pfSense, you control the range of IPs that a Peer is allowed to reach on your network with Firewall Rules (not with Allowed IPs).

2a. You need to associate the tun_wg0 interface with a system interface using Interfaces > Assignments > (select tun_wg0) Add. (It will come out as OPT_n, where n is an unused number)
2b. In your OPT_n Interface settings, set your Interface Configuration Type to "Static IPv4".
2c. In your OPT_n Interface settings, to the network you want to use for your Wireguard Tunnel. (In just a moment, I'm going to use the example of 192.168.10.1/24)
2d. In Firewall Rules, duplicate the same "Pass VPN traffic from WireGuard peers" for the new OPT_n assignment.

2. In your Peer Configuration for your device, the Allowed Network area should usually be scoped as narrowly as possible for assignment. This prevents collisions since WG clients do not negotiate for IPs. They try to claim blindly. It can be challenging to scale this setup using broad scopes since client devices often try to claim occupied IPs. Fix this with narrow scopes.

A configuration example to clarify some confusing terms - Allowed IPs and Interface Addresses:

• Suppose your pfSense tunnel interface network is 192.168.10.1/24. You're going to reserve that space to assign to the Peer devices connecting to your pfSense device.

• Suppose you want to assign the IP address 192.168.10.5 to a Peer (say, Alice's Mobile Phone).

• On your pfSense, Alice's Mobile Phone Peer settings should set the Allowed IPs to 192.168.10.5/32.

• This means that your pfSense will only accept traffic from the single IP of 192.168.10.5 for Alice's Mobile Phone. (Anything else will be rejected)
• If you don't do this, then clients can self-assign themselves with IPs that collide with other IPs.

• On Alice's Mobile Phone, the Interface Address is 192.168.10.5/24 (matching the pfSense tunnel network mask is the easiest method, but I'll clarify what is actually happening below).

• The subnet mask of the Interface Address is the range of IPs from which Alice's Mobile Phone will accept responses.
• If the pfSense Wireguard Tunnel interface has the IP 192.168.10.1, Alice's Mobile Phone Interface Address can be set to 192.168.10.5/29, or 192.168.10.5/28, ... up to 192.168.10.5/24 - and it will properly acknowledge requests from your pfSense Wireguard Tunnel.
• In the above case, if Alice's Mobile Phone Interface Address is set to 192.168.10.5/30, range goes from 192.168.10.4 - 192.168.10.7, the her phone will not accept responses from the pfSense Wireguard Tunnel device at 192.168.10.1

• Critically, the Wireguard peers do not negotiate IP addresses. They try to handshake and fail.

• So, if Alice's Mobile Phone and Bob's Mobile Phone are set to 192.168.10.5/24 in their Allowed IPs in the Peer settings, they can simultaneously claim 192.168.10.5. This causes handshake delays.
• In this case, one Peer's handshake will not complete. They will fail and need to retry - which can take a few seconds or more.
• This can lead to conditions where Peer connections are very unstable as they attempt to handshake with occupied IPs in that range and fail.
• In high-traffic networks, this can result in Peers intermittently disconnecting and spending significant time in the handshake attempt phase.

• On Alice's Mobile Phone, the Allowed IPs setting is the range of IPs that will be routed over the pfSense connection.

• 0.0.0.0/0 for a full tunnel, or say, 192.168.1.0/24 (to route only requests to that network to your pfSense Wireguard tunnel).

There is a namespace collision in the term "Allowed IPs". It was a poor decision in the spec of the Wireguard protocol itself.

• For Alice's Mobile Phone, Allowed IPs means the "range of IP addresses to be routed to the pfSense Wireguard Tunnel."
• For the pfSense Peer settings area, Allowed IPs means "the range of accepted peer interface IP addresses for this particular peer."
• Most notably, in the pfSense Peer settings, this setting has NOTHING TO DO WITH THE RANGE OF IPS THAT THE PFSENSE TUNNEL WILL RESOLVE.
• Every client can reach every point on your network when using the default guide, as long as it sends traffic via an IP address in the Allowed IPs range. You will need to limit that reach in your Firewall Rules.

There is a lot of confusing terminologies, and I didn't see much clarifying documentation anywhere. I hope this helps future users avoid the confusion of setting up this marvelous tech.

P.S. I simplified my explanation above, which is not technically correct - just as correct as it needs to be for most users. Wireguard is designed around a bidirectional network topology and is designed to be bidirectional for all Tunnels and Peers. In a bidirectional network, the terms Allowed IPs and Interface Address mean the same thing, but the most common use cases are the sort of server-client setup analogous to OpenVPN. In this case, implementing these terms means very different things. We generally want our clients to route traffic through our servers, BUT we do not want our servers to be routing traffic through our clients. So, the confusion in terms comes from the fact that we are turning a bidirectional networking technology into a unidirectional routing topology.

[micah]

I wrote this out of frustration at 2:00a. Now, I can’t edit.

So, 2c is about setting the Interface Network. And, there is no need to include a Default Gateway. It will use the system default in its absence.

The second point 2 should actually be a 3.

I didn’t realize that some points would be indented while others weren’t. Apologies on the readability. Maybe I can make a new post with these issues fixed and properly tagged.

[Traveler]

@micah This is very helpful, thank you! It would be very helpful if the https://docs.netgate.com/pfsense/en/latest/recipes/wireguard-ra.html page was standalone or at least referenced the other pages for assigning the interface.

And the observation that firewall rules govern access is very helpful.

Every client can reach every point on your network when using the default guide, as long as it sends traffic via an IP address in the Allowed IPs range. You will need to limit that reach in your Firewall Rules.

For completeness, it would be great to sketch the common case of rules that allow access to one or two specific resources.

[SteveITS]

Lurking past, there’s a Feedback link on doc pages to submit changes. :)

[Traveler]

@SteveITS I made an attempt when I first read the page, but your nudge got me to spend the 30 minutes to setup an account (again) and report the issue, thanks. And this discussion gives much more clarity.

[Traveler]

For future travelers, this Youtube video is helpful: https://www.youtube.com/watch?v=ralWaBL98pU