Install OPNsense on a Mini-PC in 7 Steps for 2026

A mini-PC with several Intel network ports can serve as a router and firewall running OPNsense, a free FreeBSD-based distribution. This tutorial covers installing it on the internal disk, assigning the WAN and LAN interfaces, the setup wizard, the DHCP server, DNS filtering (domain blocking) and the checks. The menus named here come from the official documentation (26.x series). OPNsense changes quickly, so if a label differs, check the documentation for your version.

Important note for France: fully replacing an ISP box (Orange, Free, SFR, Bouygues) often requires provider-specific settings (VLANs, DHCP options, PPPoE credentials) and may cost you TV or phone service. The simplest way to start is to place OPNsense behind the box, with the OPNsense WAN plugged into a LAN port of the box. You can replace the box later.

Prerequisites

• An x86-64 (amd64) mini-PC with at least two Ethernet ports. The hardware documentation lists a 1 GHz dual-core CPU and 3 GB of RAM as the minimum. It recommends a 1.5 GHz multi-core CPU, 8 GB of RAM and a 120 GB SSD. Intel network cards are recommended. ARM processors (Raspberry Pi) are not supported.
• Example of suitable hardware: the Protectli Vault VP2420. It is a fanless unit (Celeron J6412, AES-NI) with four Intel 2.5 GbE ports (i225-V or i226-V depending on the production batch). On FreeBSD, these ports show up as igc0 to igc3. It also has an HDMI output and a serial console port.
• A USB stick of at least 1 GB. Its contents will be erased.
• A monitor and keyboard for the installation (or a serial console cable if you use the “serial” image).
• A Linux computer to prepare the stick (the commands below use Linux).
• No existing operating system is needed: OPNsense installs directly on the internal disk, which will be erased.

Step-by-step installation

Step 1: Download and verify the USB image

On opnsense.org/download, choose the amd64 architecture, the vga image type (USB image with screen output, UEFI-compatible) and a mirror. Download the .img.bz2 image and the checksum file. Do not use a virtual machine image or an old release (such as 20.1): take the latest stable release on offer. Replace 26.7 with the version number actually shown.

VERSION=26.7
MIRROR="https://URL-OF-CHOSEN-MIRROR/opnsense/releases/${VERSION}"
mkdir -p ~/opnsense && cd ~/opnsense
wget "${MIRROR}/OPNsense-${VERSION}-vga-amd64.img.bz2"
wget "${MIRROR}/OPNsense-${VERSION}-checksums-amd64.sha256"
sha256sum "OPNsense-${VERSION}-vga-amd64.img.bz2"
grep "vga-amd64.img.bz2" "OPNsense-${VERSION}-checksums-amd64.sha256"

Check: the two SHA-256 hashes shown must match. If they differ, download the image again, possibly from another mirror. The documentation also describes how to verify the signature with openssl.

Then decompress the image:

bunzip2 -k "OPNsense-${VERSION}-vga-amd64.img.bz2"
ls -lh "OPNsense-${VERSION}-vga-amd64.img"

Step 2: Write the image to the USB stick

⚠️ dd erases the target device without asking for confirmation. First identify the stick with certainty: plug it in, then check the output of lsblk (size, model, TRAN = usb).

lsblk -o NAME,SIZE,MODEL,TRAN,MOUNTPOINTS

If the stick is /dev/sdX (replace X, and never use the system disk), unmount its partitions, then write the image:

sudo umount /dev/sdX?* 2>/dev/null
sudo dd if="OPNsense-${VERSION}-vga-amd64.img" of=/dev/sdX bs=16k status=progress conv=fsync
sync

Check: sudo fdisk -l /dev/sdX must show a partition table on the stick. According to the documentation, a “trailing garbage” warning may appear because of the digital signature. You can ignore it.

Step 3: Boot from the stick and install to the internal disk

