How to Create a Custom FreeBSD Distribution on the FreeBSD Operating System
Categories:
4 minute read
Introduction
FreeBSD is a powerful, secure, and highly customizable Unix-like operating system known for its performance, advanced networking capabilities, and permissive licensing. One of its greatest strengths is the ability to create custom distributions tailored to specific needs, whether for embedded systems, servers, security appliances, or personal use.
Creating a custom FreeBSD distribution involves modifying the base system, selecting only the necessary components, and packaging them into an installable image. This guide will walk you through the process step by step, covering everything from setting up a build environment to generating a bootable ISO.
Prerequisites
Before starting, ensure you have the following:
- A FreeBSD System – You need a working FreeBSD installation (version 13 or later is recommended) with administrative privileges.
- Sufficient Disk Space – At least 20GB of free space is recommended for building the system.
- Basic Knowledge of FreeBSD – Familiarity with the command line, ports system, and kernel configuration is helpful.
- Git Installed – Required for fetching the FreeBSD source code.
Step 1: Setting Up the Build Environment
To create a custom FreeBSD distribution, you need the FreeBSD source code and build tools.
1.1 Install Required Tools
Ensure you have the necessary tools installed:
pkg install git bash
1.2 Fetch the FreeBSD Source Code
The FreeBSD source code is maintained in a Git repository. Clone it with:
git clone https://git.freebsd.org/src.git /usr/src
Alternatively, you can check out a specific release branch:
git clone -b stable/13 https://git.freebsd.org/src.git /usr/src
1.3 Update the Source Tree (Optional)
If you want the latest changes, run:
cd /usr/src && git pull
Step 2: Configuring the Custom Distribution
FreeBSD provides a flexible build system that allows customization at multiple levels.
2.1 Understanding src.conf and make.conf
src.conf– Controls which parts of the base system are built.make.conf– Defines compiler flags and build options.
Create or modify /etc/src.conf to disable unnecessary components:
# Example: Disable debugging symbols and unwanted utilities
WITHOUT_DEBUG=
WITHOUT_MAN=
WITHOUT_SENDMAIL=
WITHOUT_SHAREDOCS=
Edit /etc/make.conf for optimization:
# Optimize for the current CPU
CPUTYPE?=native
2.2 Customizing the Kernel
The kernel can be trimmed down to remove unnecessary drivers.
2.2.1 Copy the Default Kernel Configuration
cd /usr/src/sys/amd64/conf
cp GENERIC MYKERNEL
2.2.2 Edit the Kernel Configuration
Open MYKERNEL in a text editor and remove unneeded devices (e.g., legacy hardware support).
Example modifications:
# Disable unused filesystems
nooption EXT2FS
nooption MSDOSFS
# Remove old network drivers
nodevice ed
2.2.3 Build the Kernel
cd /usr/src
make buildkernel KERNCONF=MYKERNEL
Step 3: Building the Base System
Once the kernel is configured, build the userland:
make buildworld
This compiles the entire FreeBSD base system according to your src.conf.
Step 4: Creating a Custom Installation Image
FreeBSD provides nanobsd and release tools for generating custom images.
4.1 Using release.sh for Custom ISOs
The release script automates the creation of installation media.
4.1.1 Configure Release Settings
Create a release configuration file:
mkdir /usr/src/release
cp /usr/src/release/release.conf.sample /usr/src/release/release.conf
Edit /usr/src/release/release.conf:
# Example modifications
KERNEL=MYKERNEL
WITHOUT_DOCS=yes
WITH_COMPRESSED_IMAGES=yes
4.1.2 Build the Release
cd /usr/src/release
make release
This generates ISO, memstick, and other installable images in /usr/obj/usr/src/amd64.amd64/release.
4.2 Using nanobsd for Minimal Images
For embedded or lightweight systems, nanobsd is ideal.
4.2.1 Install nanobsd
cd /usr/src/tools/tools/nanobsd
make
4.2.2 Configure nanobsd
Create a configuration file (my_nanobsd.cfg):
#!/bin/sh
NANO_NAME=my_custom_bsd
NANO_SRC=/usr/src
NANO_KERNEL=MYKERNEL
NANO_IMAGES=2
4.2.3 Run nanobsd
sh nanobsd.sh -c my_nanobsd.cfg
This creates a minimal image in /usr/obj/nanobsd.full.
Step 5: Adding Custom Packages
To include additional software, use pkg or the ports system.
5.1 Pre-installing Packages
Modify /usr/src/release/Makefile to include packages:
# Example: Add bash and curl
WORLD_EXTRA_INSTALL+=/usr/local/bin/bash
WORLD_EXTRA_INSTALL+=/usr/local/bin/curl
5.2 Creating a Custom Package Repository
If you need custom-compiled packages:
mkdir /usr/local/packages
pkg create -o /usr/local/packages bash curl
Then, configure the release to include this repository.
Step 6: Testing the Custom Distribution
Before deployment, test the image in a virtual machine (e.g., bhyve or VirtualBox).
bhyve -c 2 -m 4G -H -A -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \
-s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/usr/obj/usr/src/amd64.amd64/release/FreeBSD-13.0-RELEASE-amd64-disc1.iso \
-s 3,virtio-net,tap0 -s 4,ahci-cd,/usr/obj/usr/src/amd64.amd64/release/FreeBSD-13.0-RELEASE-amd64-disc1.iso \
-s 29,fbuf,tcp=0.0.0.0:5900,w=1024,h=768,wait -s 30,xhci,tablet -s 31,hda,play=/dev/dsp0,rec=/dev/dsp0 \
vm0
Step 7: Automating the Build Process
To streamline future builds, create a script that automates:
- Source updates
- Kernel and world builds
- Image generation
Example (/root/build_custom_bsd.sh):
#!/bin/sh
# Update source
cd /usr/src
git pull
# Rebuild world and kernel
make -j$(sysctl -n hw.ncpu) buildworld
make buildkernel KERNCONF=MYKERNEL
# Create release
cd /usr/src/release
make release
echo "Custom FreeBSD image generated in /usr/obj/usr/src/amd64.amd64/release"
Make it executable:
chmod +x /root/build_custom_bsd.sh
Conclusion
Creating a custom FreeBSD distribution allows you to optimize the system for performance, security, or specific use cases. By following this guide, you can:
- Trim unnecessary components from the base system.
- Customize the kernel for better efficiency.
- Generate lightweight or specialized installation media.
- Automate the build process for reproducibility.
FreeBSD’s flexibility makes it an excellent choice for tailored deployments, whether for servers, embedded devices, or security-focused systems. With further experimentation, you can refine your custom distribution to meet exact requirements.
Further Reading
By mastering these techniques, you can fully leverage FreeBSD’s potential for your projects.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.