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.

Note

The WireGuard package is still under active development. Follow the development progress on the developer’s YouTube channel

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. This example information was obtained from a propular WireGuard VPN Provider.

Item	Value
Tunnel Addresses	`10.68.140.33/32` and `fc00:bbbb:bbbb:bb01::5:8c20/128`
Tunnel Private Key	ADRM6pyoYpofcDd0TkX4sb7UkR+Zj4AYeZOE2WWg2tI=
Peer Public Key	EPLh6pVel06dND8cE4Prix9GP4hGLYNhQhn5mSN2yzM=
Peer Endpoint	`86.106.143.236`
Peer Port	`51820`
Peer WG Address	Same as tunnel addresses for `/32` and `/128` routes
Peer DNS Server	`193.138.218.74`
Allowed IPs	`0.0.0.0/0` and `::0/0`

Hint

Start with configuring IPv4 connectivity first. Once IPv4 connectivity is established and working, then circle back and configure IPv6 connectivity if desired.

Some or all 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 > Tunnels
Click Add Tunnel
Fill in the options using the information determined earlier:

Enabled

Checked

Description

VPN Provider

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

Enter the private key supplied by the provider ADRM6pyoYpofcDd0TkX4sb7UkR+Zj4AYeZOE2WWg2tI=.

Note

Click Generate to generate a new key pair if the provider accepts user-generated keys.
Click Save

Peer Configuration¶

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

Navigate to VPN > WireGuard > Tunnels
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:

Enable

Checked

Tunnel

The WireGuard tunnel for this VPN provider.

Description

The name of this server or VPN provider.

Dynamnic Endpoint

Unchecked

Endpoint

The server hostname or IP address, 86.106.143.236 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 EPLh6pVel06dND8cE4Prix9GP4hGLYNhQhn5mSN2yzM=.

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.

Most VPN providers are not utiizling pre-shared keys at this time.

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 and ::0/0.
Click Save Peer

Confirm Handshakes¶

At this point it is possible to confirm basic connectivity with the VPN provider.

Navigate to VPN > WireGuard > Status
Click Show Peers
Confirm peer connectivity and recent handshaking with the peer

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 (Assign a WireGuard Interface):

Navigate to Interfaces > Assignments
Select the appropriate tun_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)
Fill in the options using the information determined earlier:
IPv4 Configuration Type

Static IPV4

IPv6 Configuration Type

Static IPv6

IPv4 Address

10.68.140.33/32

IPv4 Upstream Gateway
- Click Add a new gateway
- Fill in the options:
  
  Gateway Name
  
  WG_VPN_v4
  
  Gateway IPv4
  
  10.68.140.33
- Click Add
IPv6 Address

fc00:bbbb:bbbb:bb01::5:8c20/128

IPv6 Upstream Gateway
- Click Add a new gateway
- Fill in the options:
  
  Gateway Name
  
  WG_VPN_v6
  
  Gateway IPv6
  
  fc00:bbbb:bbbb:bb01::5:8c20
- Click Add
Click Save
Click Apply Changes

Gateways and Groups¶

These gateways 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, edit the WireGuard interface gateways and fill in a different Monitor IP address which responds to ICMP echo (ping) requests over the WireGuard tunnel.

To create a new group:

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

Group Name

Prefer_WireGuard_V4

Gateway Priority

WG_VPN_v4

Tier 1

WANGW

Tier 2

Description

Prefer VPN, fail to WAN
Repeat for IPv6 if required
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
Repeat for IPv6 if required
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
Repeat for IPv6 if required
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 by adding 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, 86.106.143.236. 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_V4, 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.
Repeat for IPv6 if required
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.