1. Plug the stick into the mini-PC, open the firmware boot menu and boot from the USB stick.
2. The live system starts. Log in as user installer with password opnsense. If that account does not work, log in as root / opnsense, choose 8) Shell and run opnsense-installer.
3. Keep the default keymap or choose your own.
4. Choose ZFS (generally recommended) or UFS. With ZFS on a single disk, the stripe type is fine.
5. Select the internal disk (often ada0 for SATA, nvd0 or nda0 for NVMe, mmcsd0 for eMMC), not the USB stick (usually da0). Check the size shown.
6. ⚠️ Confirm the “last chance” warning: the selected disk will be wiped entirely.
7. Set a strong root password, then choose Complete Install. Remove the stick when the machine reboots.

Check: after rebooting without the stick, the console shows the OPNsense version, the detected interfaces and the numbered menu (from 0) Logout to 13) Restore a configuration). Choose 8) Shell and type:

opnsense-version
ifconfig -l

The first command prints the installed version. The second lists the interfaces (for example igc0 igc1 igc2 igc3 on the VP2420).

Step 4: Assign the WAN and LAN interfaces

On the console, choose 1) Assign interfaces. Answer “no” to VLAN setup (unless your ISP requires VLANs), then enter the WAN interface (for example igc0) and the LAN interface (for example igc1). To tell the ports apart, unplug and replug a cable: the link status changes. Then connect the WAN to the box or ONT, and your PC to the LAN.

By default, the LAN uses 192.168.1.1/24 and the WAN gets its address via DHCP. If your box already uses the 192.168.1.0/24 network, change the LAN address to avoid a conflict. Choose 2) Set interface(s) IP address, select the LAN and give it, for example, 192.168.10.1 with a 24 mask. The tool offers to enable a DHCP server on the LAN: accept and enter a range, for example 192.168.10.100 to 192.168.10.199. Decline switching the web interface to HTTP.

Check: from the console, 7) Ping host to 9.9.9.9 must get replies. On the PC connected to the LAN:

ip -4 addr show
ip route | grep default
ping -c 4 192.168.10.1

The PC must have an address in the DHCP range and a default route to the OPNsense LAN address.

Step 5: Setup wizard in the web interface

Open https://192.168.10.1 (or https://192.168.1.1 if you kept the default address). The certificate is self-signed, so a browser warning is expected. Log in as root with the password set during installation. The wizard (System > Wizard) opens on first login and lets you set:

• the hostname, domain, time zone and DNS servers;
• the WAN type: DHCP behind a box, PPPoE with the ISP credentials, or a static address;
• the LAN address and the root password.

On the WAN page, if OPNsense sits behind a box (private 192.168.x.x WAN address), untick “Block private networks”. Otherwise, traffic from the box will be blocked. You can change these settings later in Interfaces > [WAN] and System > Settings > General. The full configuration is stored in /conf/config.xml. Do not edit this file by hand: use the web interface or the console menu.

Check: Interfaces > Overview must show an IPv4 address and a gateway on the WAN. From the shell (option 8):

ping -c 4 9.9.9.9
drill opnsense.org

Step 6: Check DHCP and firewall rules

According to the documentation, the wizard sets up Unbound for DNS and Dnsmasq for DHCP. The range is configured in Services > Dnsmasq DNS & DHCP > DHCP ranges: add or edit the range (Interface = LAN, start and end addresses), then Save and Apply. The served interfaces are selected in the General tab. On an older, upgraded installation, DHCP may still be handled by ISC DHCP (plugin) or Kea (Services > Kea DHCP). Enable only one DHCP server per interface.

Firewall: by default, the WAN blocks all unsolicited inbound traffic, and the LAN allows outbound access to the Internet. Do not add any allow rule on the WAN (no SSH, no web interface). Review the rules in Firewall > Rules > LAN and Firewall > Rules > WAN. Outbound NAT is automatic. After a change made from the console, reload the firewall:

configctl filter reload
pfctl -sr | head -n 20

