Build OpenBSD from Source

Synopsis #

Building OpenBSD from source is a development or -stable maintenance workflow. It is not the supported way to move from one release to the next, and a custom kernel is not a routine optimization or hardening step. Normal systems should use signed release upgrades, syspatch(8) , and binary packages.

The authoritative build order is maintained in release(8) and the official source-build FAQ. This guide explains the prerequisites, reboot points, and recovery steps. Read the current official instructions completely before starting a build.

Choose the Exact Branch and Purpose #

OpenBSD development has three relevant states:

  • A release is the published six-month system.
  • -stable is that release plus selected errata and reliability patches.
  • -current is the development branch and is normally entered through the latest snapshot.

Do not compile across a release boundary. To build -stable, begin with the matching release binaries. To build -current, begin with the closest current snapshot and read the current transition instructions before building.

Record the starting system and available space:

uname -a
  # Record the exact running kernel and architecture
sysctl kern.version
  # Record the complete kernel build identity
df -h /usr
  # Confirm space for source and object trees

Keep verified installation media, a console, and current backups available. Installing a kernel or base system can leave the host unable to boot; confirm how to recover it before proceeding.

Obtain Matching Source without Root CVS #

OpenBSD uses cvs(1) for its source repositories. /usr/src is normally writable by members of wsrc. Grant that group only while preserving the account’s other intended supplementary groups, then start a new login session.

Select an official AnonCVS server and verify its published SSH fingerprint. For OpenBSD 8.0 -stable, replace both placeholders below with the listed server and the matching OPENBSD_X_Y branch:

cd /usr
  # Start from the parent of the conventional source directory
cvs -qd anoncvs@ANONCVS_SERVER:/cvs checkout -r OPENBSD_X_Y -P src
  # Fetch the selected stable source branch as an unprivileged wsrc member

For an existing tree:

cd /usr/src
  # Enter the root of the complete source tree
cvs -q up -Pd -r OPENBSD_X_Y
  # Update to the same stable branch

ANONCVS_SERVER and OPENBSD_X_Y are placeholders. A -current checkout omits the stable tag and uses cvs up -Pd -A for later updates. Do not mix sticky tags or update only part of a tree needed by the build.

Confirm the Object Directory #

The base build places objects under /usr/obj. The current release(8) instructions require owner build, group wobj, and mode 770:

ls -ld /usr/obj

If the directory has the wrong ownership or permissions, check for existing builds before correcting it:

doas chown build:wobj /usr/obj
  # Set the required build identity
doas chmod 770 /usr/obj
  # Permit the build user and wobj group

Do not erase /usr/obj recursively as a routine preparation step. Preserve or remove existing objects according to the current build instructions and the work they contain.

Build and Install the Supported Kernel #

Build the kernel before userland so newly built programs run against the required kernel interfaces. The current release instructions use the supported architecture kernel configuration, commonly GENERIC.MP:

cd /sys/arch/$(machine)/compile/GENERIC.MP
  # Enter the supported kernel build directory for the running architecture
doas make obj
  # Create the kernel object directory
doas make config
  # Generate the build configuration
doas make && doas make install
  # Build the kernel and install it as /bsd, preserving the previous kernel as /obsd

Confirm the exact configuration name in the current release(8) instructions for the architecture. Only GENERIC and GENERIC.MP kernels are supported by the OpenBSD project.

Reboot before building userland:

doas reboot

At the boot loader, /obsd is the fallback kernel after a normal kernel installation. Know how to select it before rebooting. After the new kernel starts, confirm uname -a, sysctl kern.version, devices, storage, networking, and console access.

Do not continue to userland when the new kernel fails verification. Boot the preserved kernel and reconcile the source branch, build output, hardware state, and current instructions.

Build the Base System #

With the new matching kernel running, create object directories and build userland:

cd /usr/src
  # Enter the verified source-tree root
doas make obj
  # Create the object-tree links and directories
doas make build
  # Build and install the matching base system

Do not skip make obj. Object files placed in the source tree complicate later builds and cleanup.

After a successful build, merge configuration and refresh device nodes exactly as directed by current release(8) :

doas sysmerge
  # Review and merge changed base configuration files
doas sh -c 'cd /dev && ./MAKEDEV all'
  # Refresh documented device nodes for the architecture

sysmerge(8) can require administrative decisions. Review each local configuration difference; do not accept or discard every file mechanically. Back up /etc and the required recovery data before this phase.

Reboot, then check the enabled services, PF rules, scheduled jobs, installed applications, and logs.

Keep Xenocara and Releases Separate #

Building the base system does not build Xenocara. The Xenocara source tree and build have their own ordered steps in release(8) and xenocara/README.md. Build them only when the development purpose requires it and keep the source branches synchronized.

Creating redistributable release sets, installer images, or a package repository adds destination filesystems, validation, signing, and architecture-specific requirements. It is not necessary merely to update one source-building host.

Avoid Custom-Kernel Drift #

config(8) supports kernel configuration work, but a custom kernel is outside normal support. Reproduce defects with GENERIC or GENERIC.MP before reporting them. Prefer documented boot-time or bsd.re-config(5) methods for a supported narrow device change when current OpenBSD guidance calls for one.

Do not remove drivers to reduce attack surface, copy a configuration from another architecture, or use a custom kernel to conceal a failing device. These changes make upgrades and bug reports harder without establishing a security benefit.

Diagnose Build Failures #

The common causes are:

  • starting from binaries too far from the source tree;
  • checking out the wrong branch or leaving sticky CVS tags;
  • missing current transition instructions;
  • building userland before installing and booting the new kernel;
  • skipping make obj;
  • carrying local source changes into an assumed-clean build;
  • hardware instability exposed by sustained CPU, memory, or storage load.

Preserve the first build error, surrounding output, exact source revision, local diffs, running kernel identity, and build command. Collect OpenBSD Diagnostic Evidence explains how to prepare a useful report.

See Managing Software: Packages and Ports for routine third-party software and Build Third-Party Software from Ports for maintained port customization. Neither workflow replaces a base-system source build.

Report a bug