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