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