Wireguard - tips for VPN newbies

[sesquipedality]

I have finally managed to get Wireguard VPN set up.  While I do think it's a lot simpler than the old staples like OpenVPN, it's a little bit of a frustrating experience, and the OPNSense instructions, while good as far as they go, do (like much of OPNSense's documentation) rather assume that you already know what you are doing.    So, for people who want to get an easyish VPN up and running but don't necessarily know a lot about Wireguard, here are some tips from my experience.

1) Pre-reading is a really good idea.

Start at wireguard.com for a quick conceptual overview - https://www.wireguard.com/

Read the Wireguard OPNSense instructions carefully.  A lot of of the frustration I experienced was due to not understanding these instructions properly when I started out.  When I came back later, a lot of the answers to the problems I was having were actually there.   There are two example configs provided.  The first, site to site setup, at https://docs.opnsense.org/manual/how-tos/wireguard-s2s.html is for linking the networks at two remote sites.  My usage case focused on connecting individual remote client machines to my local network, so I relied upon the slightly unhelpfully named "road warrior" setup at https://docs.opnsense.org/manual/how-tos/wireguard-client.html.

2) Useful Wireguard concepts

Wireguard is designed with a "general case" and peer-to-peer philosophy in mind, that makes it slightly confusing in a client/server context.  Wireguard nodes are peers, the basic idea is that each peer has a private key and a public key.  If you know your own private key and the other end's public key, and the other end knows its private key and your public key, then you will be able to talk.  But you will also need to understand how your network topology fits into Wireguard's model.

Because nodes are peers and not clients and servers, some of the configuration you would usually do on a server actually takes place on the "client".   On the "server", you can (and should) restrict the addresses a "client" is allowed to present as, but access control is all done outside of Wireguard in the router itself - Wireguard only really handles the creation of the network interface.   If you are reliant on a non-public DNS server, your clients will need to be configured individually to use it.

DHCP is not really a thing with Wireguard.  The remote end decides what IP address it's asking for and the local end gets to say yes or no.  This is true for both ends.

One end (likely the server) is going to need a resolvable DNS name or a static IP.  The other end can be non-fixed and behind a firewall (although you will need to configure keepalive in the latter case), but without one "anchored" endpoint there is no way for the peers to find each other.

3) Shared Secrets

Wireguard provides a pre-shared secret key or PSK (referred to as "shared secret" in OPNSense) as an added layer of security.  This is another key that is known to both clients.  This is optional, and you can ignore it if you like.  Explanations as to how it improves security are sparse at best, but it appears to work by creating a hash with the public keys sent across the network, so your actual keys are never transmitted.   The OPNSense documentation doesn't really refer to this, but if you want to generate one, you can do it from the command line using "wg genpsk".  This key needs to be configured on both ends of the connection.

4) OPNSense configuration - server

Read the OPNSense docs first.

Some settings are not relevant in a client/server setup.  You do not need to set a DNS server on the server end, as this setting is for DNS servers on the remote end of the tunnel.  The "tunnel address" setting is slightly confusing, but you want it to be the IP address and netmask of the local end of the tunnel.  You pick the address, and it needs to be on a different logical network from the other networks on your router.  If you decide on 10.80.0.1 with netmask 255.255.255.0 (so allowing for up to 253 clients), this setting would be 10.80.0.1/24.  OPNSense will generate public and private keys for you when you save the local configuration.

You can use any port number not in use on the local machine for your server.  You will need access to this UDP port through your firewall so that "clients" can talk to it.

5) Client configuration

I found it easiest to create the client configurations outside of OPNSense and then copy the relevant details into the OPNSense GUI.  Wireguard is still relatively new, and there is not much in the way of GUI configuration, so you will likely have to become familiar with its config file format in any event.   Here is a sample client config.

Code: [Select]

[Interface]
Address = 10.80.0.5/24
ListenPort = 51870
PrivateKey = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
DNS = 10.10.0.1

[Peer]
PublicKey = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy=
PresharedKey = zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz=
AllowedIPs = 0.0.0.0/0
Endpoint = my.fqdn.com:51820
PersistentKeepalive = 25

Running through these in order

(I) Interface section - configuration of the local end of the tunnel.
a) Address - the local tunnel endpoint address and network used by the client.  Again this must be otherwise unused on the client. 
b) Listenport - can be anything that's not used locally - if you're behind a firewall, the connection will be on a different port anyway.
c) PrivateKey - Wireguard generates these.  On Unix, the command "wg genkey | tee privatekey | wg pubkey > publickey" will put your key in the file "privatekey".  Remember to keep these secret - do not make these files world readable.
d) DNS - the name of your DNS server on the server network.  You need to set this if you are routing all traffic via the VPN.  You probably don't want to try to run a DNS server directly on the Wireguard interface, because it may not be able to bind to the interface at boot time.  Note that there is no current way to set a default DNS search prefix on Windows, so your Windows users will have to live with typing full domain names for your services.

