Introduction to NanoBSD

DanielGerzo

Many of the designations used by
manufacturers and sellers to distinguish their products are claimed
as trademarks. Where those designations appear in this document,
and the FreeBSD Project was aware of the trademark claim, the
designations have been followed by the “™” or the
“®” symbol.

Last modified on 2014-05-24 15:33:58 by bcr.

Abstract

This document provides information about the
NanoBSD tools, which can be used to
create FreeBSD system images for embedded applications, suitable
for use on a Compact Flash card (or other mass storage
medium).

1. Introduction to NanoBSD

NanoBSD is a tool currently
developed by Poul-Henning Kamp <phk@FreeBSD.org>. It creates a FreeBSD system image for
embedded applications, suitable for use on a Compact Flash card
(or other mass storage medium).

It can be used to build specialized install images, designed
for easy installation and maintenance of systems commonly called
“computer appliances”. Computer appliances have
their hardware and software bundled in the product, which means
all applications are pre-installed. The appliance is plugged
into an existing network and can begin working (almost)
immediately.

The features of NanoBSD
include:

Ports and packages work as in FreeBSD — Every single
application can be installed and used in a
NanoBSD image, the same way as in
FreeBSD.

No missing functionality — If it is possible to do
something with FreeBSD, it is possible to do the same thing
with NanoBSD, unless the specific
feature or features were explicitly removed from the
NanoBSD image when it was
created.

Everything is read-only at run-time — It is safe
to pull the power-plug. There is no necessity to run
fsck(8) after a non-graceful shutdown of the
system.

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.

2. NanoBSD Howto

2.1. The Design of NanoBSD

Once the image is present on the medium, it is possible to
boot NanoBSD. The mass storage
medium is divided into three parts by default:

Two image partitions: code#1
and code#2.

The configuration file partition, which can be mounted
under the /cfg directory
at run time.

The configuration file partition persists under the
/cfg directory. It
contains files for /etc
directory and is briefly mounted read-only right after the
system boot, therefore it is required to copy modified files
from /etc back to the
/cfg directory if changes
are expected to persist after the system restarts.

Note:

The partition containing
/cfg should be mounted
only at boot time and while overriding the configuration
files.

Keeping /cfg mounted at all times
is not a good idea, especially if the
NanoBSD system runs off a mass
storage medium that may be adversely affected by a large
number of writes to the partition (like when the filesystem
syncer flushes data to the system disks).

2.2. Building a NanoBSD Image

A NanoBSD image is built using
a simple nanobsd.sh shell script, which
can be found in the
/usr/src/tools/tools/nanobsd
directory. This script creates an image, which can be copied
on the storage medium using the dd(1) utility.

Change the current directory to the base directory of
the NanoBSD build
script.

Start the build process.

Change the current directory to the place where the
built images are located.

Install NanoBSD onto the
storage medium.

2.3. Customizing a NanoBSD Image

This is probably the most important and most interesting
feature of NanoBSD. This is also
where you will be spending most of the time when
developing with NanoBSD.

Invocation of the following command will force the
nanobsd.sh to read its configuration from
myconf.nano located in the current
directory:

#sh nanobsd.sh -c myconf.nano

Customization is done in two ways:

Configuration options

Custom functions

2.3.1. Configuration Options

With configuration settings, it is possible to configure
options passed to both the
buildworld and
installworld stages of the
NanoBSD build process, as well as
internal options passed to the main build process of
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 FreeBSD even more, until it will consists of just the
kernel and two or three files in the userland.

The configuration file consists of configuration
options, which override the default values. The most
important directives are:

NANO_NAME — Name of build
(used to construct the workdir names).

NANO_SRC — Path to the
source tree used to build the image.

NANO_KERNEL — Name of
kernel configuration file used to build kernel.

CONF_BUILD — Options passed
to the buildworld stage of
the build.

CONF_INSTALL — Options
passed to the installworld
stage of the build.

CONF_WORLD — Options passed
to both the buildworld and
the installworld stage of the
build.

FlashDevice — Defines what
type of media to use. Check
FlashDevice.sub for more
details.

2.3.2. Custom Functions

It is possible to fine-tune
NanoBSD using shell functions in
the configuration file. The following example illustrates
the basic model of custom functions:

2.4. Updating NanoBSD

The update process of NanoBSD
is relatively simple:

Build a new NanoBSD image,
as usual.

Upload the new image into an unused partition of a
running NanoBSD
appliance.

The most important difference of this step from the
initial NanoBSD installation is
that now instead of using _.disk.full
(which contains an image of the entire disk), the
_.disk.image image is installed
(which contains an image of a single system
partition).

Reboot, and start the system from the newly installed
partition.

If all goes well, the upgrade is finished.

If anything goes wrong, reboot back into the previous
partition (which contains the old, working image), to
restore system functionality as fast as possible. Fix any
problems of the new build, and repeat the process.

To install new image onto the running
NanoBSD system, it is possible to
use either the updatep1 or
updatep2 script located in the
/root directory, depending from which
partition is running the current system.

According to which services are available on host serving
new NanoBSD image and what type of
transfer is preferred, it is possible to examine one of these
three ways: