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. Defaults to output of 223.Cm uname -p . 224.It Va NANO_BOOT0CFG 225Controls the options passed to 226.Xr boot0cfg 8 ; 227these dictate 228.Nm boot0 Ns 's 229behaviour. 230.It Va NANO_BOOTLOADER 231The 232.Nm boot0 233loader to use relative to the 234.Va NANO_WORLDDIR 235variable. 236This defaults to 237.Pa boot/boot0sio 238and should be overridden to 239.Pa boot/boot0 240to provide a VGA 241console. 242.It Va CONF_BUILD 243Options passed to the 244.Cm buildworld 245stage of the build. 246.It Va CONF_INSTALL 247Options passed to the 248.Cm installworld 249stage of the build. 250.It Va CONF_WORLD 251Options passed to both the 252.Cm buildworld 253and 254.Cm installworld 255stages of the build. 256.It Va FlashDevice 257Defines the type of media to use. 258Check the 259.Pa FlashDevice.sub 260file for more details. 261.El 262.Pp 263For more configuration options, please check the 264.Nm 265script. 266.Pp 267To build 268.Nm NanoBSD 269image using the 270.Pa nanobsd.conf 271configuration file, use the following command: 272.Bd -literal -offset indent 273sh nanobsd.sh -c nanobsd.conf 274.Ed 275.Pp 276It is possible to fine-tune 277.Nm NanoBSD 278using shell functions in the configuration file. 279The following example illustrates the basic model of custom functions: 280.Bd -literal -offset indent 281cust_foo () ( 282 echo "bar=topless" > \\ 283 ${NANO_WORLDDIR}/etc/foo 284) 285customize_cmd cust_foo 286.Ed 287.Pp 288There are a few pre-defined customization functions ready for use: 289.Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent 290.It Cm cust_comconsole 291Disables 292.Xr getty 8 293on the virtual 294.Xr syscons 4 295or 296.Xr vt 4 297terminals 298.Pq Pa /dev/ttyv* 299and enables the use of the first serial port as the system 300console. 301.It Cm cust_allow_ssh_root 302Allow root to log in via 303.Xr sshd 8 . 304.It Cm cust_install_files 305Installs files from the 306.Pa nanobsd/Files 307directory, which contains some useful scripts for system administration. 308.El 309.Sh FILES 310.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact 311.It Pa src/tools/tools/nanobsd 312Base directory of the 313.Nm NanoBSD 314build script. 315.El 316.Sh EXAMPLES 317Making persistent changes to 318.Pa /etc/resolv.conf : 319.Bd -literal -offset indent 320vi /etc/resolv.conf 321\&... 322mount /cfg 323cp /etc/resolv.conf /cfg 324umount /cfg 325.Ed 326.Pp 327A more useful example of a customization function is the following, 328which changes the default size of the 329.Pa /etc 330directory from 5MB to 30MB: 331.Bd -literal -offset indent 332cust_etc_size () ( 333 cd ${NANO_WORLDDIR}/conf 334 echo 30000 > default/etc/md_size 335) 336customize_cmd cust_etc_size 337.Ed 338.Sh SEE ALSO 339.Xr make.conf 5 , 340.Xr boot 8 , 341.Xr boot0cfg 8 , 342.Xr picobsd 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