/share/man/man8/nanobsd.8

  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 Nm NanoBSD Ss 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
280terminals
281.Pq Pa /dev/ttyv*
282and enables the use of the first serial port as the system
283console.
284.It Cm cust_allow_ssh_root
285Allow root to log in via
286.Xr sshd 8 .
287.It Cm cust_install_files
288Installs files from the
289.Pa nanobsd/Files
290directory, which contains some useful scripts for system administration.
291.El
292.Sh FILES
293.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact
294.It Pa src/tools/tools/nanobsd
295Base directory of the
296.Nm NanoBSD
297build script.
298.El
299.Sh EXAMPLES
300Making persistent changes to
301.Pa /etc/resolv.conf :
302.Bd -literal -offset indent
303vi /etc/resolv.conf
304\&...
305mount /cfg
306cp /etc/resolv.conf /cfg
307umount /cfg
308.Ed
309.Pp
310A more useful example of a customization function is the following,
311which changes the default size of the
312.Pa /etc
313directory from 5MB to 30MB:
314.Bd -literal -offset indent
315cust_etc_size () (
316	cd ${NANO_WORLDDIR}/conf
317	echo 30000 > default/etc/md_size
318)
319customize_cmd cust_etc_size
320.Ed
321.Sh SEE ALSO
322.Xr make.conf 5 ,
323.Xr boot 8 ,
324.Xr boot0cfg 8 ,
325.Xr picobsd 8
326.Sh HISTORY
327The
328.Nm
329utility first appeared in
330.Fx 6.0 .
331.Sh AUTHORS
332.An -nosplit
333.Nm NanoBSD
334was developed by
335.An Poul-Henning Kamp Aq phk@FreeBSD.org .
336This manual page was written by
337.An Daniel Gerzo Aq danger@FreeBSD.org .