xref: /freebsd/share/man/man8/nanobsd.8 (revision 65b71c48d226f3ef3eb1c4452dccc678a7d2ac96)
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 May 20, 2010
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 bhknw
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 n
63Do not cleanup before each build stage.
64This suppresses the normal cleanup work done before the
65.Cm buildworld
66stage and adds -DNO_CLEAN to the make command line
67used for each build stage (world and kernel).
68.It Fl w
69Skip the
70.Cm buildworld
71stage of the build.
72.El
73.Pp
74The features of
75.Nm NanoBSD
76include:
77.Pp
78.Bl -bullet -offset indent -compact
79.It
80Ports and packages work as in
81.Fx .
82Every single application can be installed and used in a
83.Nm NanoBSD
84image, the same way as in
85.Fx .
86.It
87No missing functionality.
88If it is possible to do something with
89.Fx ,
90it is possible to do the same thing with
91.Nm NanoBSD ,
92unless the specific feature or features were explicitly removed from the
93.Nm NanoBSD
94image when it was created.
95.It
96Everything is read-only at run-time.
97It is safe to pull the power-plug.
98There is no necessity to run
99.Xr fsck 8
100after a non-graceful shutdown of the system.
101.It
102Easy to build and customize.
103Making use of just one shell script and one configuration file it is
104possible to build reduced and customized images satisfying any arbitrary
105set of requirements.
106.El
107.Ss NanoBSD Media Layout
108The mass storage medium is divided into three parts by default (which
109are normally mounted read-only):
110.Pp
111.Bl -bullet -offset indent -compact
112.It
113Two image partitions:
114.Li code#1
115and
116.Li code#2 .
117.It
118The configuration file partition, which can be mounted under the
119.Pa /cfg
120directory at run time.
121.El
122.Pp
123The
124.Pa /etc
125and
126.Pa /var
127directories are
128.Xr md 4
129(malloc backed) disks.
130.Pp
131The configuration file partition persists under the
132.Pa /cfg
133directory.
134It contains files for
135.Pa /etc
136directory and is briefly mounted read-only right after the system boot,
137therefore it is required to copy modified files from
138.Pa /etc
139back to the
140.Pa /cfg
141directory if changes are expected to persist after the system restarts.
142.Sh BUILDING Nm NanoBSD
143A
144.Nm NanoBSD
145image is built using a simple
146.Nm
147shell script, which can be
148found in the
149.Pa src/tools/tools/nanobsd
150directory.
151This script creates a bootable image, which can be copied on the storage
152medium using the
153.Xr dd 1
154utility.
155.Pp
156The necessary commands to build and install a
157.Nm NanoBSD
158image are:
159.Bd -literal -offset indent
160cd /usr/src/tools/tools/nanobsd
161sh nanobsd.sh
162cd /usr/obj/nanobsd.full
163dd if=_.disk.full of=/dev/da0 bs=64k
164.Ed
165.Sh CUSTOMIZING Nm NanoBSD
166This is probably the most important and most interesting feature of
167.Nm NanoBSD .
168This is also where you will be spending most of the time when developing with
169.Nm NanoBSD .
170.Pp
171Customization is done in two ways:
172.Pp
173.Bl -bullet -offset indent -compact
174.It
175Configuration options.
176.It
177Custom functions.
178.El
179.Pp
180With configuration settings, it is possible to configure options passed
181to both the
182.Cm buildworld
183and
184.Cm installworld
185stages of the
186.Nm NanoBSD
187build process, as well as internal options passed to the main build
188process of
189.Nm NanoBSD .
190Through these options it is possible to cut the system down, so it will
191fit on as little as 64MB.
192You can use the configuration options to trim down the system
193even more, until it will consist of just the kernel and two or three
194files in the userland.
195.Pp
196The configuration file consists of configuration options, which override
197the default values.
198The most important directives are:
199.Bl -tag -width ".Va CONF_INSTALL" -offset indent
200.It Va NANO_NAME
201Build name (used to construct the working directory names).
202.It Va NANO_SRC
203Path to the source tree used to build the image.
204.It Va NANO_KERNEL
205Name of the kernel configuration file used to build the kernel.
206.It Va NANO_ARCH
207Machine processor architecture to build. Defaults to output of
208.Cm uname -p .
209.It Va NANO_BOOT0CFG
210Controls the options passed to
211.Xr boot0cfg 8 ;
212these dictate
213.Nm boot0 Ns 's
214behaviour.
215.It Va NANO_BOOTLOADER
216The
217.Nm boot0
218loader to use relative to the
219.Va NANO_WORLDDIR
220variable.
221This defaults to
222.Pa boot/boot0sio
223and should be overridden to
224.Pa boot/boot0
225to provide a VGA
226console.
227.It Va CONF_BUILD
228Options passed to the
229.Cm buildworld
230stage of the build.
231.It Va CONF_INSTALL
232Options passed to the
233.Cm installworld
234stage of the build.
235.It Va CONF_WORLD
236Options passed to both the
237.Cm buildworld
238and
239.Cm installworld
240stages of the build.
241.It Va FlashDevice
242Defines the type of media to use.
243Check the
244.Pa FlashDevice.sub
245file for more details.
246.El
247.Pp
248For more configuration options, please check the
249.Nm
250script.
251.Pp
252To build
253.Nm NanoBSD
254image using the
255.Pa nanobsd.conf
256configuration file, use the following command:
257.Bd -literal -offset indent
258sh nanobsd.sh -c nanobsd.conf
259.Ed
260.Pp
261It is possible to fine-tune
262.Nm NanoBSD
263using shell functions in the configuration file.
264The following example illustrates the basic model of custom functions:
265.Bd -literal -offset indent
266cust_foo () (
267	echo "bar=topless" > \\
268	     ${NANO_WORLDDIR}/etc/foo
269)
270customize_cmd cust_foo
271.Ed
272.Pp
273There 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
276Disables
277.Xr getty 8
278on the virtual
279.Xr syscons 4
280or
281.Xr vt 4
282terminals
283.Pq Pa /dev/ttyv*
284and enables the use of the first serial port as the system
285console.
286.It Cm cust_allow_ssh_root
287Allow root to log in via
288.Xr sshd 8 .
289.It Cm cust_install_files
290Installs files from the
291.Pa nanobsd/Files
292directory, which contains some useful scripts for system administration.
293.El
294.Sh FILES
295.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
296.It Pa src/tools/tools/nanobsd
297Base directory of the
298.Nm NanoBSD
299build script.
300.El
301.Sh EXAMPLES
302Making persistent changes to
303.Pa /etc/resolv.conf :
304.Bd -literal -offset indent
305vi /etc/resolv.conf
306\&...
307mount /cfg
308cp /etc/resolv.conf /cfg
309umount /cfg
310.Ed
311.Pp
312A more useful example of a customization function is the following,
313which changes the default size of the
314.Pa /etc
315directory from 5MB to 30MB:
316.Bd -literal -offset indent
317cust_etc_size () (
318	cd ${NANO_WORLDDIR}/conf
319	echo 30000 > default/etc/md_size
320)
321customize_cmd cust_etc_size
322.Ed
323.Sh SEE ALSO
324.Xr make.conf 5 ,
325.Xr boot 8 ,
326.Xr boot0cfg 8 ,
327.Xr picobsd 8
328.Sh HISTORY
329The
330.Nm
331utility first appeared in
332.Fx 6.0 .
333.Sh AUTHORS
334.An -nosplit
335.Nm NanoBSD
336was developed by
337.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
338This manual page was written by
339.An Daniel Gerzo Aq Mt danger@FreeBSD.org .
340