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