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