Creating an OPNsense bootable USB drive means writing the downloaded image to the drive as a raw disk image, not copying the file onto it. In practice: decompress the .bz2 download so you have the plain .img file, use an image-writing tool (a graphical writer such as balenaEtcher, Rufus in its raw DD mode on Windows, or the dd command on Linux and macOS) to write that .img onto the correct USB drive, then boot the firewall hardware from the drive. The whole job takes a few minutes of your attention plus the writing time. This guide covers the preparation, all three writing methods, how to boot from the result, and how to confirm the drive really works.
What you need
- The verified, decompressed image. For most hardware that is
OPNsense-26.7-vga-amd64.img; headless hardware uses the serial image, and nano goes to a drive or card of at least 4 GB. If you have not downloaded and checked the file yet, start with OPNsense Download and the checksum verification guide. - A USB flash drive you can erase completely. Writing an image destroys everything on the target drive, including its partition table. There is no undo, so use a drive whose contents you no longer need.
- For nano only: at least 4 GB of media. The nano image is 3 GB and needs a USB drive, SD card or CF card of 4 GB or more, because the card becomes the running system rather than just an installer.
- A card reader, if applicable. Nano users writing to SD or CF media need the appropriate reader attached to the computer doing the writing.
One clarification before any tool opens: the official OPNsense install guide describes the images and the boot process but does not currently name or endorse a specific writing tool. The tools below are the standard, widely used options, presented as our guidance; the principles (raw write, correct target, erase warning) are the same whichever you choose.
Step 1: Decompress the image
Your download ends in .bz2, which is bzip2 compression. Some writers accept the compressed file directly and decompress as they go; others expect the plain image. Decompressing first works everywhere and removes one variable, so that is the recommended route:
- Linux:
bunzip2 OPNsense-26.7-vga-amd64.img.bz2 - macOS: double-click the .bz2 file in Finder, or run
bunzip2in Terminal if you have it. - Windows: extract with 7-Zip or a similar archive tool (right-click, extract here).
Afterwards you should have a single file ending in .img (or .iso for the dvd image, which is normally mounted by a hypervisor rather than written to USB). Keep the original .bz2 as well; it is the file the published checksums describe, so it remains your verified master copy.
A word on drive size for the installer images: the compressed downloads are only a few hundred megabytes, and the decompressed installer images remain modest, so practically any USB stick you already own has room for a vga or serial installer. Capacity only becomes a hard requirement with nano, where the 4 GB minimum is real because the media becomes the running system rather than a delivery vehicle.
Step 2: Write the image
Method A: A graphical writer (Windows, macOS, Linux)
A dedicated image writer such as balenaEtcher is the safest choice for most people, because it shows only removable drives and refuses to touch your system disk. The flow is the same in this class of tool:
- Open the writer and choose the image file (the decompressed .img).
- Select the target USB drive. Read its name and capacity carefully and be certain it is the drive you intend to erase.
- Start the write and let it finish, including any validation pass the tool offers. Validation re-reads the drive and compares it with the image, which is worth the extra minute.
- Eject the drive properly rather than pulling it out, so no cached data is lost.
Method B: Rufus on Windows, in DD mode
Rufus is a popular Windows alternative. The important detail is the mode: when Rufus detects a bootable image it may offer to write in "ISO mode", which extracts files onto a formatted drive. OPNsense USB images are complete disk images, so choose the DD mode (raw image) option when Rufus asks. ISO mode can produce a drive that boots into a menu yet fails to start the installer correctly, which is a confusing failure to debug. Select the image, confirm the target drive is your USB stick and nothing else, choose DD mode, and write.
Method C: dd on Linux or macOS
The dd command writes the image byte for byte and is the traditional method on Unix-like systems. It is also unforgiving: pointing it at the wrong device erases that device. Work carefully:
- Identify the drive's device name with the drive plugged in (on Linux,
lsblk; on macOS,diskutil list). Note the whole-disk device, for example/dev/sdXon Linux or/dev/diskNon macOS, and double-check it by capacity. - Unmount any partitions of that drive that the system mounted automatically (eject them; do not format them).
- Write the image. On Linux the shape of the command is:
sudo dd if=OPNsense-26.7-vga-amd64.img of=/dev/sdX bs=4M status=progress conv=fsync, with your real device in place of sdX. On macOS the equivalent uses the raw device (/dev/rdiskN) for speed. - Wait for the command to return and report records written; dd is silent until it finishes unless you asked for progress output. Then eject the drive.
Whichever method you used, expect your computer to afterwards claim the drive is unformatted or show unfamiliar partitions. That is correct behaviour: the drive now contains a FreeBSD system layout that Windows and macOS cannot read as files. Do not accept any offer to format it.
While the image writes: prepare the target machine
The write takes a few minutes, and it is time well spent getting the firewall hardware ready, because the boot test that follows goes more smoothly when everything is already connected:
- Connect the display and keyboard (for vga), or the console cable and your terminal computer (for serial), before you power on, so you catch the very first boot messages and the boot-menu prompt.
- Plug in at least the LAN network cable. The live environment comes up with its LAN interface at 192.168.1.1, and having a cable in place lets you confirm link lights and even open the web interface from another computer during your test boot. Leave the WAN side for the real installation unless you are deliberately testing the full setup.
- Identify the ports. Look at the machine and note how many network ports it has and any labelling. The installation will ask you to assign interfaces, and knowing the physical layout in advance makes that step calm instead of guesswork.
- Remove other bootable media. Extra USB drives or cards left in the machine can confuse the boot menu; the installer stick should be the only removable boot candidate.
Installing into a virtual machine instead?
If your OPNsense will run as a virtual machine, you can skip this entire guide. Hypervisors boot directly from an ISO file, so download the dvd image, verify it the same way, and attach the .iso to the virtual machine as its optical drive. No USB hardware, decompression choices or write modes are involved. The raw-write process in this article is for physical hardware and for the cards and sticks that embedded devices boot from.
Step 3: Boot the firewall hardware from the drive
Move the drive to the machine that will run OPNsense, connect a monitor and keyboard (or your serial console cable for the serial image), and power on. Most machines need one of two things to boot from USB:
- A one-time boot menu: press the boot-menu key shown during the first seconds of startup (commonly F8, F11, F12 or Esc, depending on the manufacturer) and select the USB drive from the list.
- A firmware setting: enter the BIOS or UEFI setup and either move USB to the front of the boot order or enable USB booting if it is switched off.
The Full images (dvd, vga, serial) are UEFI hybrid images, so they boot on both modern UEFI systems and older legacy BIOS systems. The nano image is the exception: it boots as MBR, so a UEFI-only machine may need its legacy or CSM option enabled before a nano card will start. If the machine ignores the drive entirely, check that the drive is in a working USB port (rear ports on a motherboard are the most reliable during boot) and that any "fast boot" option is not skipping device detection.
How to confirm the drive works
A successful write announces itself clearly at boot. Match what you see against the image you wrote:
- vga image: boot messages scroll on the monitor, the live environment starts, and you are greeted by a console menu on a system reachable at 192.168.1.1. Seeing the menu means the drive works; the installation itself starts only when you log in as the user
installerwith the passwordopnsense, so nothing happens to your disks before that point. - serial image: the same boot sequence appears as text in your terminal program at 115200 baud. Clean, readable text means success.
- nano image: the system boots directly into a running OPNsense and asks you to assign interfaces, because nano is preinstalled and has no installer stage.
If you reach any of those states, the bootable drive is proven good, and you can shut the machine down and plan the real installation, or continue straight into the OPNsense Installation Guide. Note what the live environment is and is not: it runs entirely from the drive and RAM, it is read-only in effect, and any settings you change in it are lost on reboot. It is a safe place to look around, check that your network ports are detected, and confirm the hardware is healthy before you commit to installing.
Troubleshooting
The computer boots its normal operating system instead
The USB drive was not selected as the boot device. Re-enter the boot menu and pick the drive explicitly, or adjust the boot order in firmware setup. Some machines also disable booting from particular ports; move the drive to another port and retry.
The screen stays blank
The most likely cause is a console mismatch rather than a bad write: a serial image shows nothing on a monitor, and a vga image shows nothing on a serial terminal. Confirm which console your hardware uses with VGA vs DVD vs Serial vs Nano, rewrite with the matching image, and boot again. Also give the machine a moment; some boards are slow to hand over to USB boot.
The serial output is garbled
Your terminal speed does not match the console. Set the terminal program to 115200 baud and reconnect; garbled text at the wrong speed is a settings problem, not a broken image.
The writing tool reports errors, or the drive vanishes mid-write
Suspect the drive or the port before the image. Try a different USB port, avoid unpowered hubs, and if errors persist, test another drive; flash media that is wearing out often fails exactly this way. If you suspect the image instead, re-run the checksum verification before rewriting.
The drive worked once but not after the machine was powered off
Check that the firmware saved your boot choice. A one-time boot menu selection applies to that boot only; for the installer that is fine, but a nano system that should boot from its card every time needs the card set as the first boot device in the firmware setup.
Safety recap
- Writing an image erases the entire target drive. Verify the target by name and capacity in the tool before starting.
- With dd, verify the device name twice. The command does not ask for confirmation.
- Keep the verified .bz2 download; it is your known-good source for rewrites.
- A drive that your everyday computer cannot read after writing is normal, not broken. Do not format it.
With a drive that boots to the live environment or, for nano, straight into a running system, you are ready for the final step of this category: the OPNsense Installation Guide, which takes the Full images from this boot screen through disk selection, the root password, and the first reboot into your installed firewall.