1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2006 Daniel Gerzo <danger@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd July 14, 2025 29.Dt NANOBSD 8 30.Os 31.Sh NAME 32.Nm nanobsd.sh 33.Nd create an embedded FreeBSD system image 34.Sh SYNOPSIS 35.Nm 36.Op Fl BbfhIiKknqvWwX 37.Op Fl c Ar config-file 38.Sh DESCRIPTION 39The 40.Nm 41utility is a script which produces a minimal implementation of 42.Fx 43(called 44.Nm NanoBSD ) , 45which typically fits on a small media such as a Compact Flash card, 46or other mass storage medium. 47It can be used to build specialized install images, designed for easy 48installation and maintenance. 49.Pp 50The following options are available: 51.Bl -tag -width ".Fl c Ar config-file" -offset indent 52.It Fl B 53Skip the install stages (both for kernel and world). 54.It Fl b 55Skip the build stages (both for kernel and world). 56.It Fl c Ar config-file 57Specify the configuration file to use. 58.It Fl f 59Skip the code slice extraction. 60.It Fl h 61Display usage information. 62.It Fl I 63Build the disk image from an existing build/install. 64.It Fl i 65Skip the disk image build stage. 66.It Fl K 67Skip the 68.Cm installkernel 69stage of the build. 70.It Fl k 71Skip the 72.Cm buildkernel 73stage of the build. 74.It Fl n 75Do not cleanup before each build stage. 76This suppresses the normal cleanup work done before the 77.Cm buildworld 78stage and adds -DNO_CLEAN to the make command line 79used for each build stage (world and kernel). 80.It Fl q 81Make output more quiet. 82.It Fl v 83Make output more verbose. 84.It Fl W 85Skip the 86.Cm installworld 87stage of the build. 88.It Fl w 89Skip the 90.Cm buildworld 91stage of the build. 92.It Fl X 93Make 94.Cm native-xtools . 95.El 96.Pp 97The features of 98.Nm NanoBSD 99include: 100.Pp 101.Bl -bullet -offset indent -compact 102.It 103Ports and packages work as in 104.Fx . 105Every single application can be installed and used in a 106.Nm NanoBSD 107image, the same way as in 108.Fx . 109.It 110No missing functionality. 111If it is possible to do something with 112.Fx , 113it is possible to do the same thing with 114.Nm NanoBSD , 115unless the specific feature or features were explicitly removed from the 116.Nm NanoBSD 117image when it was created. 118.It 119Everything is read-only at run-time. 120It is safe to pull the power-plug. 121There is no necessity to run 122.Xr fsck 8 123after a non-graceful shutdown of the system. 124.It 125Easy to build and customize. 126Making use of just one shell script and one configuration file it is 127possible to build reduced and customized images satisfying any arbitrary 128set of requirements. 129.El 130.Ss NanoBSD Media Layout 131The mass storage medium is divided into three parts by default (which 132are normally mounted read-only): 133.Pp 134.Bl -bullet -offset indent -compact 135.It 136Two image partitions: 137.Li code#1 138and 139.Li code#2 . 140.It 141The configuration file partition, which can be mounted under the 142.Pa /cfg 143directory at run time. 144.El 145.Pp 146The 147.Pa /etc 148and 149.Pa /var 150directories are 151.Xr md 4 152(malloc backed) disks. 153.Pp 154The configuration file partition persists under the 155.Pa /cfg 156directory. 157It contains files for 158.Pa /etc 159directory and is briefly mounted read-only right after the system boot, 160therefore it is required to copy modified files from 161.Pa /etc 162back to the 163.Pa /cfg 164directory if changes are expected to persist after the system restarts. 165.Sh BUILDING Nm NanoBSD 166A 167.Nm NanoBSD 168image is built using a simple 169.Nm 170shell script, which can be 171found in the 172.Pa src/tools/tools/nanobsd 173directory. 174This script creates a bootable image, which can be copied on the storage 175medium using the 176.Xr dd 1 177utility. 178.Pp 179The necessary commands to build and install a 180.Nm NanoBSD 181image are: 182.Bd -literal -offset indent 183cd /usr/src/tools/tools/nanobsd 184sh nanobsd.sh 185cd /usr/obj/nanobsd.full 186dd if=_.disk.full of=/dev/da0 bs=64k 187.Ed 188.Sh CUSTOMIZING Nm NanoBSD 189This is probably the most important and most interesting feature of 190.Nm NanoBSD . 191This is also where you will be spending most of the time when developing with 192.Nm NanoBSD . 193.Pp 194Customization is done in two ways: 195.Pp 196.Bl -bullet -offset indent -compact 197.It 198Configuration options. 199.It 200Custom functions. 201.El 202.Pp 203With configuration settings, it is possible to configure options passed 204to both the 205.Cm buildworld 206and 207.Cm installworld 208stages of the 209.Nm NanoBSD 210build process, as well as internal options passed to the main build 211process of 212.Nm NanoBSD . 213Through these options it is possible to cut the system down, so it will 214fit on as little as 64MB. 215You can use the configuration options to trim down the system 216even more, until it will consist of just the kernel and two or three 217files in the userland. 218.Pp 219The configuration file consists of configuration options, which override 220the default values. 221The most important directives are: 222.Bl -tag -width ".Va CONF_INSTALL" -offset indent 223.It Va NANO_NAME 224Build name (used to construct the working directory names). 225.It Va NANO_SRC 226Path to the source tree used to build the image. 227.It Va NANO_KERNEL 228Name of the kernel configuration file used to build the kernel. 229.It Va NANO_ARCH 230Machine processor architecture to build. 231Defaults to output of 232.Cm uname -p . 233.It Va NANO_BOOT0CFG 234Controls the options passed to 235.Xr boot0cfg 8 ; 236these dictate 237.Nm boot0 Ns 's 238behaviour. 239.It Va NANO_BOOTLOADER 240The 241.Nm boot0 242loader to use relative to the 243.Va NANO_WORLDDIR 244variable. 245This defaults to 246.Pa boot/boot0sio 247and should be overridden to 248.Pa boot/boot0 249to provide a VGA 250console. 251.It Va CONF_BUILD 252Options passed to the 253.Cm buildworld 254stage of the build. 255.It Va CONF_INSTALL 256Options passed to the 257.Cm installworld 258stage of the build. 259.It Va CONF_WORLD 260Options passed to both the 261.Cm buildworld 262and 263.Cm installworld 264stages of the build. 265.It Va FlashDevice 266Defines the type of media to use. 267Check the 268.Pa FlashDevice.sub 269file for more details. 270.El 271.Pp 272For more configuration options, please check the 273.Nm 274script. 275.Pp 276To build 277.Nm NanoBSD 278image using the 279.Pa nanobsd.conf 280configuration file, use the following command: 281.Bd -literal -offset indent 282sh nanobsd.sh -c nanobsd.conf 283.Ed 284.Pp 285It is possible to fine-tune 286.Nm NanoBSD 287using shell functions in the configuration file. 288The following example illustrates the basic model of custom functions: 289.Bd -literal -offset indent 290cust_foo () ( 291 echo "bar=topless" > \\ 292 ${NANO_WORLDDIR}/etc/foo 293) 294customize_cmd cust_foo 295.Ed 296.Pp 297There are a few pre-defined customization functions ready for use: 298.Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent 299.It Cm cust_comconsole 300Disables 301.Xr getty 8 302on the virtual 303.Xr syscons 4 304or 305.Xr vt 4 306terminals 307.Pq Pa /dev/ttyv* 308and enables the use of the first serial port as the system 309console. 310.It Cm cust_allow_ssh_root 311Allow root to log in via 312.Xr sshd 8 . 313.It Cm cust_install_files 314Installs files from the 315.Pa nanobsd/Files 316directory, which contains some useful scripts for system administration. 317.El 318.Sh FILES 319.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact 320.It Pa src/tools/tools/nanobsd 321Base directory of the 322.Nm NanoBSD 323build script. 324.El 325.Sh EXAMPLES 326Making persistent changes to 327.Pa /etc/resolv.conf : 328.Bd -literal -offset indent 329vi /etc/resolv.conf 330\&... 331mount /cfg 332cp /etc/resolv.conf /cfg 333umount /cfg 334.Ed 335.Pp 336A more useful example of a customization function is the following, 337which changes the default size of the 338.Pa /etc 339directory from 5MB to 30MB: 340.Bd -literal -offset indent 341cust_etc_size () ( 342 cd ${NANO_WORLDDIR}/conf 343 echo 30000 > default/etc/md_size 344) 345customize_cmd cust_etc_size 346.Ed 347.Sh SEE ALSO 348.Xr make.conf 5 , 349.Xr boot 8 , 350.Xr boot0cfg 8 351.Sh HISTORY 352The 353.Nm 354utility first appeared in 355.Fx 6.0 . 356.Sh AUTHORS 357.An -nosplit 358.Nm NanoBSD 359was developed by 360.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . 361This manual page was written by 362.An Daniel Gerzo Aq Mt danger@FreeBSD.org . 363