OPNsense is an open source firewall and routing platform based on FreeBSD, with a web interface, a stateful packet filter, built-in VPNs and an intrusion prevention system powered by Suricata. In this tutorial you will take a freshly installed OPNsense firewall with a WAN and a LAN interface and configure it for real use: assign interfaces, run the setup wizard, update the system, organize rules with aliases, publish an internal web server with a port forward, set up a WireGuard remote access VPN and turn on intrusion prevention with the ET Open ruleset.

Menu paths in this guide match current OPNsense releases (25.x and later). Some pages are renamed between versions, so if a menu item is not exactly where described, use the search box at the top of the web interface.

Prerequisites

To follow this tutorial you need:

  • OPNsense installed on hardware or in a virtual machine (for example on a KVM host) from the official image at opnsense.org/download, with at least 2 CPU cores, 4 GB of RAM and two network interfaces. 8 GB of RAM is recommended if you enable intrusion prevention.
  • Console access to the firewall (keyboard and screen, serial, or the VM console).
  • A computer connected to the LAN side to reach the web interface.
  • For the WireGuard step, a Linux client with the wireguard package installed.

In the examples the LAN is 192.168.1.0/24 with the firewall at 192.168.1.1, and your_wan_ip is the public address of the WAN interface.

Step 1 - Assigning interfaces from the console

After installation, log in on the console as root with the password you set in the installer (the default is opnsense). The console menu appears:

  0) Logout                              7) Ping host
  1) Assign interfaces                   8) Shell
  2) Set interface IP address            9) pfTop
  3) Reset the root password            10) Firewall log
  4) Reset to factory defaults          11) Reload all services
  5) Power off system                   12) Update from console
  6) Reboot system                      13) Restore a backup

Check the interface summary printed above the menu. If WAN and LAN are attached to the wrong network cards, choose 1, answer n to the LAGG and VLAN questions, and enter the correct device names when asked for the WAN and LAN interfaces (for example vtnet0 and vtnet1 on KVM, igc0 and igc1 on many Intel appliances). Confirm with y.

If the LAN must use a different subnet than 192.168.1.0/24, choose 2, select the LAN interface and enter the address and prefix. Answer y to enable the DHCP server on the LAN and give it a range.

From a computer on the LAN, confirm the firewall answers:

ping -c 3 192.168.1.1

Step 2 - Running the setup wizard

Browse to https://192.168.1.1, accept the self-signed certificate warning and log in as root. On the first login the wizard starts automatically; if not, open System > Wizard. Go through its pages:

  1. General Information: set the hostname (for example fw01), the domain and, optionally, upstream DNS servers. Leave Override DNS unchecked if you want to use the servers provided by your ISP over DHCP. OPNsense runs its own Unbound DNS resolver for LAN clients.
  2. Time Server Information: keep the default NTP servers and select your time zone.
  3. Configure WAN Interface: choose the type your uplink uses, DHCP or Static with address, prefix and gateway. Keep Block RFC1918 Private Networks and Block bogon networks checked when the WAN has a public address.
  4. Configure LAN Interface: confirm the LAN address.
  5. Set Root Password: set a strong password, different from the default.
  6. Reload to apply the configuration.

Log in again with the new password. The dashboard shows the version, interface status and gateways.

Step 3 - Updating OPNsense

Always update before configuring services, since updates include security fixes for the base system and plugins. Go to System > Firmware > Status, click Check for updates and then Update in the Updates tab. Major upgrades, which are released twice a year, appear as a separate upgrade option in the same place. The firewall reboots if the update requires it.

After the reboot, System > Firmware > Status should report that there are no updates available.

Step 4 - Creating aliases

Aliases are named groups of hosts, networks or ports. Rules that use aliases stay readable, and when an address changes you update the alias once instead of editing every rule. Go to Firewall > Aliases and create the following, clicking + for each one and Apply at the end:

NameTypeContentDescription
WEB_SERVERHost(s)192.168.1.10Internal web server
WEB_PORTSPort(s)80, 443HTTP and HTTPS
ADMIN_HOSTSHost(s)192.168.1.20, 192.168.1.21Admin workstations

