OPNsense

Home›Blog›Download & Install›OPNsense Installation Guide: Step by Step on Real Hardware

OPNsense Installation Guide: Step by Step on Real Hardware

Category: Download & Install · Updated 2026-11-19 · Applies to OPNsense 26.7

Illustration of OPNsense being installed on a desktop firewall computer

Installing OPNsense on real hardware follows a short, predictable path: boot the machine from your prepared USB drive, log in to the live environment as the user installer with the password opnsense, choose a keymap, pick ZFS (the recommended option in most cases) or UFS, select the target disk and confirm that its contents will be destroyed, decide on swap, set the root password, and reboot. After the reboot you assign your network interfaces, and the firewall is reachable on the LAN at 192.168.1.1 with its web interface at https://192.168.1.1. This guide walks through every step in order, explains the choices that depend on your hardware, and shows you how to confirm each stage worked before moving on.

Before you begin

  • A bootable USB drive with a Full image (vga for hardware with a display, serial for headless hardware), downloaded and verified. If you still need it, How to Create an OPNsense Bootable USB Drive covers the writing process, and VGA vs DVD vs Serial vs Nano settles which image your hardware needs. (The nano image is preinstalled and is not covered by this guide; there is nothing to install with it.)
  • Hardware that meets the minimum: a 64-bit x86 machine with at least 3 GB of RAM (the installer itself needs 3 GB to run), with 4 GB described as reasonable and 8 GB as recommended in the official sizing guide.
  • A target disk you are prepared to erase. The installer destroys the contents of the disk you select. Back up anything on it first, or physically disconnect drives you cannot afford to lose so they cannot be chosen by mistake.
  • Display and keyboard, or a serial console at 115200 baud, matching your image type.
  • Network cables for LAN and WAN, and a note of which physical port is which, because you will assign interfaces by name at the end.

Step 1: Boot into the live environment

Insert the USB drive, power on, and use the machine's boot menu or firmware settings to boot from the drive, exactly as described in the bootable USB guide. The system loads a live environment: a complete OPNsense that runs from the USB drive and RAM without touching your disks. You will see boot messages, and then a console login prompt and menu.

Two features of the live environment are worth knowing before you log in:

  • The Importer: the Full images can run the OPNsense Importer before the system fully boots. It exists for people reinstalling over an existing OPNsense, because it can import the previous configuration from the old disk. On a fresh build there is nothing to import, so let it pass. Note one consequence if you ever do import: the installer and root password then become the root password of the imported configuration, not the defaults below.
  • The live system is read-only. It is also reachable over the network at 192.168.1.1 (console, web interface and SSH, with the user root and password opnsense), which is handy for a quick look around. But changes made in the live environment are lost on reboot, so treat it as a waiting room, not a place to configure anything.

Step 2: Start the installer

At the console, log in with the dedicated installer account:

  • Username: installer
  • Password: opnsense

Logging in as this user starts the installer automatically. If you logged in as root instead, or the installer did not start, there is a manual route: from the console menu choose 8) Shell, then run opnsense-installer. The installer is a text-mode wizard that you drive with the keyboard: arrow keys or the highlighted letters to choose, Enter to confirm.

Step 3: Keymap and install type

The first question is the keyboard layout (keymap). Choose the layout that matches your physical keyboard so that special characters in passwords later behave as expected; the default is fine for a standard US keyboard. Next you reach the central choice of the installation: the filesystem for the target disk.

OptionWhat it meansChoose it when
ZFSThe modern copy-on-write filesystem, installed with a guided layoutThe documentation recommends ZFS in most cases. It is the right default for an SSD or hard disk install, and it needs a couple of GB at least to be worthwhile.
UFSThe traditional FreeBSD filesystemInstalling onto SD or MMC media, or very small and simple targets where ZFS is not a good fit. The official guidance for SD/MMC installs is UFS, selecting the mmcsd0 device as the target.

For a typical mini PC or converted desktop with an internal SSD, choose ZFS and accept the guided defaults. The choice is about the install target, not about performance tuning; both filesystems run the same OPNsense on top.

Step 4: Select the disk and confirm

The installer lists the storage devices it can see and asks where to install. Identify your target by its model and capacity, not by its position in the list, and select it. For SD or MMC targets, the device to look for is mmcsd0. The installer then gives you the final warning, in plain terms: the contents of the selected disk will be destroyed. This is the point of no return, so read the device name once more before confirming.

If your target disk does not appear at all, stop and troubleshoot rather than choosing a substitute: check that the drive is properly connected, and remember that the installer needs 3 GB of RAM to run, so a machine below that may misbehave before it ever lists disks.

Step 5: Swap and the root password

Two smaller decisions follow. First, swap: the installer asks whether to create a swap partition. The guidance in the official documentation is to skip swap for small targets, specifically those under 16 GB, where the space is worth more than the safety net. On a roomy SSD, accepting the default is fine.

