DOCSEARCHbyAlgolia
Submit Docs

OPNsense Tools Build System

repository·master·Indexed 43 days ago

https://github.com/opnsense/tools

Infrastructure for creating OPNsense sets, packages, and system images (DVD, Memstick, VM). Orchestrates the compilation of FreeBSD base, kernel, ports, and OPNsense-specific plugins and core components. Supports cross-building for other architectures and provides modular build stages via make.

Tokens
1.7K
Snippets
8
Records
11
Agent score
7%

What's inside OPNsense Tools

  1. Build OPNsense images (Quickstart)

    master

    To perform a standard build and generate a DVD image, use the following command:

    # make dvd

    Once successful, you can find the location of the generated images by running:

    # make print-IMAGESDIR
    # make dvd

  2. Set up the OPNsense build system

    master

    To build OPNsense images, you need a FreeBSD 14.3-RELEASE (amd64) machine with at least 40GB of disk space and 8GB of RAM. All tasks require root privileges.

    Standard Installation (in /usr)

    # pkg install git
# cd /usr
# git clone https://github.com/opnsense/tools
# cd tools
# make update

    Non-standard Installation (using ROOTDIR)

    If you want to install the tools in a directory other than /usr, use the ROOTDIR environment variable:

    # mkdir -p /tmp/opnsense
# cd /tmp/opnsense
# git clone https://github.com/opnsense/tools
# cd tools
# env ROOTDIR=/tmp/opnsense make update
    # mkdir -p /tmp/opnsense
# cd /tmp/opnsense
# git clone https://github.com/opnsense/tools
# cd tools
# env ROOTDIR=/tmp/opnsense make update

  3. Cross-build for other architectures

    master

    Cross-building is experimental and requires user-mode emulation packages and additional boot files. To cross-build for a specific device (e.g., BANANAPI or RPI2):

    1. Build base and kernel:
      # make base kernel DEVICE=BANANAPI
    2. Create xtools set (to speed up package building):
      # make xtools DEVICE=BANANAPI
    3. Build packages:
      # make packages DEVICE=BANANAPI
    4. Build final image:
      # make arm-<size> DEVICE=BANANAPI
    # make base kernel DEVICE=BANANAPI

  4. Configure the build via configuration files

    master

    Instead of passing many arguments to make, you can use configuration files located in your CONFIGDIR.

    1. CONFIGDIR/build.conf: The primary configuration file required for the build.
    2. CONFIGDIR/build.conf.local: A local override file that is parsed first. Use this for flexible overrides in specific environments.

  5. Configure Virtual Machine (VM) images

    master

    VM images are not included in binary releases due to varying disk formats and sizes. The default is vmdk with 20G and 1G swap.

    To customize the VM image, use the following syntax:

    # make vm-<format>[,<size>[,<swap>[,<extras>]]

    Available formats:

    • qcow: Qemu, KVM (legacy)
    • qcow2: Qemu, KVM (non-backwards-compatible)
    • raw: Unformatted
    • vhd: VirtualPC, Hyper-V, Xen (dynamic)
    • vhdf: Azure, VirtualPC, Hyper-V (fixed)
    • vmdk: VMWare, VirtualBox (dynamic)

    Arguments:

    • <size>: Disk size.
    • <swap>: Swap size or off to disable.
    • <extras>: An extras.conf hook name.
    # make vm-qcow2,30G,off

  6. Build targeted packages in ports, plugins, or core

    master

    To avoid rebuilding everything, you can target specific packages:

    # make ports-<packagename>[,...]
# make plugins-<packagename>[,...]
# make core-<packagename>[,...]

    Note: Reissuing ports builds will clear progress for plugins and core.

    You can also override the list of packages using:

    • make ports PORTSLIST="security/openssl"
    • make plugins PLUGINSLIST="devel/debug"
    # make ports-curl PORTSENV="DEPEND=no PRUNE=no"

  7. Use build options with `make step`

    master

    The OPNsense build is modular. You can build individual stages (base, kernel, ports, plugins, and core) separately. All steps are invoked via make.

    To specify options on the command line, use the OPTION="value" syntax:

    # make step OPTION="value"

    Early Build Options

    • SETTINGS: The name of the requested local configuration.
    • CONFIGDIR: Path to a directory containing configuration files to override SETTINGS (use absolute paths).

    Build Options

    • ABI: Custom ABI (defaults to SETTINGS).
    • ADDITIONS: List of packages/plugins to add to images.
    • ARCH: Target architecture (if not native).
    • COMSPEED: Serial speed (e.g., 115200, default).
    • DEBUG: Build a debug kernel with extra object information.
    • DEVICE: Device-specific modifications (e.g., A10, default).
    • KERNEL: Kernel config to use (e.g., SMP, default).
    • MIRRORS: List of mirrors to prefetch sets from.
    • NAME: Image name (defaults to OPNsense).
    • PRIVKEY / PUBKEY: Keys for signing sets.
    • SUFFIX: Suffix for the top package name.
    • TIMESTAMP: Fixed timestamp for reproducible pkgbase sets.
    • TYPE: Base name of the top package to be installed.
    • UEFI: Use amd64 hybrid images (e.g., vga vm).
    • VERSION: Version tag.
    • ZFS: Build VM images with ZFS (pool name zroot).
    # make step OPTION="value"

  8. Perform regression tests and audits

    master

    Use these commands to ensure build integrity:

    • make test: Runs regression tests to check the integrity of core.git modifications and generates output for the style checker.
    • make audit: Checks binary packages from ports against the upstream vulnerability database.

  9. Run individual build stages

    master

    The build process is divided into stages that can be run independently. Re-running a stage will continue from previous progress without cleaning.

    TargetDescription
    make baseBuild userland binaries, bootloader, and administrative files
    make kernelBuild the kernel and loadable kernel modules
    make portsBuild all third-party ports
    make pluginsBuild additional plugins
    make coreWrap up core as a package
    make dvdCreate a DVD live image
    make serialCreate a serial memstick live image
    make vgaCreate a VGA memstick live image
    make nanoCreate a flash card full disk image
    make vmCreate a virtual machine full disk image
    make releaseBuild release sets (unpredictable image set)
    make distributionBuild target with sanity checks, image clearing, and core alignment

    Useful Directory Commands

    • make print-SETSDIR: Print the directory where kernel, base, packages, and release sets are stored.
    • make print-IMAGESDIR: Print the directory where final images are stored.

  10. Update code repositories

    master

    You can update the OPNsense repositories using the make update command. You can update all repositories or specify individual ones.

    Syntax:

    # make update[-<repo1>[,...]] [VERSION=git.tag]

    Available repository options:

    • core
    • plugins
    • ports
    • portsref
    • src
    • tools

    Use the VERSION flag to update to a specific git tag instead of HEAD.

    # make update core,plugins VERSION=26.7.4

  11. Clean build artifacts

    master

    Use the make clean-<option> command to remove specific build artifacts and free up space.

    Available clean options:

    • arm, base, dvd, kernel, nano, serial, vga, vm: Removes specific image types.
    • packages, ports: Removes package sets.
    • plugins: Removes plugins from package sets.
    • core: Removes core from package sets.
    • distfiles: Removes distfiles.
    • images: Removes all images.
    • obj: Removes all object directories.
    • sets: Removes all sets.
    • src: Resets kernel/base build directory.
    • stage: Resets main staging area.
    • logs: Removes all logs.
    # make clean-images