Replace the addresses with those of your own network. To check that an alias resolves correctly, open Firewall > Diagnostics > Aliases, select the alias and see its current content.

Step 5 - Writing LAN firewall rules

OPNsense evaluates rules on the interface where the traffic enters, from top to bottom, and the first matching rule wins. A new installation has an anti-lockout rule for the web interface and a rule that allows all LAN traffic to anywhere. As an example of tightening this, force LAN clients to use the firewall's own DNS resolver, while the admin workstations can still query any DNS server for troubleshooting.

Go to Firewall > Rules > LAN and click + to add the first rule:

  • Action: Pass
  • Interface: LAN
  • Direction: in
  • Protocol: TCP/UDP
  • Source: ADMIN_HOSTS
  • Destination: any
  • Destination port range: from DNS to DNS
  • Description: Allow any DNS from admin hosts

Save it, then add a second rule:

  • Action: Block
  • Interface: LAN
  • Protocol: TCP/UDP
  • Source: LAN net
  • Destination: This Firewall, with Destination / Invert checked
  • Destination port range: from DNS to DNS
  • Log: checked
  • Description: Block external DNS from LAN

Make sure the pass rule is above the block rule and both are above the default allow rule (drag them or use the move arrows), then click Apply changes.

To verify the rules, run a DNS query against an external server from a normal LAN client:

dig @1.1.1.1 example.com

;; communications error to 1.1.1.1#53: timed out

The same query against 192.168.1.1 works, and from an admin workstation both work. Open Firewall > Log Files > Live View and filter by the rule description to see the blocked attempts and the rule that matched them.

Step 6 - Forwarding a port to an internal server

To publish the web server on the WAN, create a destination NAT (port forward) rule. Go to Firewall > NAT > Port Forward and click +:

  • Interface: WAN
  • Protocol: TCP
  • Destination: WAN address
  • Destination port range: WEB_PORTS
  • Redirect target IP: WEB_SERVER
  • Redirect target port: WEB_PORTS
  • Description: Web server
  • Filter rule association: Add associated filter rule

Click Save and Apply changes. The associated filter rule is created automatically in Firewall > Rules > WAN and is kept in sync with the NAT rule.

Test it from a machine outside your network:

curl -I http://your_wan_ip

HTTP/1.1 200 OK
Server: nginx
...

If you test from the LAN instead, the request may fail even though the forward works, because reaching your own WAN address from inside requires NAT reflection, which is disabled by default. Enable it under Firewall > Settings > Advanced only if you need it; using internal DNS records for your services is usually cleaner.

Step 7 - Setting up a WireGuard remote access VPN

WireGuard is built into OPNsense. In this example the tunnel network is 10.10.10.0/24, the firewall is 10.10.10.1 and one client gets 10.10.10.2.

First, on the Linux client, generate the client key pair:

umask 077
wg genkey | tee client.key | wg pubkey > client.pub
cat client.pub

Copy the public key from the output. Next, create the server instance in OPNsense. Go to VPN > WireGuard > Instances, click + and set:

  • Name: wg0
  • Public key / Private key: click the gear icon to generate a key pair
  • Listen port: 51820
  • Tunnel address: 10.10.10.1/24

Save it and copy the generated public key; the client needs it. Then go to VPN > WireGuard > Peers, click + and set:

  • Name: laptop
  • Public key: the content of client.pub
  • Allowed IPs: 10.10.10.2/32
  • Instances: wg0

Save, go back to the Instances tab, check Enable WireGuard at the bottom and click Apply.

The tunnel now needs three firewall rules. In Firewall > Rules > WAN, add a pass rule with Protocol UDP, Destination WAN address and Destination port range 51820, so clients can reach the listener. In Firewall > Rules > WireGuard (Group), add a pass rule with Source 10.10.10.0/24 and Destination any, so clients can use the tunnel. Finally, so that VPN clients can reach the Internet through the firewall, go to Firewall > NAT > Outbound, switch the mode to Hybrid outbound NAT rule generation, save, and add a rule with Interface WAN, Source address 10.10.10.0/24 and Translation / target Interface address. Apply the changes on each page.

