All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
$FreeBSD: releng/10.2/share/man/man8/nanobsd.8 271095 2014-09-04 13:45:16Z se $
.Dd May 20, 2010 .Dt NANOBSD 8 .Os .Sh NAME .Nm nanobsd.sh .Nd utility used to create a FreeBSD system image suitable for embedded applications .Sh SYNOPSIS .Nm .Op Fl bhknw .Op Fl c Ar config-file .Sh DESCRIPTION The .Nm utility is a script which produces a minimal implementation of .Fx (called .Nm NanoBSD ) , which typically fits on a small media such as a Compact Flash card, or other mass storage medium. It can be used to build specialized install images, designed for easy installation and maintenance.
p The following options are available: l -tag -width ".Fl c Ar config-file" -offset indent t Fl b Skip the build stages (both for kernel and world). t Fl c Ar config-file Specify the configuration file to use. t Fl h Display usage information. t Fl k Skip the .Cm buildkernel stage of the build. t Fl n Do not cleanup before each build stage. This suppresses the normal cleanup work done before the .Cm buildworld stage and adds -DNO_CLEAN to the make command line used for each build stage (world and kernel). t Fl w Skip the .Cm buildworld stage of the build. .El
p The features of .Nm NanoBSD include:
p l -bullet -offset indent -compact t Ports and packages work as in .Fx . Every single application can be installed and used in a .Nm NanoBSD image, the same way as in .Fx . t No missing functionality. If it is possible to do something with .Fx , it is possible to do the same thing with .Nm NanoBSD , unless the specific feature or features were explicitly removed from the .Nm NanoBSD image when it was created. t Everything is read-only at run-time. It is safe to pull the power-plug. There is no necessity to run .Xr fsck 8 after a non-graceful shutdown of the system. t Easy to build and customize. Making use of just one shell script and one configuration file it is possible to build reduced and customized images satisfying any arbitrary set of requirements. .El .Ss Nm NanoBSD Ss Media Layout The mass storage medium is divided into three parts by default (which are normally mounted read-only):
p l -bullet -offset indent -compact t Two image partitions: .Li code#1 and .Li code#2 . t The configuration file partition, which can be mounted under the
a /cfg directory at run time. .El
p The
a /etc and
a /var directories are .Xr md 4 (malloc backed) disks.
p The configuration file partition persists under the
a /cfg directory. It contains files for
a /etc directory and is briefly mounted read-only right after the system boot, therefore it is required to copy modified files from
a /etc back to the
a /cfg directory if changes are expected to persist after the system restarts. .Sh BUILDING Nm NanoBSD A .Nm NanoBSD image is built using a simple .Nm shell script, which can be found in the
a src/tools/tools/nanobsd directory. This script creates a bootable image, which can be copied on the storage medium using the .Xr dd 1 utility.
p The necessary commands to build and install a .Nm NanoBSD image are: d -literal -offset indent cd /usr/src/tools/tools/nanobsd sh nanobsd.sh cd /usr/obj/nanobsd.full dd if=_.disk.full of=/dev/da0 bs=64k .Ed .Sh CUSTOMIZING Nm NanoBSD This is probably the most important and most interesting feature of .Nm NanoBSD . This is also where you will be spending most of the time when developing with .Nm NanoBSD .
p Customization is done in two ways:
p l -bullet -offset indent -compact t Configuration options. t Custom functions. .El
p With configuration settings, it is possible to configure options passed to both the .Cm buildworld and .Cm installworld stages of the .Nm NanoBSD build process, as well as internal options passed to the main build process of .Nm NanoBSD . Through these options it is possible to cut the system down, so it will fit on as little as 64MB. You can use the configuration options to trim down the system even more, until it will consist of just the kernel and two or three files in the userland.
p The configuration file consists of configuration options, which override the default values. The most important directives are: l -tag -width ".Va CONF_INSTALL" -offset indent t Va NANO_NAME Build name (used to construct the working directory names). t Va NANO_SRC Path to the source tree used to build the image. t Va NANO_KERNEL Name of the kernel configuration file used to build the kernel. t Va NANO_ARCH Machine processor architecture to build. Defaults to output of .Cm uname -p . t Va NANO_BOOT0CFG Controls the options passed to .Xr boot0cfg 8 ; these dictate .Nm boot0 Ns 's behaviour. t Va NANO_BOOTLOADER The .Nm boot0 loader to use relative to the .Va NANO_WORLDDIR variable. This defaults to
a boot/boot0sio and should be overridden to
a boot/boot0 to provide a VGA console. t Va CONF_BUILD Options passed to the .Cm buildworld stage of the build. t Va CONF_INSTALL Options passed to the .Cm installworld stage of the build. t Va CONF_WORLD Options passed to both the .Cm buildworld and .Cm installworld stages of the build. t Va FlashDevice Defines the type of media to use. Check the
a FlashDevice.sub file for more details. .El
p For more configuration options, please check the .Nm script.
p To build .Nm NanoBSD image using the
a nanobsd.conf configuration file, use the following command: d -literal -offset indent sh nanobsd.sh -c nanobsd.conf .Ed
p It is possible to fine-tune .Nm NanoBSD using shell functions in the configuration file. The following example illustrates the basic model of custom functions: d -literal -offset indent cust_foo () ( echo "bar=topless" > \\ ${NANO_WORLDDIR}/etc/foo ) customize_cmd cust_foo .Ed
p There are a few pre-defined customization functions ready for use: l -tag -width ".Cm cust_allow_ssh_root" -offset indent t Cm cust_comconsole Disables .Xr getty 8 on the virtual .Xr syscons 4 or .Xr vt 4 terminals
q Pa /dev/ttyv* and enables the use of the first serial port as the system console. t Cm cust_allow_ssh_root Allow root to log in via .Xr sshd 8 . t Cm cust_install_files Installs files from the
a nanobsd/Files directory, which contains some useful scripts for system administration. .El .Sh FILES l -tag -width ".Pa src/tools/tools/nanobsd" -compact t Pa src/tools/tools/nanobsd Base directory of the .Nm NanoBSD build script. .El .Sh EXAMPLES Making persistent changes to
a /etc/resolv.conf : d -literal -offset indent vi /etc/resolv.conf ... mount /cfg cp /etc/resolv.conf /cfg umount /cfg .Ed
p A more useful example of a customization function is the following, which changes the default size of the
a /etc directory from 5MB to 30MB: d -literal -offset indent cust_etc_size () ( cd ${NANO_WORLDDIR}/conf echo 30000 > default/etc/md_size ) customize_cmd cust_etc_size .Ed .Sh SEE ALSO .Xr make.conf 5 , .Xr boot 8 , .Xr boot0cfg 8 , .Xr picobsd 8 .Sh HISTORY The .Nm utility first appeared in .Fx 6.0 . .Sh AUTHORS .An -nosplit .Nm NanoBSD was developed by .An Poul-Henning Kamp Aq phk@FreeBSD.org . This manual page was written by .An Daniel Gerzo Aq danger@FreeBSD.org .