User Tools

Site Tools



Unofficial NanoBSD technical resources

Externals links about NanoBSD

Here are a list of docs and tutorials about NanoBSD:

Understanding NanoBSD

What is NanoBSD ?

It's a shell script (/usr/src/tools/tools/nanobsd/) that generate embedded FreeBSD image disk.

Images generated by NanoBSD

After using NanoBSD, you will found a full disk image (_.disk.full) that contains 2 partitions (p1 and p2) (both copy of _.disk.image file). The file _.disk.image is the light FreeBSD filesystem (in diskless mode). Using 2 partitions permit to use a simple and safe upgrading process: The new _.disk.image file is copied over the non-active partition, and the bootloader is modified for boot on the non-active partition at the next boot. There are the scripts updatep1 and updatep2 for this task.

Using NanoBSD

NanoBSD manage flash device and prevent fsck by mounting the filesystem read-only. For saving configuration file, you need to copy /etc into /conf: There is the script save_cfg for this task.

Studying NanoBSD

Command options

Here are the command line options of NanoBSD:

Usage: $0 [-bikqvw] [-c config_file]
  -b      suppress builds (both kernel and world)
  -i      suppress disk image build
  -k      suppress buildkernel
  -n      add -DNO_CLEAN to buildworld, buildkernel, etc
  -q      make output more quite
  -v      make output more verbose
  -w      suppress buildworld
  -c      specify config file
  -h      Display usage information.


Here are the functions steps:

  1. clean_build
  2. make_conf_build
  3. build_world
  4. build_kernel
  5. clean_world
  6. make_conf_install
  7. install_world
  8. install_etc
  9. setup_nanobsd_etc
  10. install_kernel
  11. run_customize
  12. setup_nanobsd
  13. prune_usr
  14. run_late_customize
  15. create_${NANO_ARCH}_diskimage
  16. last_orders

Variables Table


Name Value (in BSDRP) Description
CONF_BUILD Options to put in make.conf during buildworld only
CONF_WORLD A big list of WITHOUT_ Options to put in make.conf during both build- & installworld
CONF_INSTALL A big list of WITHOUT_ too Options to put in make.conf during installworld only
MAKEOBJDIRPREFIX /usr/obj/nanobsd.BSDRP.{ARCH} object directory
NANO_ARCH i386/amd Target architecture
NANO_BOOT0CFG -o packet -s 1 -m 3 Boot0cfg configuration mode
NANO_CONFSIZE 2048 Size of configuration file system in 512 bytes sectors
NANO_CUSTOMIZE Customize commands
NANO_DATASIZE 2048 Size of data file system in 512 bytes sectors
NANO_DISKIMGDIR /usr/obj/nanobsd.BSDRP.{ARCH} The directory to put the final images
NANO_DRIVE ad0 (TO ADD in BSDRP make!) The drive name of the media at runtime
NANO_GLABEL_SYS BSDRP glabel name for system partition
NANO_GLABEL_CFG cfg glabel name for configuration partition
NANO_GLABEL_DATA data glabel name for data partition
NANO_IMAGES 2 Number of code images on media (1 or 2)
NANO_IMGNAME BSDRP.img The default name for any image we create
NANO_INIT_IMG2 What to do with the second image partition: 0 (empty), 1 (copy twice the image)
NANO_KERNEL BSDRP-I386 / BSDRP-AMD64 Name of the kernel config file
NANO_LATE_CUSTOMIZE Late customize commands
NANO_MAKE_CONF_INSTALL /usr/obj/nanobsd.BSDRP.{ARCH}/make.conf.install
NANO_MD_BACKING file Backing type of md(4) device (file or swap)
NANO_MEDIASIZE 1200000 Target media size in 512 bytes sectors
NANO_NAME BSDRP Name of the obj dir
NANO_NEWFS -b 4096 -f 512 -i 8192 -O1 -m 2 -U Newfs paramters to use
NANO_OBJ /usr/obj/nanobsd.BSDRP.{ARCH} Object tree directory
NANO_PACKAGE_DIR /usr/src/tools/tools/nanobsd/BSDRP/Pkg Where cust_pkg() finds packages to install
NANO_PMAKE make -j 3 Parallel Make
NANO_RAM_ETCSIZE 10204 Size of the /etc ramdisk in 512 bytes sectors
NANO_RAM_TMPVARSIZE 20480 Size of the /tmp+/var ramdisk in 512 bytes sectors
NANO_SRC /usr/src Source tree directory
NANO_TOOLS tools/tools/nanobsd/BSDRP Where nanobsd additional files live under the source tree
NANO_WORLDDIR /usr/obj/nanobsd.BSDRP.{ARCH}/_.w Target World directory

