Warning

WireGuard has been removed from the base system in releases after pfSense Plus 21.02-p1 and pfSense CE 2.5.0, when it was removed from FreeBSD.

If upgrading from a version that has WireGuard active, the upgrade will abort until all WireGuard tunnels are removed. For more details, see the Release Notes

WireGuard is available as an experimental add-on package on pfSense Plus 21.05, pfSense CE 2.5.2, and later versions. The settings for the WireGuard add-on package are not compatible with the older base system configuration.

WireGuard VPN Client Configuration Example¶

This recipe explains how to setup WireGuard as a “client” to a remote VPN service through which Internet traffic will be routed.

Note

Though WireGuard does not have a concept of “Client” and “Server” per se, in this style of deployment the firewall initiates connections to a remote peer but the peer never initiates back to the firewall. In this way, the firewall behaves like a “Client” and may be referred to as such in this document. The remote peer may also be referred to as “server”.

Required Information¶

The following basic information must be determined before starting the VPN configuration.

Item	Value
Tunnel Address	`10.6.210.2/24`
Interface Keys	Generate locally or from provider
Peer Public Key	Obtain from provider
Peer Endpoint	`198.51.100.6`
Peer Port	`51820`
Peer WG Address	`10.6.210.1`
Peer DNS Server	`10.6.0.1` (No TLS)
Allowed IPs	`0.0.0.0/0` (All traffic)

Some of these values must be obtained from the VPN provider or server administrator. Methods vary, but some may have a web-based portal which shows settings or generates a configuration file. Others may opt to send settings in a more secure manner.

Keys¶

In this role, the source of the keys can vary. Ideally, a private and public key set for this firewall should be generated by this firewall and the private key should never leave. The public key should be copied and submitted to the administrator of the server side so it can be used for this client.

Some providers insist on generating the keys themselves so they can preallocate addresses and other settings based on keys they already know. This also allows them to easily generate configurations for clients. It’s less secure this way, but more convenient.

Tunnel Configuration¶

First create the WireGuard tunnel.

Navigate to VPN > WireGuard
Click Add Tunnel
Fill in the options using the information determined earlier:

Enabled

Checked

Description

VPN Provider

Address

10.6.210.2/24

Listen Port

This does not likely matter unless the server requires a specific source port. In most cases it can be left blank or at the default 51820.

Interface Keys

Click Generate to create a new set of keys, or enter the private key supplied by the provider.
Click Save, or continue on to add the peer

Peer Configuration¶

The peer entry for the server can be added when editing the tunnel. To edit the tunnel:

Navigate to VPN > WireGuard
Locate the WireGuard tunnel for this VPN provider
Click at the end of the row for the tunnel

From the tunnel editing page, add a peer as follows:

Click Add Peer
Fill in the options using the information determined earlier:

Description

The name of this server or VPN provider

Endpoint

The server hostname or IP address, 198.51.100.6 in this example.

Endpoint Port

The server WireGuard port, 51820 in this example.

Public Key

The public key for the VPN provider endpoint, given by the VPN provider.

Allowed IPs

List of networks to route to the remote side. Since this example will be sending all traffic through the VPN provider, enter 0.0.0.0/0.

Peer WireGuard Address

If known, the IP address of the server in the tunnel subnet (e.g. 10.6.210.1).

Pre-Shared Key

Not used in this example, but for additional security this pre-shared key can be generated and copied to the peer. Must match on the client and server.
Click Update
Click Save

Assign Interface¶

First, fix the default gateway so WireGuard isn’t automatically selected before it’s ready:

Navigate to System > Routing
Set Default Gateway IPv4 to a specific gateway (e.g. WANGW) or group
Set Default Gateway IPv6 in a similar manner if this VPN will also carry IPv6 traffic
Click Save
Click Apply Changes

Next, assign the interface so the automatic gateway can be used for policy routing (Assign a WireGuard Interface).

Navigate to Interfaces > Assignments
Select the appropriate wg<number> interface in the Available network ports list
Click Add to assign the interface as a new OPT interface (e.g. OPT1)
Navigate to the Interface configuration page, Interfaces > OPTx
Check Enable
Enter an appropriate Description which will become the interface name (e.g. WG_VPN)
Click Save
Click Apply Changes

Gateways and Groups¶

Assigning the interface creates an automatic gateway named after the interface itself. In this example, since the interface was named WG_VPN, the automatic gateway is WG_VPN_WGV4.

This gateway can be added to a gateway group for failover or load balancing of outbound traffic. This example assumes there are no existing groups. If there are groups already, the new gateway can be added to them like any other.

This example sets up a Gateway Group which prefers WireGuard and fails over to WAN. Traffic directed to this group will use WireGuard when it is up, and WAN when it is down. In practice this specific behavior may or may not be desirable, but can be used as a template for other scenarios.