Check: on the LAN PC, ip -4 addr must show an address in the range, and ping -c 4 opnsense.org must get replies. Leases handed out are visible in the leases tab (Leases) of the DHCP service in use.

Step 7: DNS filtering and configuration backup

OPNsense has no “Content Filter” menu, and SquidGuard is a pfSense package. Simple filtering is done with Unbound DNS blocklists: Services > Unbound DNS > Blocklists. Tick Enable, choose one or more lists under Type of DNSBL, optionally add allowed or blocked domains, then Apply. To update the lists regularly, add an “Update Unbound DNSBLs” job in System > Settings > Cron. This filtering only works if clients use OPNsense as their DNS server.

Then back up the configuration: System > Configuration > Backups > Download configuration. Keep this XML file off the router: it contains secrets.

ls -l /conf/config.xml
ls /conf/backup | tail -n 5

Check: from the LAN PC, nslookup <domain-in-the-list> 192.168.10.1 must return 0.0.0.0 (or NXDOMAIN, depending on the chosen setting), while a normal domain still resolves.

Verification checks

• Lobby > Dashboard: version, gateway and service status.
• System > Gateways > Configuration: the WAN gateway must be online.
• System > Firmware > Status > Check for updates: the check must succeed, which also confirms Internet access and DNS.
• On a LAN client:

ping -c 4 9.9.9.9
nslookup opnsense.org 192.168.10.1
curl -kIs https://192.168.10.1 | head -n 1

Security and best practices

• Keep the web interface and SSH reachable from the LAN only. For remote administration, use a VPN (WireGuard or OpenVPN), never a port forward.
• In System > Settings > Administration, keep SSH disabled, or restrict it to the LAN interface with key-based authentication. Make sure the web interface only listens on the LAN (Listen Interfaces option).
• Use a strong root password. You can enable TOTP (2FA) via System > Access > Servers and the authentication settings, as described in the documentation for your version.
• Apply updates: System > Firmware > Status for minor updates, console option 12) Update from console for major releases. Back up before every update.
• On a public WAN, keep Block private networks and Block bogon networks ticked in Interfaces > [WAN].

Troubleshooting common errors

No address on the WAN

Likely cause: the cable is in the wrong port, or the interfaces are swapped. Check with ifconfig (status active) and run 1) Assign interfaces again. Behind a box, make sure Block private networks is unticked. For PPPoE, check the credentials and any VLAN your ISP requires.

The LAN PC gets no address

Likely cause: no DHCP server is running, or two DHCP servers are active on the same interface. Check Services > Dnsmasq DNS & DHCP and disable ISC/Kea if they are active on the LAN. Dnsmasq will not start if another DHCP service is holding its ports.

Web interface unreachable

Make sure the PC is on the LAN network, then use console option 11) Restart web interface. If the address conflicts with the box, change the LAN address (option 2).

Internet works by IP but not by name

Likely cause: a DNS problem. Test drill opnsense.org from the shell and check Services > Unbound DNS > General. If a legitimate site is blocked, add it to the Blocklists allowed domains.

FAQ

Do I need to install Linux before OPNsense?

No. OPNsense is a complete FreeBSD-based system: it installs directly on the disk and replaces whatever was there.

Can I use sudo or nano in the shell?

They are not installed by default and are not needed. You are already root in the shell, and everything is configured through the web interface or the console menu.

How do I update OPNsense?

Go to System > Firmware > Status, click Check for updates, then install the updates. The update settings are in System > Firmware > Settings. Major upgrades (for example 26.1 to 26.7) can also be done with console option 12.

Is the Protectli Vault VP2420 suitable?

Yes. It has four Intel 2.5 GbE ports supported by FreeBSD’s igc driver and a 64-bit CPU with AES-NI, so it matches OPNsense’s hardware recommendations. Check the RAM and storage options you choose when buying.

Read also

• Installer home assistant sur un mini pc
• Meilleur mini pc fanless silencieux homelab
• Comparison raspberry pi 5 vs mini pc n100