On the client, create the configuration file:

sudo nano /etc/wireguard/wg0.conf

[Interface]
PrivateKey = client_private_key
Address = 10.10.10.2/32
DNS = 9.9.9.9

[Peer]
PublicKey = opnsense_public_key
Endpoint = your_wan_ip:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Replace client_private_key with the content of client.key and opnsense_public_key with the key generated on the instance. AllowedIPs = 0.0.0.0/0 routes all IPv4 traffic through the VPN; use 192.168.1.0/24, 10.10.10.0/24 instead to reach only the LAN. Bring the tunnel up and check the handshake:

sudo wg-quick up wg0
sudo wg show

interface: wg0
  public key: 4mU2...=
  private key: (hidden)
  listening port: 43918
  fwmark: 0xca6c

peer: Xk1P...=
  endpoint: 203.0.113.1:51820
  allowed ips: 0.0.0.0/0
  latest handshake: 5 seconds ago
  transfer: 1.24 KiB received, 2.10 KiB sent

A latest handshake line means the tunnel is established. In OPNsense, VPN > WireGuard > Status shows the same peer as connected. Bring it down with sudo wg-quick down wg0.

Step 8 - Enabling intrusion prevention

OPNsense includes Suricata, configured under Services > Intrusion Detection. In IPS mode it sits inline on an interface and drops packets that match rules set to drop.

IPS mode relies on netmap, which does not work with hardware offloading. Go to Interfaces > Settings and make sure Hardware CRC, Hardware TSO and Hardware LRO are all disabled (they are by default), then reboot if you changed anything.

Go to Services > Intrusion Detection > Administration and, in the Settings tab, set:

  • Enabled: checked
  • IPS mode: checked
  • Promiscuous mode: unchecked
  • Pattern matcher: Hyperscan (if your CPU supports it) or Aho-Corasick
  • Interfaces: WAN

Click Apply. Then open the Download tab, select the ET Open rulesets that fit your network (for example ET open/emerging-scan, ET open/emerging-exploit and ET open/emerging-malware), click Enable selected and then Download & Update Rules.

Downloaded rules only alert by default. To drop traffic, go to the Policy tab, click + and create a policy with the rulesets you enabled, Action set to Alert, and New action set to Drop. Apply it. Start with a small set of rulesets; enabling everything as drop is a common way to break legitimate traffic.

To verify detection, run a quick port scan against your_wan_ip from an outside machine with nmap, then open the Alerts tab. Alerts from the emerging-scan set appear with the source address and, for dropped packets, the action blocked.

To keep rules current, open the Schedule tab, enable the update job and pick a daily time.

Step 9 - Backing up the configuration

OPNsense keeps the whole configuration in one XML file. Go to System > Configuration > Backups and click Download configuration. Store the file outside the firewall; importing it on a new installation from the same page restores all interfaces, rules, VPNs and plugin settings. The same page lists automatic local backups, one per configuration change, which you can compare and roll back to.

Troubleshooting

  • You locked yourself out of the web interface. From the console, choose 8 (Shell) and run pfctl -d to disable the packet filter temporarily, fix the rule in the web interface, then run pfctl -e or reboot.
  • The port forward does not answer. Check that the WAN rule was created, that the internal server uses OPNsense as its default gateway, and that you are testing from outside the LAN.
  • WireGuard has no handshake. Confirm that UDP 51820 is allowed on the WAN, that the peer's public key matches client.pub, and that the instance is enabled. VPN > WireGuard > Log File shows errors.
  • Traffic drops after enabling IPS. Open Alerts, find the rule responsible and change its action back to alert in the Rules tab, or remove its ruleset from the drop policy.

Conclusion

Your OPNsense firewall is now updated and configured with readable alias-based rules, a published web server, a WireGuard VPN for remote access and Suricata blocking known attacks on the WAN. As next steps, split the LAN into VLANs with separate rule sets, add certificates with the ACME client plugin under System > Firmware > Plugins, or set up a second OPNsense with CARP under System > High Availability for failover.