OPNsense

Home›Blog›Security & Troubleshooting›OPNsense WireGuard VPN Setup for Secure Remote Access

OPNsense WireGuard VPN Setup for Secure Remote Access

Category: Security & Troubleshooting · Updated 2026-11-19 · Applies to OPNsense 26.7

Illustration of a phone connecting through an encrypted tunnel to a home network

You set up WireGuard in OPNsense from the GUI at VPN > WireGuard: create an Instance (the firewall's side of the tunnel, with its own keypair and tunnel address), add one Peer per device that may connect, open the listen port on the WAN, add a firewall rule for the tunnel, and confirm success by a recent handshake on the Status page. When the handshake appears and your phone can open a LAN address while its traffic shows your home connection, the VPN is working.

What you are building

WireGuard is a modern VPN protocol built into OPNsense, so there is nothing extra to install. The setup in this guide is the classic road warrior pattern: phones and laptops out in the world connect back to your firewall, and once connected they can reach your LAN as if they were at home, while their internet traffic can optionally leave through your home connection as well. OPNsense organises WireGuard into two kinds of objects, and understanding them makes every later step obvious:

  • An Instance is the local tunnel device on the firewall (named wg0, wg1, and so on). It holds the firewall's keypair, its tunnel address, and the port it listens on.
  • A Peer is one remote device allowed to use an instance. Each peer has its own keypair and its own tunnel address. One peer per device, always: sharing a peer between two devices causes connection fights that look like random dropouts.

The official documentation for this setup is the WireGuard client how-to, and this guide follows the same model with the reasoning filled in.

Plan your addresses before you click anything

WireGuard needs a small private network for the tunnel itself, separate from your LAN. Pick a range you do not use anywhere else. The official how-to uses a tunnel network of 10.10.10.0/24 as its example, with the firewall taking 10.10.10.1/24; this guide uses the same example so the pieces line up if you cross check the documentation.

DeviceTunnel addressNotes
OPNsense instance10.10.10.1/24The instance address uses the full network mask, not a /32
Phone10.10.10.2/32Each peer gets its own single address
Laptop10.10.10.3/32Next free address in the tunnel range
  • Choose a tunnel range that does not overlap your LAN, your guest network, or any VLAN subnets you run. Overlaps produce routing behaviour that is miserable to debug.
  • Write down which address belongs to which device. You will thank yourself the first time a peer misbehaves.
  • Decide now whether peers should reach only the LAN (split tunnel) or send all traffic through home (full tunnel). You can change it later; it is set per peer by its allowed addresses, explained below.

Step 1: Create the instance on OPNsense

Go to VPN > WireGuard > Instances and add a new instance:

  1. Give it a clear name, such as RoadWarrior.
  2. Generate the keypair in the GUI. The private key stays on the firewall; the public key is what you will paste into each client device later.
  3. Set the listen port. The conventional WireGuard port is 51820, and the official how-to uses it; a different port is fine as long as you use it consistently in the WAN rule and the client configs.
  4. Enter the tunnel address for the firewall side, 10.10.10.1/24 in our example. The official guidance is explicit on two points here: use the network mask rather than a /32 for the instance, and leave the instance DNS field blank.
  5. Save, then enable WireGuard overall and apply.

Step 2: Create one peer per device

Each connecting device needs its own keys. The cleanest workflow is to generate the device's keypair in its WireGuard app (every platform app can do this), copy the device's public key, and register it on the firewall. Private keys should never travel or be pasted into the firewall for a device generated peer.

Go to VPN > WireGuard > Peers and add a peer for the first device:

  1. Name it after the device and its owner, such as phone-alex, so the status page stays readable.
  2. Paste the device's public key.
  3. Set the allowed addresses to that device's tunnel address as a single host, 10.10.10.2/32 for the phone. On the firewall side this field means: these are the addresses this peer may use as its source inside the tunnel.
  4. Select the instance it belongs to.
  5. Save and apply. Repeat for each additional device, incrementing the tunnel address.

Step 3: Let the tunnel in through the WAN

WireGuard listens quietly and answers only correctly keyed peers, but the firewall still needs a rule that lets the initial packets arrive. Add a WAN rule:

  • Protocol: UDP.
  • Destination: the WAN address, destination port 51820 (or your chosen listen port).
  • Action: pass.
  • Description: something you will recognise later, such as Allow WireGuard in.

If your internet connection has a dynamic public address, your devices also need a hostname that follows it, which usually means a dynamic DNS name configured once and used as the endpoint in every client config. A client pointing at an old IP address is the single most common reason a previously working tunnel stops connecting after an ISP change.

Step 4: Let tunnel traffic reach the LAN

A connected peer is on the tunnel network, not on your LAN, so one more rule decides what it may reach. Assign the WireGuard instance as an interface if you want per tunnel rules and a friendly name in the rules screens, then add a rule on the WireGuard interface (or interface group) that passes traffic from the tunnel network to your LAN network. Start permissive while you verify the tunnel works, then tighten it: many home setups end with the tunnel allowed to reach the LAN but not the firewall's own admin ports from unknown devices, or limited to specific hosts such as a file server. If you run IDS/IPS with Suricata, remember the tunnel interface is just another interface: you choose deliberately whether it is inspected.

Step 5: Configure the client device

In the device's WireGuard app, create a tunnel with these pieces:

  • Private key: the device's own private key, generated in the app.
  • Address: the device's tunnel address, for example 10.10.10.2/32.
  • Peer public key: the firewall instance's public key from Step 1.
  • Endpoint: your public address or dynamic DNS name, with the listen port, for example yourname.example.org:51820.
  • Allowed addresses (on the client): this is the routing decision. Use your LAN network (for example 192.168.1.0/24) plus the tunnel network for a split tunnel that only sends home traffic through the VPN. Use 0.0.0.0/0 for a full tunnel where all internet traffic also exits via home; if you choose full tunnel, also set a DNS server in the client config (your firewall's LAN address is the natural choice) or name resolution will leak or fail.
  • Persistent keepalive: setting this to a modest value such as 25 seconds helps connections survive NAT on hotel and mobile networks. It is optional on the firewall side; it matters on the client.

Confirm it worked: the handshake

WireGuard is silent when idle, so the proof of life is the handshake. Connect the device, then open VPN > WireGuard > Status on the firewall:

  • Your peer should show a latest handshake time within the last minute or two, plus small but growing transfer counters.
  • From the device, open a LAN address you know answers, such as the firewall's LAN IP or a local server. It should load exactly as it does at home.
  • If you built a full tunnel, check the device's public IP with any what is my IP page: it should show your home connection's address, not the cafe or mobile network you are sitting on.
  • Disconnect and reconnect once. A healthy setup handshakes again immediately; you are checking that the success was not a one off.

A recent handshake with no working traffic means the tunnel is up and a rule or route is missing. No handshake at all means the packets are not arriving or the keys do not match. That split tells you where to look next.

Troubleshooting by symptom

No handshake appears on the status page

Check, in order: the WAN rule exists and matches UDP on the right port; the endpoint in the client config points at your current public address (dynamic DNS updated?); the client has internet access at all; and the public keys are not swapped. The most frequent key mistake is pasting the firewall's public key into the firewall's peer entry, or the device's private key where its public key belongs. Public keys only, on both sides, each side holding the other's.

Handshake works, but the LAN does not answer

The tunnel is fine; routing or rules are not. Confirm the client config's allowed addresses include your LAN network, confirm the firewall has a pass rule from the tunnel network to the LAN, and confirm the device you are pinging is on and answers other LAN devices. If you assigned the WireGuard interface, make sure the rule sits on that interface and that the interface is enabled.

LAN works, but the internet breaks when connected

That is the full tunnel pattern: the client sends everything to the firewall, and the firewall is not passing it onward or DNS fails. Check the client's DNS setting first (blank DNS with a full tunnel is a classic failure), then confirm the tunnel rule allows traffic to the internet, not just to the LAN.

It worked at home testing, but not from outside

Testing from your own Wi-Fi can succeed through paths that do not exist from the internet. Always verify from a genuinely external network, such as the phone on mobile data with Wi-Fi off. If it fails only externally, look again at the WAN rule and at anything upstream of the firewall (an ISP router in front of OPNsense needs its own port forwarding, and some ISPs block inbound traffic entirely).

Good habits once it runs

  • One peer per device, named clearly, so a lost phone is one peer deletion rather than a rebuild of the whole tunnel.
  • Keep the client configs and the firewall backup together; the configuration backup at System > Configuration > Backups includes your instances and peers, as covered in our backup and restore guide.
  • Revisit the tunnel firewall rule after the first week and trim it to what you actually use.
  • If a device is retired, delete its peer. Old peers with valid keys are standing invitations nobody remembers issuing.

Extending the setup later

The road warrior pattern in this guide is the foundation for the other common shapes. A second instance can serve a different group with different rules: family devices on one instance with broad LAN access, a contractor or a guest on another that reaches a single server. Because instances are separate devices with separate addresses and ports, their rules stay independent, and a mistake in one does not open the other. Site to site tunnels between two OPNsense firewalls use the same objects, with each side holding the other as a peer and the allowed addresses describing the far network rather than a single host. The verification habit is identical there too: look for the handshake first, then test traffic.

Key hygiene deserves one paragraph of its own. A peer's private key is the whole credential: anyone holding it is that device, as far as the firewall knows. Keep client configs out of shared cloud notes and email, generate fresh keys when a device changes hands, and when you replace a phone, create a new peer for it instead of copying the old phone's keys across. The five minutes this costs is the entire security model working as intended.

What success should feel like day to day

A finished setup disappears. The phone connects in a second or two when you toggle the tunnel, LAN names and addresses behave exactly as they do at home, and the status page quietly accumulates handshakes. If connecting takes half a minute, or works only on the second attempt, something in the chain above is marginal, usually the endpoint or the keepalive, and it is worth fixing while the details are fresh rather than training yourself to tolerate it.

Done in this order, WireGuard on OPNsense is a short job: one instance, one peer per device, two rules, and a handshake to prove it. Remote access stops depending on exposed services, and your LAN becomes reachable from anywhere without being reachable by everyone.

Keep going in Security & Troubleshooting