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