(II) Peer section - information about the remote end
(a) PublicKey - the server's public key - you can take this from the OPNSense GUI - just edit the "local endpoint" and copy from there
(b) PresharedKey - must be the same for both ends of the tunnel.  Generate using "wg genpsk"
(c) AllowedIPs - 0.0.0.0/0 is the setting to tell this machine to route all of its traffic over the VPN when it is up.  You can alternatively set this only to route traffic to your secure network using e.g. "10.10.0.0/24,10.20.0.0/24"
(d) Endpoint - this is the public name and port of your server
(e) PersistentKeepalive - if your client will never be behind NAT you can leave this out, but if NAT is ever likely to be involved, you will need this to make sure that the firewall on the client end does not close the connection between client and server.

Confguring mobile clients can be painful.  There does not appear to be a qrencode package for OPNSense, but on a Unix system with qrencode installed, you can convert a config file into scanable format using "qrencode -t ansiutf8 -r client.conf" (make sure your terminal window is big enough).  This can then be scanned in in the Android (and possibly iOS) application.  (It may be that the OPNSense maintainers might want to include  graphics/libqrencode in their available packages so that people could install it if they wanted to, but it is rather a niche use case.)

(https://github.com/burghardt/easy-wg-quick is a script used to quickly generate config files for this type of installation which may be worth investigating if you have a lot of clients to set up, but plumbing its configuration in to OPNSense may take some thought.)

6) OPNSense configuration - client

Again, not all settings are relevant in this sort of setup.  Add the relevant ones from the "Endpoints" tab.   "Name" can be whatever you want to call the link.  "Public key" is the client's key as generated above, and "shared secret" is likewise your generated PSK.   "Allowed IPs" should be set to the IP address you want this client to connect as, so in the above example, you would set it to 10.80.0.5/32.  Note that you use a single host netmask, as there is only one IP address that this client is allowed to connect as and this link is not a route to anything other than this specific endpoint.  "Endpoint address" and "endpoint port" are likely to change and do not need to be configured.  You are unlikely to need "keepalive" here, as your server port is accessible via the firewall at all times.  The clients will set keepalive if they need it.

Don't forget to go back to add this endpoint to "peers" in your local endpoint to allow the connections to talk to each other.

6) Routing

This will depend hugely on your setup.  The official docs say that to allow routing to the Internet, you need to add the Wireguard interface to the OPNSense interfaces.   I wasn't able to get this to work, and didn't need to, so it may be that this is out of date.  For me, it was enough to add a firewall rule allowing traffic on the Wireguard interface to pass.   For outbound NAT rules I use a hybrid configuration that turns off NAT on the Wireguard interface (not sure if I need that or not) and after that I created duplicates of the auto-created rules, substituting the "WireGuard" net for my local networks.  In all honestly I find the OPNSense firewall to be a bit of a black art, and there may be a better way to do this, but it seems to work for me.

7) Troubleshooting

Wireguard's diagnostics are, frankly, utterly rubbish, but OPNSense does provide you with most of the info available.  You may also find it helpful to use "tcpdump -i wg0" from the router on the command line interface to monitor the traffic on the VPN link.

OPNSense's "list configuration" tab shows your currently configured tunnels.  If a client is not showing up here, then you probably forgot to add it as a peer to the local endpoint.  If "allowed IPs" is blank, that may be a symptom of an incorrectly configured tunnel.  "Latest handshake" shows when a client last connected - if it's not there, then your tunnel is not working, but bear in mind it can take a short while for the tunnel to come up after you restart it.  Similarly the "Handshakes" tab will show you if a client has connected since you last restarted Wireguard on the server (if the number on the right corresponding to the public key of the link is not 0) so may also be useful.  You can stop and restart Wireguard on the router to reset these if you need to.

Hopefully this info will be useful to someone who, like me, was having trouble getting things to work.

[mimugmail]

When it comes to troubleshooting its always good to go to CLI and do a:

/usr/local/etc/rc.d/wireguard restart

Most of the time the error at the output will put you in the right direction.
Sadly you can't force to output in a file for UI debug.

[miroco]

Nice write-up.

May I suggest that you move it to "Tutorials and FAQs"?


miroco

[sesquipedality]

Thanks.  Happy to have that happen, but I don't think I can do it myself.

[mimugmail]

I put it on my howto collection
https://www.routerperformance.net/opnsense/opnsense-and-wireguard/

[mfpck]

Additionally helpful for understanding and for road-warrior setups indeed:
https://www.wireguardconfig.com/