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
30 .Nd utility used to create a FreeBSD system image suitable for embedded
35 .Op Fl c Ar config-file
39 utility is a script which produces a minimal implementation of
43 which typically fits on a small media such as a Compact Flash card,
44 or other mass storage medium.
45 It can be used to build specialized install images, designed for easy
46 installation and maintenance.
48 The following options are available:
49 .Bl -tag -width ".Fl c Ar config-file" -offset indent
51 Skip the build stages (both for kernel and world).
52 .It Fl c Ar config-file
53 Specify the configuration file to use.
55 Skip the code slice extraction.
57 Display usage information.
59 Skip the disk image build stage.
69 Do not cleanup before each build stage.
70 This suppresses the normal cleanup work done before the
72 stage and adds -DNO_CLEAN to the make command line
73 used for each build stage (world and kernel).
75 Make output more quiet.
77 Make output more verbose.
91 .Bl -bullet -offset indent -compact
93 Ports and packages work as in
95 Every single application can be installed and used in a
97 image, the same way as in
100 No missing functionality.
101 If it is possible to do something with
103 it is possible to do the same thing with
105 unless the specific feature or features were explicitly removed from the
107 image when it was created.
109 Everything is read-only at run-time.
110 It is safe to pull the power-plug.
111 There is no necessity to run
113 after a non-graceful shutdown of the system.
115 Easy to build and customize.
116 Making use of just one shell script and one configuration file it is
117 possible to build reduced and customized images satisfying any arbitrary
120 .Ss NanoBSD Media Layout
121 The mass storage medium is divided into three parts by default (which
122 are normally mounted read-only):
124 .Bl -bullet -offset indent -compact
126 Two image partitions:
131 The configuration file partition, which can be mounted under the
133 directory at run time.
142 (malloc backed) disks.
144 The configuration file partition persists under the
147 It contains files for
149 directory and is briefly mounted read-only right after the system boot,
150 therefore it is required to copy modified files from
154 directory if changes are expected to persist after the system restarts.
155 .Sh BUILDING Nm NanoBSD
158 image is built using a simple
160 shell script, which can be
162 .Pa src/tools/tools/nanobsd
164 This script creates a bootable image, which can be copied on the storage
169 The necessary commands to build and install a
172 .Bd -literal -offset indent
173 cd /usr/src/tools/tools/nanobsd
175 cd /usr/obj/nanobsd.full
176 dd if=_.disk.full of=/dev/da0 bs=64k
178 .Sh CUSTOMIZING Nm NanoBSD
179 This is probably the most important and most interesting feature of
181 This is also where you will be spending most of the time when developing with
184 Customization is done in two ways:
186 .Bl -bullet -offset indent -compact
188 Configuration options.
193 With configuration settings, it is possible to configure options passed
200 build process, as well as internal options passed to the main build
203 Through these options it is possible to cut the system down, so it will
204 fit on as little as 64MB.
205 You can use the configuration options to trim down the system
206 even more, until it will consist of just the kernel and two or three
207 files in the userland.
209 The configuration file consists of configuration options, which override
211 The most important directives are:
212 .Bl -tag -width ".Va CONF_INSTALL" -offset indent
214 Build name (used to construct the working directory names).
216 Path to the source tree used to build the image.
218 Name of the kernel configuration file used to build the kernel.
220 Machine processor architecture to build.
221 Defaults to output of
224 Controls the options passed to
229 .It Va NANO_BOOTLOADER
232 loader to use relative to the
237 and should be overridden to
242 Options passed to the
246 Options passed to the
250 Options passed to both the
256 Defines the type of media to use.
259 file for more details.
262 For more configuration options, please check the
270 configuration file, use the following command:
271 .Bd -literal -offset indent
272 sh nanobsd.sh -c nanobsd.conf
275 It is possible to fine-tune
277 using shell functions in the configuration file.
278 The following example illustrates the basic model of custom functions:
279 .Bd -literal -offset indent
281 echo "bar=topless" > \\
282 ${NANO_WORLDDIR}/etc/foo
284 customize_cmd cust_foo
287 There are a few pre-defined customization functions ready for use:
288 .Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent
289 .It Cm cust_comconsole
298 and enables the use of the first serial port as the system
300 .It Cm cust_allow_ssh_root
301 Allow root to log in via
303 .It Cm cust_install_files
304 Installs files from the
306 directory, which contains some useful scripts for system administration.
309 .Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
310 .It Pa src/tools/tools/nanobsd
311 Base directory of the
316 Making persistent changes to
317 .Pa /etc/resolv.conf :
318 .Bd -literal -offset indent
322 cp /etc/resolv.conf /cfg
326 A more useful example of a customization function is the following,
327 which changes the default size of the
329 directory from 5MB to 30MB:
330 .Bd -literal -offset indent
332 cd ${NANO_WORLDDIR}/conf
333 echo 30000 > default/etc/md_size
335 customize_cmd cust_etc_size
344 utility first appeared in
350 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
351 This manual page was written by
352 .An Daniel Gerzo Aq Mt danger@FreeBSD.org .