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 Remote Access VPN Configuration Example

This recipe covers configuring a basic WireGuard remote access style VPN tunnel.

Note

Though WireGuard does not have a concept of “Client” and “Server” per se, in this style of deployment the firewall cannot initiate connections to remote peers. In this way the firewall acts like a “Server” and may be referred to as such in this documentation. Remote peers may also be referred to as “clients”.

Required Information

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

Item

Value

Design

Remote access, one tunnel+many peers

Firewall WAN

198.51.100.6

Listen Port

51820

Tunnel Subnet

10.6.210.0/24

Tunnel Address

10.6.210.1/24

Peer Addresses

10.6.210.2 - 10.6.210.254

Peer Endpoints

Dynamic

Generating Keys

WireGuard requires public/private key pairs for each peer, including this firewall.

Warning

Keys cannot be reused between clients, as WireGuard requires unique keys to identify clients and where to send their traffic.

Tunnel Keys

To generate keys for the firewall itself, click the Generate button when configuring a tunnel. The GUI will populate the private and public key fields automatically.

The peers will need the public key for their configuration.

Peer Keys

Each peer will need its own public/private key pair. The private key will be needed on the peer client software while the public key will be needed on the firewall itself for the peer definition.

These keys can be generated by the clients themselves, or via command line on a system which has the WireGuard utilities installed. This includes the firewall itself; these commands may be run from a console or SSH shell or from Diagnostics > Command Prompt.

From a command line, execute the following:

$ wg genkey | tee privatekey | wg pubkey > publickey

This command outputs files named privatekey and publickey which respectively contain a private key and its associated public key. This key pair can be used for a WireGuard peer.

To view the keys, inspect the contents of the files:

$ cat privatekey
WGpL3/ejM5L9ngLoAtXkSP1QTNp4eSD34Zh6/Jfni1Q=
$ cat publickey
b9FjbupGC7fomO5U4jL5Irt1ZV5rq4c+utGKj53HXgU=

Repeat the commands as needed as many times as is necessary for the number of peers required by this tunnel. Note the keys in a secure place.

Tip

Change the commands to output files named for their associated peer, then store the resulting files in a secure location.

Alternately, the keys can be output in one command without storing them persistently. This behavior is not be supported on all platforms, but is supported on the firewall itself.

$ wg genkey | tee /dev/stderr | wg pubkey
4BSH81zC3/OWl25XrzqWy7WnAiARXySHd+K+KFxNrWU=
rzWOC0zH9v2zF6r92uCbjs7JOmhqy8N+cUdA+GCynSM=

Tunnel Configuration

Now it’s time to create the WireGuard tunnel.

  • Navigate to VPN > WireGuard > Tunnels

  • Click fa-plus Add Tunnel

  • Fill in the options using the information determined earlier:

    Enable

    Checked

    Description

    Remote Access

    Listen Port

    51820

    Interface Keys

    Click Generate to create a new set of keys.

    Interface Addresses

    10.6.210.1/24

  • Click Save

Peer Configuration

Peers can be added when editing a tunnel. To edit a tunnel:

  • Navigate to VPN > WireGuard > Peers

  • Click fa-plus Add Peer

  • Fill in the options using the information determined earlier:

    Enable

    Checked

    Tunnel

    tun_wg<num> (Remote Access)

    Description

    The name of this client (e.g. The name of a person, device, username, or other uniquely identifying information.)

    Dynamic Endpoint

    Checked

    Keep Alive

    Typically left blank, but may be filled in if clients have problems traversing certain firewalls.

    Public Key

    The public key for this peer. Obtained from the key generation process earlier, or from the peer itself if it was generated by client software directly.

    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.

    Allowed IPs

    The tunnel IP address for this peer, from the list determined above, with a /32 CIDR mask. For example, the first peer will be 10.6.210.2/32, the second will be 10.6.210.3/32, and so on.

  • Click Save Peer

  • Repeat the steps to add additional peers as needed.

Firewall Rules

First add a rule to pass external WireGuard traffic on the WAN:

  • Navigate to Firewall > Rules, WAN tab

  • Click fa-level-up Add to add a new rule to the top of the list

  • Use the following settings:

    Action

    Pass

    Interface

    WAN

    Protocol

    UDP

    Source

    any

    Destination

    WAN Address

    Destination Port Range

    (other), 51820

    Description

    Pass traffic to WireGuard

  • Click Save

  • Click Apply Changes

Next, add a rule to pass traffic inside the WireGuard tunnel:

  • Navigate to Firewall > Rules, WireGuard tab

  • Click fa-level-up Add to add a new rule to the top of the list

  • Use the following settings:

    Action

    Pass

    Interface

    WireGuard

    Protocol

    Any

    Source

    any

    Destination

    any

    Description

    Pass VPN traffic from WireGuard peers

  • Click Save

  • Click Apply Changes

Client Configuration

Client configuration varies by platform, see WireGuard documentation for details. This section covers a basic configuration.

This is an example configuration from a WireGuard client for a split-tunnel configuration:

[Interface]
PrivateKey = WGpL3/ejM5L9ngLoAtXkSP1QTNp4eSD34Zh6/Jfni1Q=
ListenPort = 51820
Address = 10.6.210.2/24

[Peer]
PublicKey = PUVBJ+zuz/0mRPEB4tIaVbet5NzVwdWMX7crGx+/wDs=
AllowedIPs = 10.6.210.1/32, 10.6.0.0/24
Endpoint = 198.51.100.6:51820

This is an example configuration from a WireGuard client for a full-tunnel configuration:

[Interface]
PrivateKey = WGpL3/ejM5L9ngLoAtXkSP1QTNp4eSD34Zh6/Jfni1Q=
ListenPort = 51820
DNS = 10.6.210.1 pfSense.home.arpa
Address = 10.6.210.2/24

[Peer]
PublicKey = PUVBJ+zuz/0mRPEB4tIaVbet5NzVwdWMX7crGx+/wDs=
AllowedIPs = 0.0.0.0/0
Endpoint = 198.51.100.6:51820

The fields in that file are as follows:

Interface

Settings for this client.

PrivateKey

The private key for this peer. Obtained from the key generation process earlier, or from the peer itself if it was generated by client software directly.

ListenPort

A static port to listen on, or omit the line to use a random port instead.

DNS

The DNS server(s) and search domain that should be used by the system when the tunnel is enabled.

Address

The tunnel address for this client. Not supported on all platforms, as some require configuring the address using command-line utilities. However, clients on Windows and Android, for example, support this directive.

This should use the same CIDR mask as the Tunnel address. In this example, the first peer is 10.6.210.2/24.

Peer

Configuration for the firewall end of the tunnel.

PublicKey

The public key from the Tunnel configuration on the firewall.

AllowedIPs

The Tunnel address, and any additional networks which should be routed across the VPN in a comma-separated list. This could be a LAN subnet (e.g. 10.6.0.0/24) or use 0.0.0.0/0 to route all traffic, including Internet traffic, across the tunnel.

Endpoint

The firewall WAN IP address and WireGuard Listen Port

Note

This only covers the basics, there are numerous other fields which can be used to control client behavior plus additional client options which vary by platform. For additional details, see the WireGuard documentation and the documentation for the WireGuard software used by a peer.

Transfer the resulting client configuration file to the peer in a secure manner. Methods vary by platform and client software.

Finish Up

After configuring the client and activating the VPN, the client should be able to pass traffic to the networks listed in the AllowedIPs list in its configuration.