# opnsense/src: the FreeBSD source tree behind the OPNsense firewall > The opnsense/src repository is the operating system source for OPNsense, a FreeBSD-derived network appliance whose tree includes the kernel, the userland and the web interface. The README in the repository is FreeBSD's own build documentation, and the Makefile exposes the full buildworld and buildkernel targets. **opnsense/src** — OPNsense operating system - Repository: https://github.com/opnsense/src - Website: https://opnsense.org/ - Stars: 522 · Forks: 205 - Language: C - License: NOASSERTION - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/opnsense-src ## What this repository actually is The repository description is the OPNsense operating system, and the default branch is stable/26.7, which tells you the release naming convention immediately. What makes this repository worth reading carefully is that the README is not OPNsense's own documentation. It is FreeBSD's source tree README, starting with the heading FreeBSD Source and the line describing itself as the top level of the FreeBSD source directory. That is what a fork of the FreeBSD source tree looks like: the upstream documentation comes along with it. The README explains that FreeBSD is an operating system used to power modern servers, desktops and embedded platforms, that a large community has continually developed it for more than thirty years, and that its advanced networking, security and storage features have made it the platform of choice for many of the busiest web sites and most pervasive embedded networking and storage devices. That last clause is the one to hold on to. OPNsense is one of the many products built on FreeBSD, and this repository is where the operating system it assembles comes from. It is a large system rather than a component: the tree includes the kernel, the complete userland, the cryptographic libraries, the web server stack and the templated configuration files that become the appliance's configuration interface. The primary language is C, the licence is one GitHub cannot classify with a LICENSE file at the root, and the repository has no GitHub releases. That is expected for an operating system source tree, where the releases are the OPNsense product images rather than tagged source archives. The top-level entries are the FreeBSD build system layout, with a Makefile, Makefile.inc1, Makefile.libcompat and Makefile.sys.inc at the root, along with files such as LOCKS, ObsoleteFiles.inc, RELNOTES, UPDATING and MAINTAINERS. There is a .cirrus.yml and a .cirrus-ci/ directory, which is the continuous integration configuration for FreeBSD, and a .clang-format for the kernel and userland code style. ## The source roadmap and the licensing structure inside the tree The Source Roadmap table in the README is the most useful map of the repository, and it also documents how licensing is handled inside a tree that mixes many licences. The system and user commands live in bin, the third-party software under the Common Development and Distribution License in cddl, and other third-party software in contrib. The cryptographic libraries and commands are in crypto, with the README pointing at crypto/README for details. The templated files that become /etc are in etc, and the GNU-licensed third-party software is in gnu, with the README directing readers to gnu/COPYING and gnu/COPYING.LIB for the GPL and LGPL terms. The kernel and the rest of the system follow the same pattern of separated origins. The kernel sources are in sys, with a pointer to sys/README.md. System include files are in include, system libraries in lib, and system commands intended to be run by other commands or daemons are in libexec. System commands are in sbin, user commands in usr.bin and system administration commands in usr.sbin. Two directories exist specifically for build variants. secure is the build system for cryptographic libraries and commands excluding Kerberos, and kerberos5 is the build system for Kerberos 5 with Heimdal, while krb5 is the build system for Kerberos 5 under MIT. Having both Kerberos implementations buildable from one tree is a practical need for a distribution that has to support either licensing choice downstream. The remaining directories cover the rest of the system: stand for the boot loader sources, release for the Makefiles and scripts that build releases and VM images, rescue for the statically linked /rescue commands, share for shared resources, share for the assembly and other shared data, tools for ancillary utilities and tests not included in the build, tests for the Kyua test suite, and targets for experimental DIRDEPS_BUILD support. The practical consequence for an adopter is that the tree is not uniform. Some directories are upstream FreeBSD maintained by the FreeBSD project, some are OPNsense additions, and some are third-party software under their own terms. A change to a file in contrib/ is a change to a package you import, and a change to sys/ is a change to the kernel. ## Building the tree: buildworld, buildkernel and the targets around them The README says the Makefile in this directory supports a number of targets for building components, or all, of the FreeBSD source tree, and points to build(7), config(8), the FreeBSD handbook on building userland and the handbook for kernels for more information, including setting make(1) variables. The Makefile's own comment block lists the common user-driven targets, and it is the most concrete piece of documentation in the repository. ``` buildworld - Rebuild *everything*, including glue to help do upgrades. installworld - Install everything built by "buildworld". world - buildworld + installworld, no kernel. buildkernel - Rebuild the kernel and the kernel-modules. installkernel - Install the kernel and the kernel-modules. ``` The naming is worth reading as a set of layers. universe is the target that really builds everything, that is buildworld and all kernels on all architectures, and the comment says to define MAKE_JUST_KERNELS or WITHOUT_WORLDS to build only kernels, or MAKE_JUST_WORLDS or WITHOUT_KERNELS to build only userland. worlds and kernels are the same thing but narrower, doing only the worlds or only the kernels. The distinction between world and kernel is the FreeBSD split. A world is the userland, the set of programs and libraries installed into a system, and a kernel is the kernel and its modules. world is buildworld plus installworld with no kernel, which is what you build when you want to build the base system for a different machine architecture than the one you are on, which is how cross-compilation is done in this tree. There is also a tinderbox target, described as the same as universe but presenting a list of failed build targets and exiting with an error if there were any. That is the target for a build farm or a CI runner, because it tells you what broke rather than stopping at the first failure. The check targets are for the installed world rather than the source tree. checkworld runs the test suite on an installed world, and the tests directory holds tests which can be run by Kyua, with tests/README for additional information. The obsolete-file checks, check-old, check-old-dirs, check-old-files and check-old-libs, list or remove things left behind by earlier versions, which is what you need when upgrading a source tree that has been patched locally. ## What OPNsense adds on top of this tree The README does not describe the OPNsense-specific parts, and that is a limitation worth stating plainly rather than papering over. The material describes the FreeBSD source tree layout, the build targets and the upstream licensing structure, and the repository description says only that this is the OPNsense operating system. So what can be said from the tree itself is that this is a full operating system source with the standard FreeBSD layout, and that OPNsense assembles its appliance from it. The web interface that OPNsense is known for, the configuration model that turns a running firewall into a router with a settings page, the plugin mechanism and the update mechanism are all part of the product, but the README here does not name their directories or describe how they are built. The presence of etc/ as a directory of template files is the one structural hint about how the appliance works. In a FreeBSD source tree, etc/ holds the files that become /etc on an installed system, and in OPNsense that directory is where the templated configuration behind the web interface lives, with the templates rendered against the live system state rather than copied verbatim. The UPDATING file and RELNOTES at the root are the other two worth knowing about. RELNOTES carries the release notes for the tree, and UPDATING covers the upgrade path, which for an appliance source tree means how a system moves from one release to the next. The stable/26.7 branch name suggests those notes are maintained per branch, which is the convention for a project that supports multiple release lines at once. The repository also carries a .git-blame-ignore-revs file, which is the mechanism for excluding large mechanical commits from blame, and a .clean_build_epoch file, which marks the point after which incremental build logic can assume a clean tree. Both are practical hints that this tree is regularly rebuilt and rebased rather than treated as a one-off import. For an adopter, the sensible reading of the README is as the upstream documentation it is. The build(7), config(8) and handbook pages it links to are the actual instructions, and they are written for FreeBSD, not for OPNsense. That is fine if you know FreeBSD, and it means the first task for anyone evaluating this repository is to establish how much of the upstream documentation they already know. ## Where opnsense/src is the wrong choice There are three limits, and the first is the scale of what a build means. The first is that building this tree is a serious undertaking. The universe target builds everything, including all kernels on all architectures, and even the narrower targets mean compiling a complete operating system. The build requires a working toolchain, the handbook pages for kernel configuration, and enough time and disk for the intermediate objects. If you want a firewall rather than a build system, the OPNsense product images exist for exactly that reason and the source tree is not the route to one. The second is that this is upstream, not the product. Because the README is FreeBSD's own, you are reading documentation for a base system that OPNsense then adapts. The parts you most likely care about when you think of OPNsense, the web interface and the plugin system, are not documented in this README at all. Anyone adopting this repository to understand or modify the appliance's behaviour has to find the OPNsense-specific documentation separately, and the correspondence between the source tree and the shipped product is not something the README establishes. There is also the licence question, which is specific to this repository rather than to FreeBSD upstream. The metadata classifies the licence as one GitHub cannot classify, with a LICENSE file at the root. For a tree that mixes FreeBSD's own BSD-licensed code with CDDL, GPL, LGPL and MIT third-party software in separate directories, the composite licensing is complex, and the per-directory structure in the Source Roadmap is how that complexity is managed rather than hidden. Any redistribution needs attention to which directory a file came from. The honest alternative depends on what you are trying to do. To run a firewall, use the OPNsense images and the plugin repository rather than this tree. To build OPNsense packages, you work here, and the FreeBSD handbook is the right reference. To learn how a network operating system is put together, this tree is an unusually complete and well-documented example, since the documentation is written by the people who built it rather than reverse-engineered from a running system. What opnsense/src offers over those alternatives is the whole system in one place with its build system intact, which is what makes it possible to patch, extend or rebuild rather than configure. The cost is that you are taking on a source tree whose primary documentation describes the upstream project, and whose scale and licensing structure are those of a full operating system. ## Conclusion Adopt opnsense/src if you are building OPNsense images or maintaining OPNsense packages, since it is the source for the whole appliance rather than a component of it. Do not adopt it if you want a firewall distribution you can install from an image, because the build targets produce a system from source rather than a packaged product. Before you build, read the FreeBSD build documentation linked from the README, and note the default branch is stable/26.7 with the last push on 2026-10-15. ## FAQ ### What is the opnsense/src repository? It is the operating system source for OPNsense, a FreeBSD-derived network appliance. The repository description says OPNsense operating system, the default branch is stable/26.7, and the tree contains the kernel, the userland, the cryptographic libraries and the templated configuration files, following the FreeBSD source layout. ### Why does the opnsense/src README describe FreeBSD? Because the repository is a fork of the FreeBSD source tree and the upstream README comes with it. The README begins with the heading FreeBSD Source and describes itself as the top level of the FreeBSD source directory, so the build documentation it links to, build(7), config(8) and the handbook, is written for FreeBSD rather than for OPNsense. ### How do I build the opnsense/src tree? The Makefile at the root carries the user-driven targets. universe builds everything including all kernels on all architectures, worlds and kernels build only those parts, buildworld rebuilds everything and installworld installs it, world is buildworld plus installworld with no kernel, and buildkernel plus installkernel handles the kernel and its modules. The README points to build(7), config(8) and the handbook for the details. ### How is licensing handled across the opnsense/src tree? By directory. The Source Roadmap table assigns each directory a licence: cddl holds third-party software under the Common Development and Distribution License, gnu holds software under the GPL or LGPL with the terms in gnu/COPYING and gnu/COPYING.LIB, crypto holds the cryptographic libraries, kerberos5 is the Heimdal build system and krb5 the MIT one. The README also notes that additional copyright information exists for some sources in the tree. ### What do the buildworld and checkworld targets do in opnsense/src? buildworld rebuilds everything including the glue that helps with upgrades, and installworld installs what buildworld produced. checkworld runs the test suite on an installed world rather than on the source tree, using the Kyua test framework, with tests/README giving more information. The tinderbox target behaves like universe but lists failed build targets and exits with an error if there were any. ## Sources - [Issues](https://github.com/opnsense/src/issues) - [opnsense/src on GitHub](https://github.com/opnsense/src) - [Project website](https://opnsense.org/) - [README](https://github.com/opnsense/src/blob/stable/26.7/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/opnsense-src