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