NANOBSD(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

🌸 NANOBSD(8) — the nanobsd.sh glow-up guide 🌸

okay bestie, sit down, grab a strawberry drink 🍓 — we're talking about nanobsd.sh, from the System Manager's Manual. yes it's a shell script, yes it makes a whole entire tiny FreeBSD, and yes it's iconic. 💅

✨ NAME ✨

nanobsd.sh — create an embedded FreeBSD system image 🫶

🎀 SYNOPSIS 🎀

nanobsd.sh [-BbfhIiKknqvWwX] [-c config-file]

that's it. that's the whole vibe check. ⭐

💖 DESCRIPTION 💖

so nanobsd.sh is a script that produces a minimal implementation of FreeBSD (called NanoBSD), which typically fits on a small media such as a Compact Flash card, or other mass storage medium. like, small small. it can be used to build specialized install images, designed for easy installation and maintenance. obsessed. 🔥

The following options are available:

  • -B — Skip the install stages (both for kernel and world).
  • -b — Skip the build stages (both for kernel and world).
  • -c config-file — Specify the configuration file to use.
  • -f — Skip the code slice extraction.
  • -h — Display usage information.
  • -I — Build the disk image from an existing build/install.
  • -i — Skip the disk image build stage.
  • -K — Skip the installkernel stage of the build.
  • -k — Skip the buildkernel stage of the build.
  • -n — Do not cleanup before each build stage. This suppresses the normal cleanup work done before the buildworld stage and adds -DNO_CLEAN to the make command line used for each build stage (world and kernel).
  • -q — Make output more quiet. 🤫
  • -v — Make output more verbose. 🗣️
  • -W — Skip the installworld stage of the build.
  • -w — Skip the buildworld stage of the build.
  • -X — Make native-xtools.

The features of NanoBSD include:

  • Ports and packages work as in FreeBSD. Every single application can be installed and used in a NanoBSD image, the same way as in FreeBSD. no cap. 👑
  • No missing functionality. If it is possible to do something with FreeBSD, it is possible to do the same thing with NanoBSD, unless the specific feature or features were explicitly removed from the NanoBSD image when it was created.
  • Everything is read-only at run-time. It is safe to pull the power-plug. There is no necessity to run fsck(8) after a non-graceful shutdown of the system. literally just yank it, she'll be fine 💀✨
  • Easy to build and customize. Making use of just one shell script and one configuration file it is possible to build reduced and customized images satisfying any arbitrary set of requirements. one script, one config, infinite possibilities, we love a low-effort queen 🎀

🦋 NanoBSD Media Layout 🦋

The mass storage medium is divided into three parts by default (which are normally mounted read-only):

  • Two image partitions: code#1 and code#2.
  • The configuration file partition, which can be mounted under the /cfg directory at run time.

The /etc and /var directories are md(4) (malloc backed) disks.

The configuration file partition persists under the /cfg directory. It contains files for /etc directory and is briefly mounted read-only right after the system boot, therefore it is required to copy modified files from /etc back to the /cfg directory if changes are expected to persist after the system restarts.

ok this part is the one people always forget 🙈 — if you edit something in /etc and want it to survive a reboot, you must copy it back to /cfg. otherwise it's giving temporary. main character energy only in /cfg.

🔥 BUILDING NanoBSD 🔥

A NanoBSD image is built using a simple nanobsd.sh shell script, which can be found in the src/tools/tools/nanobsd directory. This script creates a bootable image, which can be copied on the storage medium using the dd(1) utility.

The necessary commands to build and install a NanoBSD image are:

cd /usr/src/tools/tools/nanobsd
sh nanobsd.sh
cd /usr/obj/nanobsd.full
dd if=_.disk.full of=/dev/da0 bs=64k

three commands and a dream, bestie 💜

🌈 CUSTOMIZING NanoBSD 🌈

This is probably the most important and most interesting feature of NanoBSD. This is also where you will be spending most of the time when developing with NanoBSD. like, most of the time. this is the whole personality. ✨

Customization is done in two ways:

  • Configuration options.
  • Custom functions.

With configuration settings, it is possible to configure options passed to both the buildworld and installworld stages of the NanoBSD build process, as well as internal options passed to the main build process of NanoBSD. Through these options it is possible to cut the system down, so it will fit on as little as 64MB. You can use the configuration options to trim down the system even more, until it will consist of just the kernel and two or three files in the userland. two or three files!! tiny little baby system 🍓

The configuration file consists of configuration options, which override the default values. The most important directives are:

  • NANO_NAME — Build name (used to construct the working directory names).
  • NANO_SRC — Path to the source tree used to build the image.
  • NANO_KERNEL — Name of the kernel configuration file used to build the kernel.
  • NANO_ARCH — Machine processor architecture to build. Defaults to output of uname -p.
  • NANO_BOOT0CFG — Controls the options passed to boot0cfg(8); these dictate boot0's behaviour.
  • NANO_BOOTLOADER — The boot0 loader to use relative to the NANO_WORLDDIR variable. This defaults to boot/boot0sio and should be overridden to boot/boot0 to provide a VGA console.
  • CONF_BUILD — Options passed to the buildworld stage of the build.
  • CONF_INSTALL — Options passed to the installworld stage of the build.
  • CONF_WORLD — Options passed to both the buildworld and installworld stages of the build.
  • FlashDevice — Defines the type of media to use. Check the FlashDevice.sub file for more details.

For more configuration options, please check the nanobsd.sh script.

To build NanoBSD image using the nanobsd.conf configuration file, use the following command:

sh nanobsd.sh -c nanobsd.conf

It is possible to fine-tune NanoBSD using shell functions in the configuration file. The following example illustrates the basic model of custom functions:

cust_foo () (
        echo "bar=topless" > \
             ${NANO_WORLDDIR}/etc/foo
)
customize_cmd cust_foo

There are a few pre-defined customization functions ready for use:

  • cust_comconsole — Disables getty(8) on the virtual syscons(4) or vt(4) terminals (/dev/ttyv*) and enables the use of the first serial port as the system console.
  • cust_allow_ssh_root — Allow root to log in via sshd(8).
  • cust_install_files — Installs files from the nanobsd/Files directory, which contains some useful scripts for system administration.
⚠️ heads up: cust_allow_ssh_root does exactly what it says on the tin — root over sshd(8). know what you're doing before you turn it on, k? 🫶

⭐ FILES ⭐

  • src/tools/tools/nanobsd — Base directory of the NanoBSD build script.

💅 EXAMPLES 💅

Making persistent changes to /etc/resolv.conf:

vi /etc/resolv.conf
...
mount /cfg
cp /etc/resolv.conf /cfg
umount /cfg

see? /etc → /cfg → survives reboot. that's the whole trick, iykyk 😌

A more useful example of a customization function is the following, which changes the default size of the /etc directory from 5MB to 30MB:

cust_etc_size () (
        cd ${NANO_WORLDDIR}/conf
        echo 30000 > default/etc/md_size
)
customize_cmd cust_etc_size

👀 SEE ALSO 👀

make.conf(5), boot(8), boot0cfg(8)

🌸 HISTORY 🌸

The nanobsd.sh utility first appeared in FreeBSD 6.0. vintage but still slaying 💜

🫶 AUTHORS 🫶

NanoBSD was developed by Poul-Henning Kamp <phk@FreeBSD.org>. This manual page was written by Daniel Gerzo <danger@FreeBSD.org>.

and that's the page, bestie — brought to you from the Debian corner of the world, dated July 14, 2025, on the NANOBSD(8) page. go build something tiny and invincible 🌈✨💖

📦 where this page comes from