Second, and most important for your security: the installer's final configuration step, "Select Root Password", asks you to set the root password for the new system. Set a strong one and record it in your password manager. If you skip or leave this unchanged, the installed system keeps the well-known default password opnsense for the root account, which anyone can look up; that is acceptable for a few minutes on an isolated bench network and for nothing longer.

The installer then copies the system to the disk. When it reports completion, choose the reboot option, and remove the USB drive while the machine restarts (or change the boot order back), so the machine boots from its new disk rather than from the installer again.

Step 6: First boot and interface assignment

The installed system boots from the internal disk and, on this first start, asks you to assign interfaces. The logic is simple and worth understanding:

  • The first interface you assign becomes LAN, the second becomes WAN, and any further interfaces become optional (OPT) interfaces.
  • You identify ports by their interface names (which reflect the hardware, for example igb0, em0 or similar) and can confirm them by MAC address or by watching which port's link light reacts when you plug and unplug a cable.
  • The wizard asks about VLANs at this stage. They are optional; if you do not need them now, decline and configure them later in the web interface.
  • If you ignore the assignment prompt, the system applies defaults rather than waiting forever, so an unattended first boot still ends in a running firewall, just possibly with the ports in an order you did not intend.

Get this step right and everything after it is easier, because every rule and setting you create later refers to these roles. If you swap LAN and WAN by accident, the symptoms are confusing (no internet, an unreachable web interface from the side you expect), but the fix is benign: reassign from the console menu with option 1) Assign interfaces at any time.

How to confirm the installation worked

Do not declare victory at the reboot. Run through these confirmations, which together prove the system is installed, reachable, and running from the right disk:

  • The console shows the welcome banner and menu. After booting from the internal disk (USB drive removed), the console displays the interface summary, including the line LAN -> v4: 192.168.1.1/24, above the numbered console menu. The default LAN address after installation is 192.168.1.1/24, and the WAN side defaults to DHCP.
  • The web interface answers. From a computer plugged into the LAN side, open https://192.168.1.1. Your browser will warn about the self-signed certificate, which is expected on a fresh install; proceed, and log in as root with the password you set during installation (or opnsense if you left it unchanged, then change it immediately).
  • The console menu is the full installed menu. The installed system offers 13 options, from 0) Logout and 1) Assign interfaces through 8) Shell to 12) Upgrade from console and 13) Restore a configuration. Seeing it means you are looking at the installed system, not the live environment.
  • A second reboot still works. Reboot once more from the console menu (option 5) with the USB drive still removed. A system that survives a cold restart on its own disk is genuinely installed.

Step 7: Update immediately

Your new system runs the 26.7 image, but the series has moved on: the latest update is 26.7.9, and it includes security advisories. Updating is therefore part of the installation, not an optional extra. Once the WAN side has internet access, go to System, then Firmware, then Status in the web interface, click "Check for updates", and install what is offered. The console alternative is option 12) Upgrade from console. When the update finishes and the system has rebooted, check the firmware status page again to confirm you are on the latest version of the series.

Troubleshooting

Logging in as installer does not start the installer

Check the account first: the installer starts for the user installer, not for root. If you are already logged in as root, use the fallback: console menu option 8) Shell, then run opnsense-installer.

The machine boots back into the USB installer after installation

The USB drive is still inserted and still first in the boot order. Remove it, or set the internal disk as the first boot device in the firmware setup, and reboot.

The web interface does not load from your computer

Work from the outside in: confirm your computer is plugged into the port you assigned as LAN, confirm the console banner shows the LAN address 192.168.1.1/24, and confirm your computer received an address in the same range. If you suspect the ports are swapped, fix the assignment at the console with option 1 rather than reinstalling.

You set no root password and the default does not work

If the Importer imported an earlier configuration during boot, the root password is that configuration's root password, not opnsense. On a truly fresh install with no import, the default is opnsense until you change it, and the console menu option 3) Reset the root password exists for exactly this situation.

A note on reinstalling over an existing OPNsense

If this machine already runs OPNsense and you are reinstalling rather than starting fresh, use the Importer that the Full images offer before boot. Point it at the existing installation and it carries the old configuration into the new install, so your interfaces, rules and settings survive the rebuild. Remember the one side effect mentioned earlier: with an imported configuration, the installer and root passwords become the root password of that imported configuration, so have it ready. Reinstalling without the Importer is a genuine fresh start: nothing is preserved, and this guide's defaults apply exactly as written.

What to do next

Your firewall is installed, assigned and patched. The sensible next steps are to finish the initial configuration in the web interface (the setup wizard walks through the essentials), confirm the WAN connection type matches your internet provider, and take a configuration backup (System, then Configuration, then Backups) before you start experimenting, so you always have a known-good state to return to. From here, the Download and Install category has done its job, and the Setup and Configuration guides take over.

Keep going in Download & Install