Note

This will only function properly if gateway monitoring is possible. For that to work, one of two things must be done:

The WireGuard Peer WireGuard Address must be filled in with the remote end of the VPN and that address must respond to ICMP echo (ping) requests over WireGuard.
Alternately, edit the automatic WireGuard interface gateway and fill in a different Monitor IP address which respond to ICMP echo (ping) requests over WireGuard.

To create a new group:

Navigate to System > Routing, Gateway Groups tab
Click Add
Configure the group as follows:

Group Name

Prefer_WireGuard

Gateway Priority

WG_VPN_WGV4

Tier 1

WANGW

Tier 2

Description

Prefer VPN, fail to WAN
Click Save
Click Apply Changes

Outbound NAT¶

By default the VPN will not have outbound NAT applied to its traffic. Most VPN providers will require this, so that all traffic appears to originate from the address of the VPN interface, and not LAN.

To setup outbound NAT for the VPN:

Navigate to Firewall > NAT, Outbound tab
Set Mode to Hybrid Outbound NAT

This example assumes the firewall starts out on Automatic Outbound NAT. If the firewall is using Manual Outbound NAT, there is no need to change the mode.
Click Save
Click Add to create a new outbound NAT rule at the top of the list
Configure the NAT rule as follows:

Interface

The assigned WireGuard interface (e.g. WG_VPN)

Source

The LAN subnet of this firewall (e.g. 192.168.1.0/24)

Description

A description of the rule, if desired: Outbound NAT for LAN to WireGuard VPN Provider

Leave all remaining options at their default values
Click Save
Click Apply Changes

Firewall Rules¶

This scenario should not require any firewall rules on the WAN or VPN interface. No connections will be made inbound on the WAN, only outbound. Traffic from the Internet will not be allowed back into the VPN interface.

Routing Traffic¶

Policy Routing¶

Rules can be added to local interfaces, such as LAN, for policy routing which utilize the gateway for the WireGuard interface.

For example, to policy route all traffic from a host on the LAN out through WireGuard:

Navigate to Firewall > Rules, LAN tab
Click Add to create a new firewall rule at the top of the list so that it matches before other rules
Configure the firewall rule as follows:

Action

Pass

Interface

LAN

Protocol

Any

Source

Set this to match the client whose outbound traffic will be routed across the VPN. For example:

Single host or alias, 192.168.1.23

Destination

Any

Gateway

WG_VPN_WGV4

Note

Click Display Advanced to show this option.

Leave all remaining options at their default values
Click Save
Click Apply Changes

This concept can be adapted for a number of different scenarios. For example, match all LAN traffic and send it across the VPN, or match traffic and use a gateway group to prefer the VPN, etc.

Static Routing¶

Specific networks can be routed across the VPN statically in a couple different ways:

Add the network(s) to the Allowed IPs list for the remote peer on this tunnel. This automatically adds a route to the operating system routing table.
Add a static route for the network(s) under System > Routing on the Static Routes tab.

Default Gateway¶

This is an optional step that some users may want to perform if they want all traffic from the firewall to cross the VPN, not only LAN client traffic.

Policy routing is the most flexible way to direct traffic over this type of connection, but it does not influence traffic from the firewall itself. To send traffic from the firewall across the VPN to Internet destinations, the VPN must be set as the default gateway.

To avoid a chicken-and-egg problem, a manual static route is required for the VPN provider peer endpoint address:

Navigate to System > Routing, Static Routes tab
Click Add
Configure the routes as follows:

Destination network

The VPN provider peer endpoint IP address. For this example, 198.51.100.6. Use a CIDR mask of 32 (or 128 if the peer endpoint is an IPv6 address.)

Gateway

WANGW so that traffic for this endpoint is routed over WAN

Description

Route to VPN provider endpoint
Click Save

With the peer route in place, now set the default gateway:

Navigate to System > Routing, Gateways tab
Set Default Gateway IPv4 to WG_VPN_WGV4, or a gateway group which includes that gateway, such as the previously created Prefer_WireGuard.
Set Default Gateway IPv6 in a similar manner if the VPN also carries IPv6 traffic.
Click Save
Click Apply Changes

At this point, all traffic that doesn’t match entries in the routing table will be sent across the VPN.

DNS Configuration¶

DNS privacy is also important, and there are a few factors to consider. For this example, DNS requests will be sent to a DNS server at the VPN peer, but without TLS.

Finish Up¶

The configuration is now complete! Depending on which sections were followed, the firewall should be able to at least communicate with the remote peer, networks, and clients should be able to pass traffic through the VPN provider out to the Internet.

Make any final adjustments or additional configurations as needed.