1 .\" Copyright (c) 2006 Daniel Gerzo <danger@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd utility used to create a FreeBSD system image suitable for embedded
37 .Op Fl c Ar config-file
41 utility is a script which produces a minimal implementation of
45 which typically fits on a small media such as a Compact Flash card,
46 or other mass storage medium.
47 It can be used to build specialized install images, designed for easy
48 installation and maintenance.
50 The following options are available:
51 .Bl -tag -width ".Fl c Ar config-file" -offset indent
53 Skip the build stages (both for kernel and world).
54 .It Fl c Ar config-file
55 Specify the configuration file to use.
57 Display usage information.
63 Do not cleanup before each build stage.
64 This suppresses the normal cleanup work done before the
66 stage and adds -DNO_CLEAN to the make command line
67 used for each build stage (world and kernel).
78 .Bl -bullet -offset indent -compact
80 Ports and packages work as in
82 Every single application can be installed and used in a
84 image, the same way as in
87 No missing functionality.
88 If it is possible to do something with
90 it is possible to do the same thing with
92 unless the specific feature or features were explicitly removed from the
94 image when it was created.
96 Everything is read-only at run-time.
97 It is safe to pull the power-plug.
98 There is no necessity to run
100 after a non-graceful shutdown of the system.
102 Easy to build and customize.
103 Making use of just one shell script and one configuration file it is
104 possible to build reduced and customized images satisfying any arbitrary
107 .Ss Nm NanoBSD Ss Media Layout
108 The mass storage medium is divided into three parts by default (which
109 are normally mounted read-only):
111 .Bl -bullet -offset indent -compact
113 Two image partitions:
118 The configuration file partition, which can be mounted under the
120 directory at run time.
129 (malloc backed) disks.
131 The configuration file partition persists under the
134 It contains files for
136 directory and is briefly mounted read-only right after the system boot,
137 therefore it is required to copy modified files from
141 directory if changes are expected to persist after the system restarts.
142 .Sh BUILDING Nm NanoBSD
145 image is built using a simple
147 shell script, which can be
149 .Pa src/tools/tools/nanobsd
151 This script creates a bootable image, which can be copied on the storage
156 The necessary commands to build and install a
159 .Bd -literal -offset indent
160 cd /usr/src/tools/tools/nanobsd
162 cd /usr/obj/nanobsd.full
163 dd if=_.disk.full of=/dev/da0 bs=64k
165 .Sh CUSTOMIZING Nm NanoBSD
166 This is probably the most important and most interesting feature of
168 This is also where you will be spending most of the time when developing with
171 Customization is done in two ways:
173 .Bl -bullet -offset indent -compact
175 Configuration options.
180 With configuration settings, it is possible to configure options passed
187 build process, as well as internal options passed to the main build
190 Through these options it is possible to cut the system down, so it will
191 fit on as little as 64MB.
192 You can use the configuration options to trim down the system
193 even more, until it will consist of just the kernel and two or three
194 files in the userland.
196 The configuration file consists of configuration options, which override
198 The most important directives are:
199 .Bl -tag -width ".Va CONF_INSTALL" -offset indent
201 Build name (used to construct the working directory names).
203 Path to the source tree used to build the image.
205 Name of the kernel configuration file used to build the kernel.
207 Machine processor architecture to build. Defaults to output of
210 Controls the options passed to
215 .It Va NANO_BOOTLOADER
218 loader to use relative to the
223 and should be overridden to
228 Options passed to the
232 Options passed to the
236 Options passed to both the
242 Defines the type of media to use.
245 file for more details.
248 For more configuration options, please check the
256 configuration file, use the following command:
257 .Bd -literal -offset indent
258 sh nanobsd.sh -c nanobsd.conf
261 It is possible to fine-tune
263 using shell functions in the configuration file.
264 The following example illustrates the basic model of custom functions:
265 .Bd -literal -offset indent
267 echo "bar=topless" > \\
268 ${NANO_WORLDDIR}/etc/foo
270 customize_cmd cust_foo
273 There 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
282 and enables the use of the first serial port as the system
284 .It Cm cust_allow_ssh_root
285 Allow root to log in via
287 .It Cm cust_install_files
288 Installs files from the
290 directory, which contains some useful scripts for system administration.
293 .Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
294 .It Pa src/tools/tools/nanobsd
295 Base directory of the
300 Making persistent changes to
301 .Pa /etc/resolv.conf :
302 .Bd -literal -offset indent
306 cp /etc/resolv.conf /cfg
310 A more useful example of a customization function is the following,
311 which changes the default size of the
313 directory from 5MB to 30MB:
314 .Bd -literal -offset indent
316 cd ${NANO_WORLDDIR}/conf
317 echo 30000 > default/etc/md_size
319 customize_cmd cust_etc_size
329 utility first appeared in
335 .An Poul-Henning Kamp Aq phk@FreeBSD.org .
336 This manual page was written by
337 .An Daniel Gerzo Aq danger@FreeBSD.org .