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 Skip the code slice extraction.
59 Display usage information.
61 Skip the disk image build stage.
71 Do not cleanup before each build stage.
72 This suppresses the normal cleanup work done before the
74 stage and adds -DNO_CLEAN to the make command line
75 used for each build stage (world and kernel).
77 Make output more quiet.
79 Make output more verbose.
93 .Bl -bullet -offset indent -compact
95 Ports and packages work as in
97 Every single application can be installed and used in a
99 image, the same way as in
102 No missing functionality.
103 If it is possible to do something with
105 it is possible to do the same thing with
107 unless the specific feature or features were explicitly removed from the
109 image when it was created.
111 Everything is read-only at run-time.
112 It is safe to pull the power-plug.
113 There is no necessity to run
115 after a non-graceful shutdown of the system.
117 Easy to build and customize.
118 Making use of just one shell script and one configuration file it is
119 possible to build reduced and customized images satisfying any arbitrary
122 .Ss NanoBSD Media Layout
123 The mass storage medium is divided into three parts by default (which
124 are normally mounted read-only):
126 .Bl -bullet -offset indent -compact
128 Two image partitions:
133 The configuration file partition, which can be mounted under the
135 directory at run time.
144 (malloc backed) disks.
146 The configuration file partition persists under the
149 It contains files for
151 directory and is briefly mounted read-only right after the system boot,
152 therefore it is required to copy modified files from
156 directory if changes are expected to persist after the system restarts.
157 .Sh BUILDING Nm NanoBSD
160 image is built using a simple
162 shell script, which can be
164 .Pa src/tools/tools/nanobsd
166 This script creates a bootable image, which can be copied on the storage
171 The necessary commands to build and install a
174 .Bd -literal -offset indent
175 cd /usr/src/tools/tools/nanobsd
177 cd /usr/obj/nanobsd.full
178 dd if=_.disk.full of=/dev/da0 bs=64k
180 .Sh CUSTOMIZING Nm NanoBSD
181 This is probably the most important and most interesting feature of
183 This is also where you will be spending most of the time when developing with
186 Customization is done in two ways:
188 .Bl -bullet -offset indent -compact
190 Configuration options.
195 With configuration settings, it is possible to configure options passed
202 build process, as well as internal options passed to the main build
205 Through these options it is possible to cut the system down, so it will
206 fit on as little as 64MB.
207 You can use the configuration options to trim down the system
208 even more, until it will consist of just the kernel and two or three
209 files in the userland.
211 The configuration file consists of configuration options, which override
213 The most important directives are:
214 .Bl -tag -width ".Va CONF_INSTALL" -offset indent
216 Build name (used to construct the working directory names).
218 Path to the source tree used to build the image.
220 Name of the kernel configuration file used to build the kernel.
222 Machine processor architecture to build.
223 Defaults to output of
226 Controls the options passed to
231 .It Va NANO_BOOTLOADER
234 loader to use relative to the
239 and should be overridden to
244 Options passed to the
248 Options passed to the
252 Options passed to both the
258 Defines the type of media to use.
261 file for more details.
264 For more configuration options, please check the
272 configuration file, use the following command:
273 .Bd -literal -offset indent
274 sh nanobsd.sh -c nanobsd.conf
277 It is possible to fine-tune
279 using shell functions in the configuration file.
280 The following example illustrates the basic model of custom functions:
281 .Bd -literal -offset indent
283 echo "bar=topless" > \\
284 ${NANO_WORLDDIR}/etc/foo
286 customize_cmd cust_foo
289 There are a few pre-defined customization functions ready for use:
290 .Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent
291 .It Cm cust_comconsole
300 and enables the use of the first serial port as the system
302 .It Cm cust_allow_ssh_root
303 Allow root to log in via
305 .It Cm cust_install_files
306 Installs files from the
308 directory, which contains some useful scripts for system administration.
311 .Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
312 .It Pa src/tools/tools/nanobsd
313 Base directory of the
318 Making persistent changes to
319 .Pa /etc/resolv.conf :
320 .Bd -literal -offset indent
324 cp /etc/resolv.conf /cfg
328 A more useful example of a customization function is the following,
329 which changes the default size of the
331 directory from 5MB to 30MB:
332 .Bd -literal -offset indent
334 cd ${NANO_WORLDDIR}/conf
335 echo 30000 > default/etc/md_size
337 customize_cmd cust_etc_size
347 utility first appeared in
353 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
354 This manual page was written by
355 .An Daniel Gerzo Aq Mt danger@FreeBSD.org .