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 fa-plus 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 fa-pencil at the end of the row for the tunnel

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

  • Click fa-plus 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 fa-plus 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 fa-plus 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 fa-level-up 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 fa-level-up 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 fa-plus 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.

See also

Options such as DNS over TLS are covered elsewhere, but can help as well.

First, set the VPN provider DNS server:

  • Navigate to System > General

  • Remove any DNS servers present in the list under DNS Server Settings

  • Set a DNS Server entry as follows:

    Address

    The address of the DNS server at the peer, in this example, 10.6.0.1.

    DNS Hostname

    If this server supports DNS over TLS, enter its hostname here. Otherwise, leave it blank.

    Gateway

    Select the VPN gateway, WG_VPN_WGV4.

  • Uncheck DNS Server Override to prevent this firewall from using DNS servers from dynamic WANs.

  • Set DNS Resolution Behavior based on the requirements of this environment:

    Warning

    This can help prevent DNS requests from leaking to other servers not using the VPN, but it can cause a chicken-end-egg scenario where DNS requests will fail unless the VPN is working. Ensure that DNS is not required to establish the VPN.

    Use local DNS, fall back to remote DNS Servers

    Use this option when using the DNS Resolver in forwarding mode and when the DNS server does not need DNS over TLS. This is the best fit for this example.

    Use local DNS, ignore remote DNS Servers

    Use this option when using DNS over TLS with the DNS Resolver in forwarding mode. This ensures that no DNS query will be sent without TLS.

    Use remote DNS Servers, ignore local DNS

    Use this option if the firewall itself shouldn’t use the DNS Resolver, but communicate directly with the DNS server without TLS.

Next, configure the DNS Resolver for Forwarding mode:

  • Navigate to Services > DNS Resolver

  • Uncheck Enable DNSSEC Support

  • Check Enable Forwarding Mode

  • Click Save

  • Click Apply Changes

Warning

If there are any Custom Options in the DNS Resolver, it is possible that switching to forwarding mode will change the context of the options. Add server: to the beginning of the Custom Options box content, above any existing options. If the Custom Options box is empty, it can remain empty.

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.