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 September 9, 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 BbfhIiKknpqvWwX 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 an SD 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 p 81Don't prepare the image. 82Skip running of the customization and early customization scripts for 83incremental image refinement from world, kernel, or packages. 84.It Fl q 85Make output more quiet. 86.It Fl v 87Make output more verbose. 88.It Fl W 89Skip the 90.Cm installworld 91stage of the build. 92.It Fl w 93Skip the 94.Cm buildworld 95stage of the build. 96.It Fl X 97Make 98.Cm native-xtools . 99.El 100.Pp 101The features of 102.Nm NanoBSD 103include: 104.Pp 105.Bl -bullet -offset indent -compact 106.It 107Ports and packages work as in 108.Fx . 109Every single application can be installed and used in a 110.Nm NanoBSD 111image, the same way as in 112.Fx . 113.It 114No missing functionality. 115If it is possible to do something with 116.Fx , 117it is possible to do the same thing with 118.Nm NanoBSD , 119unless the specific feature or features were explicitly removed from the 120.Nm NanoBSD 121image when it was created. 122.It 123Everything is read-only at run-time. 124It is safe to pull the power-plug. 125There is no necessity to run 126.Xr fsck 8 127after a non-graceful shutdown of the system. 128.It 129Easy to build and customize. 130Making use of just one shell script and one configuration file it is 131possible to build reduced and customized images satisfying any arbitrary 132set of requirements. 133.El 134.Ss NanoBSD Media Layout 135The mass storage medium is divided into three parts by default (which 136are normally mounted read-only): 137.Pp 138.Bl -bullet -offset indent -compact 139.It 140Two image partitions: 141.Li code#1 142and 143.Li code#2 . 144.It 145The configuration file partition, which can be mounted under the 146.Pa /cfg 147directory at run time. 148.El 149.Pp 150The 151.Pa /etc 152and 153.Pa /var 154directories are 155.Xr md 4 156(malloc backed) disks. 157.Pp 158The configuration file partition persists under the 159.Pa /cfg 160directory. 161It contains files for 162.Pa /etc 163directory and is briefly mounted read-only right after the system boot, 164therefore it is required to copy modified files from 165.Pa /etc 166back to the 167.Pa /cfg 168directory if changes are expected to persist after the system restarts. 169.Sh BUILDING Nm NanoBSD 170A 171.Nm NanoBSD 172image is built using a simple 173.Nm 174shell script, which can be 175found in the 176.Pa src/tools/tools/nanobsd 177directory. 178This script creates a bootable image, which can be copied on the storage 179medium using the 180.Xr dd 1 181utility. 182.Pp 183The necessary commands to build and install a 184.Nm NanoBSD 185image are: 186.Bd -literal -offset indent 187cd /usr/src/tools/tools/nanobsd 188sh nanobsd.sh 189cd /usr/obj/nanobsd.full 190dd if=_.disk.full of=/dev/da0 bs=64k 191.Ed 192.Sh CUSTOMIZING Nm NanoBSD 193This is probably the most important and most interesting feature of 194.Nm NanoBSD . 195This is also where you will be spending most of the time when developing with 196.Nm NanoBSD . 197.Pp 198Customization is done in two ways: 199.Pp 200.Bl -bullet -offset indent -compact 201.It 202Configuration options. 203.It 204Custom functions. 205.El 206.Pp 207With configuration settings, it is possible to configure options passed 208to both the 209.Cm buildworld 210and 211.Cm installworld 212stages of the 213.Nm NanoBSD 214build process, as well as internal options passed to the main build 215process of 216.Nm NanoBSD . 217Through these options it is possible to cut the system down, so it will 218fit on as little as 64MB. 219You can use the configuration options to trim down the system 220even more, until it will consist of just the kernel and two or three 221files in the userland. 222.Pp 223The configuration file consists of configuration options, which override 224the default values. 225The most important directives are: 226.Bl -tag -width ".Va CONF_INSTALL" -offset indent 227.It Va NANO_NAME 228Build name (used to construct the working directory names). 229.It Va NANO_SRC 230Path to the source tree used to build the image. 231.It Va NANO_KERNEL 232Name of the kernel configuration file used to build the kernel. 233.It Va NANO_ARCH 234Machine processor architecture to build. 235Defaults to output of 236.Cm uname -p . 237.It Va NANO_BOOT0CFG 238Controls the options passed to 239.Xr boot0cfg 8 ; 240these dictate 241.Nm boot0 Ns 's 242behaviour. 243.It Va NANO_BOOTLOADER 244The 245.Nm boot0 246loader to use relative to the 247.Va NANO_WORLDDIR 248variable. 249This defaults to 250.Pa boot/boot0sio 251and should be overridden to 252.Pa boot/boot0 253to provide a VGA 254console. 255.It Va CONF_BUILD 256Options passed to the 257.Cm buildworld 258stage of the build. 259.It Va CONF_INSTALL 260Options passed to the 261.Cm installworld 262stage of the build. 263.It Va CONF_WORLD 264Options passed to both the 265.Cm buildworld 266and 267.Cm installworld 268stages of the build. 269.It Va FlashDevice 270Defines the type of media to use. 271Check the 272.Pa FlashDevice.sub 273file for more details. 274.El 275.Pp 276For more configuration options, please check the 277.Nm 278script. 279.Pp 280To build 281.Nm NanoBSD 282image using the 283.Pa nanobsd.conf 284configuration file, use the following command: 285.Bd -literal -offset indent 286sh nanobsd.sh -c nanobsd.conf 287.Ed 288.Pp 289It is possible to fine-tune 290.Nm NanoBSD 291using shell functions in the configuration file. 292The following example illustrates the basic model of custom functions: 293.Bd -literal -offset indent 294cust_foo () ( 295 echo "bar=topless" > \\ 296 ${NANO_WORLDDIR}/etc/foo 297) 298customize_cmd cust_foo 299.Ed 300.Pp 301There are a few pre-defined customization functions ready for use: 302.Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent 303.It Cm cust_comconsole 304Disables 305.Xr getty 8 306on the virtual 307.Xr syscons 4 308or 309.Xr vt 4 310terminals 311.Pq Pa /dev/ttyv* 312and enables the use of the first serial port as the system 313console. 314.It Cm cust_allow_ssh_root 315Allow root to log in via 316.Xr sshd 8 . 317.It Cm cust_install_files 318Installs files from the 319.Pa nanobsd/Files 320directory, which contains some useful scripts for system administration. 321.El 322.Sh FILES 323.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact 324.It Pa src/tools/tools/nanobsd 325Base directory of the 326.Nm NanoBSD 327build script. 328.El 329.Sh EXAMPLES 330Making persistent changes to 331.Pa /etc/resolv.conf : 332.Bd -literal -offset indent 333vi /etc/resolv.conf 334\&... 335mount /cfg 336cp /etc/resolv.conf /cfg 337umount /cfg 338.Ed 339.Pp 340A more useful example of a customization function is the following, 341which changes the default size of the 342.Pa /etc 343directory from 5MB to 30MB: 344.Bd -literal -offset indent 345cust_etc_size () ( 346 cd ${NANO_WORLDDIR}/conf 347 echo 30000 > default/etc/md_size 348) 349customize_cmd cust_etc_size 350.Ed 351.Sh SEE ALSO 352.Xr make.conf 5 , 353.Xr boot 8 , 354.Xr boot0cfg 8 355.Sh HISTORY 356The 357.Nm 358utility first appeared in 359.Fx 6.0 . 360.Sh AUTHORS 361.An -nosplit 362.Nm NanoBSD 363was developed by 364.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . 365This manual page was written by 366.An Daniel Gerzo Aq Mt danger@FreeBSD.org . 367