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