Functions Table


Name Description
build_kernel Copy kernel config file and Build Kernel
build_world Run Build World
clean_build Delete and create object directory
clean_world Clean and create object directory
cust_install_files Copy all files under Files to nanobsd target
FlashDevice Load FlashDevice.sub
install_world Install all binary (make installworld)
install_etc Install /etc (make distribution
install_kernel Install kernel (make installkernel)
make_conf_build Construct build make.conf using $CONF_WORLD and $CONF_BUILD
make_conf_install Construct install make.conf using $CONF_WORLD and $CONF_BUILD
prune_usr Remove all empty directories in target /usr
run_customize run customize scripts (commands in $NANO_CUSTOMIZE)
run_late_customize run late customize scripts (commands in $NANO_LATE_CUSTOMIZE and cust_ functions)
setup_nanobsd configure nanobsd setup: Move /usr/local/etc to /etc/local
setup_nanobsd_etc configure target nanobsd /etc: enable diskless, enable r/o of /, create fstab
UsbDevice USB device geometries
create_${NANO_ARCH}_diskimage Build disk image (partition, format, bootloader, etc.)
last_orders Empty function to be customized by user (ex: copy diskimage to other place)

NanoBSD logs files

Name Description
_.bk Build Kernel log Build World log
_.di Disk image creation log
_.dl nanobsd setup creation log (/etc, /conf, etc..)
_.du nanobsd disk usage (du) output
_.env All environnement used during nanobsd runs
_.etc Install etc log
_.fdisk File used for fdisk the nanoBSD image
_.ik Install kernel log files
_.iw Install world log files
_.mtree Light mtree file of the nanoBSD image

BSDRP patches for NanoBSD

All this patchs were wrote for NanoBSD included in FreeBSD 8.1-Release.

AMD64 support

This very small patch permit to generate NanoBSD amd64 image.

This patch was proposed to be added into the official NanoBSD the Mon, 15 Jun 2009 05:51:53 GMT and was included in FreeBSD 8.1.

Label support: No more hardcoded ad0/da0 for root filesystem

The image of NanoBSD hardcode the device type use for mounting the root filesystem:

  • ad0 for the first ATA device
  • da0 for the first SCSI device (used for USB key)

This mean, that a “ad0-nanobsd” image can't be installed on a USB key: It will not correctly boot (because the fstab will indicate the root filesystem on the ad0 drive, but when booting from a USB key, it's on da0).

The pfSense team meet the same problem, and Scott Ullrich give me this big advice: Use label in your fstab for avoiding this problem!

Then, here is the patch, and the new update script (merged updatep1 and updatep2 nanoBSD script):

This patch was proposed to be added into NanoBSD on the FreeBSD-embedded mailing-list the Sun Jul 5 22:12:38 UTC 2009, and a modified version is committed in -current.

Port compiling patches

This patches is an improvement of the method used by Gitoyen NanoBSD router.

It replaces the installation of package by compiling ports during NanoBSD image build: This permit to add ports during build process of NanoBSD images.

This patch support cross-compilation i386 ports from an amd64 release.

You can found this patches as the function add_port () in the BSDRP nano configuration file.

Improving mtree generation

NanoBSD generate a mtree reference file, but for system security audit the default nanoBSD mtree file didn't contain enough parameters

This patch add sha256digest to mtree function of nanoBSD:


sparc64 support (work in progress)

This patch is to be used with the nanobsd glabel patch:


Cross-compilation of port is not possible: This patch is usable from a sparc64 computer only.

Upgrading nanoBSD image is not supported: There is no FreeBSD bootloader available on sparc64 (the Sun OBP permit to select the partition from where to boot).

Actual State: Commenting net/bird and net/openlldp permit to build the sparc64 BSDRP image, but the resulting image don't accept to login (Generate a “__sparc_utrap: fatal illegal instruction”).

arm support (work in progress)

This patch, prensently didn't fully works because I didn't found a solution for cross-compil arm ports from an i386/amd64 FreeBSD.

But it should work from an arm FreeBSD (not tested, I didn't have arm computer)

This patch permit to generate NanoBSD arm image: It's came from the nanobsd/gateworks exemples.


documentation/technical_docs/nanobsd.txt · Last modified: 2011/12/27 14:37 (external edit)