NanoBSD
Historical reference
BSDRP no longer uses NanoBSD. Images are built with the poudriere image feature. This page is kept for historical context and for anyone studying older BSDRP releases or other NanoBSD-based projects.
External links about NanoBSD¶
Documentation and tutorials about NanoBSD:
- Introduction to NanoBSD: official presentation page on the FreeBSD website
- Building a FreeBSD Appliance With NanoBSD (PDF): presentation given at BSDCan 2006
- NanoBSD man page: the man page
- Gitoyen NanoBSD quagga router (French only): one of the closest projects to this one, with the clever idea of managing configuration on an external SVN server, and (most interesting) a patch that adds ports-compilation support
Understanding NanoBSD¶
What is NanoBSD?¶
It is a shell script (/usr/src/tools/tools/nanobsd/) that generates embedded FreeBSD disk images.
Images generated by NanoBSD¶
After running NanoBSD, you will find a full disk image (_.disk.full) that contains two partitions (p1 and p2), both copies of _.disk.image. The file _.disk.image is the slimmed-down FreeBSD filesystem (running in diskless mode). Using two partitions allows a simple and safe upgrade process: the new _.disk.image is written to the inactive partition, and the bootloader is updated to boot from it at the next reboot. The updatep1 and updatep2 scripts handle this.
Using NanoBSD¶
NanoBSD manages a flash device and avoids fsck by mounting the filesystem read-only. To save configuration files, you need to copy /etc into /conf; the save_cfg script does this.
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.
Steps¶
The build is structured as the following functions, run in order:
- clean_build
- make_conf_build
- build_world
- build_kernel
- clean_world
- make_conf_install
- install_world
- install_etc
- setup_nanobsd_etc
- install_kernel
- run_customize
- setup_nanobsd
- prune_usr
- run_late_customize
- create_\${NANO_ARCH}_diskimage
- last_orders
Variables table¶
FIXME
| 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 | 0 | 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_MAKE_CONF_BUILD | /usr/obj/nanobsd.BSDRP.{ARCH}/make.conf.build | |
| 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¶
FIXME
| 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 log files¶
| Name | Description |
|---|---|
| _.bk | Build Kernel log |
| _.bw | 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¶
Port compilation patches¶
This patch is an improvement on the method used by the Gitoyen NanoBSD router.
Instead of installing pre-built packages, it compiles ports as part of the NanoBSD image build, which allows ports to be added during image generation.
The patch supports cross-compiling i386 ports from an amd64 release.
You can find this patch as the add_port () function in the BSDRP NanoBSD configuration file.
The better solution today is to use poudriere to generate packages.