Getting Started with Opnsense Build on aarch64

Written by

user

in

This section covers how to get started with a native FreeBSD build environment on aarch64 hardware or emulated systems. Whether you’re building for the Raspberry Pi or any other ARM64 device, this guide walks you through setup using QEMU on Ubuntu and managing the build using opnsense/tools.

1. Download FreeBSD VM Image

Download a prebuilt FreeBSD aarch64 image from the official FreeBSD mirrors:

Download: FreeBSD 14.1 aarch64 QCOW2 Image

Make sure your host system supports uvwxz file systems. For this guide, we’ll be using Ubuntu 20.04 or later due to its ease of use and broader community support. While RHEL-based systems work, they often come with more complex configuration overhead, especially around virtualization tooling.

2. Install QEMU on Ubuntu

sudo apt update
sudo apt install qemu-system-arm

3. Launch FreeBSD in QEMU

Important: Don’t blindly copy the command. Understand what each part does.

qemu-system-aarch64 \
  -m <AMOUNT_OF_RAM_IN_MB> \
  --cpu max \
  --smp cores=<NUMBER_OF_CORES> \
  -M virt,gic-version=3,highmem=on \
  -bios /usr/lib/u-boot/qemu_arm64/u-boot.bin \
  -serial telnet::4444,server \
  -nographic \
  -drive if=none,file=<PATH_TO_VM_DISK.qcow2>,format=qcow2,id=hd0 \
  -device virtio-blk-device,drive=hd0 \
  -device virtio-net-device,netdev=net0 \
  -netdev user,id=net0

This sets up an emulated ARM64 machine with virtio devices and telnet console access.

Connect to the QEMU console:

telnet localhost 4444

4. Clone Build Tools and Generate Keys

Use opnsense/tools for building the image:

git clone https://github.com/opnsense/tools
cd tools

Generate repository keys and fingerprint:

cd /usr/tools/
openssl genrsa -out config/24.7/repo.key 4096
openssl rsa -pubout -in config/24.7/repo.key -out config/24.7/repo.pub
make fingerprint

Save the fingerprint securely — it will be used to verify package integrity.

5. Install Required Build Packages (for RPi/SBC)

pkg install u-boot-rpi4 rpi-firmware aarch64-binutils

Note: aarch64-binutils may not be strictly necessary if you’re not cross-compiling, but it’s useful to have installed regardless.

6. Resolve Package Manager Issues

If you encounter a version mismatch with pkg:

cd /usr/tools/ports/ports-mgmt/pkg
make
make reinstall

7. Build Image

When building the final image, avoid using a 3G size limit — it will likely fail. Allocate at least 8G:

make base DEVICE=RPI SIZE=8G

Warning: Do not use the -j flag (parallel builds) during plugin compilation, especially on lower-powered hardware like the Raspberry Pi. It will result in unstable or failed builds.

8. Final Notes

  • This build process is resource-intensive and will take a long time on low-end aarch64 systems.
  • Use native builds over cross-builds when possible for better compatibility.
  • Stick to DEVICE-specific flags like DEVICE=RPI for tailored images.

More posts