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