os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
doc/en/projects/nanobsd/index.sgml
Hiroki Sato f9105467ef Merge new www design. 
Submitted by:	Emily Boyd (emilyboyd at emilyboyd dot com)
Sponsored by:	Google Summer of Code 2005
2005-10-04 19:43:53 +00:00

192 lines
7.6 KiB
Text
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD: www/en/projects/nanobsd/index.sgml,v 1.4 2005/09/19 17:02:45 joel Exp $">
<!ENTITY title "NanoBSD: FreeBSD for appliance use.">
<!ENTITY % navincludes SYSTEM "../../includes.navdevelopers.sgml"> %navincludes;
<!ENTITY % includes SYSTEM "../../includes.sgml"> %includes;
<!-- Status levels -->
<!-- The list of contributors was moved to a separate file so that it can
be used by other documents in the FreeBSD web site. -->
<!ENTITY % developers SYSTEM "../../developers.sgml"> %developers;
]>
<html>
&header;
<h2>NanoBSD = FreeBSD for appliance use.</h2>
<p>
NanoBSD is designed to put a possibly reduced FreeBSD system
on a Compact Flash card (or other mass storage of your choice)
in a way which is suitable for use in appliance like applications.
<p>
The mass storage is divided into three parts, two image partitions
and a configuration file partition, which normally are mounted
only read-only. This means that it is safe to pull the power
plug on a NanoBSD machine and that Flash based storage is not worn
out with filesystem metadata writes.
<p>
Having two image partitions means that it is possible to download
a new image while the system is running, reboot to run that new
image and if that fails somehow, it is still possible to switch
back to the old image partition.
<h2>Building NanoBSD images</h2>
<p>
The Nanobsd build system lives in <tt>src/tools/tools/nanobsd</tt>
and consists of makefiles and shell scripts which drives use of
the Makefiles in the FreeBSD source tree to create a NanoBSD image.
<p>
The necessary commands to build a NanoBSD image are:
<ul>
<li><tt>cd .../src/tools/tools/nanobsd</tt>
<li><tt>make</tt>
</ul>
<p>
Depending on your machine, this will take from half an hour
to some hours. The process is split into a sequence of
steps, and if errors happen underway it is generally, but
not always possible to rectify the error and type <tt>make</tt>
again to complete the missing steps.
<p>
If you want to start from scratch you have to delete all files
and directories in the NanoBSD directory which start with an
underscore: <tt>rm -rf _.*</tt>
<p>
Here is a breakdown of the files and directories which NanoBSD
builds, in the order they are built:
<ul>
<li><tt>_.bw</tt>
<p>The output from running <tt>make buildworld</tt> in the
source tree.
<p>If this step fails, the output is instead left
in the file <tt>_.bw.tmp</tt>
<li><tt>_.iw</tt>
<p>The output from running <tt>make installworld DESTDIR=_.w</tt>
in the source tree.
<p>If this step fails, the output is instead left
in the file <tt>_.iw.tmp</tt>
<li><tt>_.w</tt>
<p>This is the directory tree into which installworld installs.
<li><tt>_.di</tt>
<p>The output from running <tt>make distribute DESTDIR=_.w</tt>
in the source trees <tt>etc</tt> subdirectory.
<p>If this step fails, the output is instead left
in the file <tt>_.di.tmp</tt>
<li><tt>_.bk</tt>
<p>The output from running <tt>make buildkernel</tt>
in the source tree.
<p>If this step fails, the output is instead left
in the file <tt>_.bk.tmp</tt>
<li><tt>_.ik</tt>
<p>The output from running <tt>make installkernel DESTDIR=_.w</tt>
in the source tree.
<p>If this step fails, the output is instead left
in the file <tt>_.ik.tmp</tt>
<li><tt>_.cs</tt>
<p>The output from running the customization scripts in the
<tt>Customize</tt> subdirectory.
<p>If this step fails, the output is instead left
in the file <tt>_.cs.tmp</tt>
<li><tt>_.md</tt>
<p>The output from building the image file containing the filesystem
images of the finished NanoBSD.
<p>If this step fails, the output is instead left
in the file <tt>_.md.tmp</tt>
<li><tt>_.mtree</tt>
<p>Mtree(8) output from the files installed into the code patitions
in the NanoBSD image.
<li><tt>_.i</tt>
<p>Image file containing the full disk image. This is the image
file you will put on the Compact Flash or other mass storage from
which your target platform boots.
<li><tt>_.i.s1</tt>
<p>Image file containing just the code partition image. This is
image you will download to update a running system.
</ul>
<h2>Customizing NanoBSD images</h2>
<p>
This is where things get interesting, and where you will be spending
your time when developing with NanoBSD.
<h3>Storage media size</h3>
<p>
The first thing you need to configure is how much storage
you have on your mass storage media. NanoBSD can work out
of the box with as little as 64MB, and if you spend time on
it, you can cut it down even further until you end up with
an installed system with just the kernel and two or three
files in userland.
<p>
You can determine the size of the storage media with the
diskinfo(8) command or by examining dmesg(8) or console
output during boot.
<p>
Once you know the number of sectors on the entire media
insert this in the <tt>Makefile</tt> in the definitions of
SECTS or pass it as a command line option to make(1) when
you build NanoBSD: <tt>MAKE SECTS=100000</tt>.
<h3>Storage media geometry</h3>
<p>
Some platforms need to use CHS addressing in the bootblocks
in which case you need to set the <tt>HD</tt> and <tt>SC</tt>
values in the Makefile as well. These can also be found from
diskinfo(8), dmesg(8) or console output. Even if your current
platform does not need these to be set, it is always a good idea
to do it anyway.
<p>
Please be aware that you have to get the values used on the
target platform. Putting a CF card in a USB-CF adapter will
not result in the correct values for the geometry.
<h3>Config partition size</h3>
<p>
The <tt>DATASIZE</tt> parameter controls how many sectors are
used for the configuration partition. Typically you will need
very little, but depending on your application and how you
organize things, you may want to set this higher or lower.
Obviously, the space you use for the configuration partition
is not available for the image partitions.
<h3>Customize scripts</h3>
<p>
You can run scripts which will customize the NanoBSD image
by listing them in the <tt>CUSTOMIZE</tt> variable in the
Makefile. The scripts will be given arguments to show them
where everything is and they can do pretty much anything
they want to do to the directory tree.
<h3>Slimming down FreeBSD to fit</h3>
<p>
The <tt>make.conf</tt> file overrides the usual <tt>/etc/make.conf</tt>
and by default disables a lot of FreeBSD from the build in order to
make it fit on 64MB devices. Go through the list and decide if there
are anything you want or do not want in your NanoBSD image.
<h3>Slimming down the kernel</h3>
<p>
You may also want to use a kernel other than <tt>GENERIC</tt>.
Put the config file in <tt>../../../sys/i386/conf</tt> and
set the name in <tt>KERNCONF</tt> in <tt>make.conf</tt>.
<p>
You can save a couple of megabytes of space in your image by
removing all the bits you will not need. (How many appliances
need support for nine different RAID controllers ?)
<h2>Provided customize scripts</h2>
<p>
By default the following customize scripts are provided (but not
called unless you list them in <tt>CUSTOMIZE</tt>.
<h3>comconsole</h3>
<p>
Disables getty(8) on the VGA devices and enables console in the
COM1 serial port.
<h3>nobeastie</h3>
<p>
Disables the "beastie-menu" in the bootloader.
<h3>NET4801</h3>
<p>
Disables ata-dma for the Soekris NET4801 because early hardware
versions do not support DMA on the CF socket.
&footer;
</body>
</html>
Reference in a new issue View git blame Copy permalink