docs/94419: [patch] NanoBSD chapter for Handbook
Daniel Gerzo
danger at rulez.sk
Mon Mar 13 19:30:16 UTC 2006
>Number: 94419
>Category: docs
>Synopsis: [patch] NanoBSD chapter for Handbook
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Mar 13 19:30:06 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator: Daniel Gerzo
>Release: FreeBSD 6.1-PRERELEASE i386
>Organization:
rulez.sk
>Environment:
System: FreeBSD tomas.elvandar.org 6.1-PRERELEASE FreeBSD 6.1-PRERELEASE #0: Wed Feb 15 02:22:30 CET 2006 root at redqueen.elvandar.org:/usr/obj/usr/src/sys/REDQUEEN i386
>Description:
As the documentation of the NanoBSD in its project site on freebsd.org
server is badly outdated and there is a Todo thing on this, I've been
working to document this tool. Now it's mostly done and it needs review
by some doc guy, most preferably native speaker. The document was
OK'd by phk@ in a technical manner via IRC.
The build version is available at:
http://www.sk.freebsd.org/doc/en/books/handbook/nanobsd.html
The source attached in Fix: section is also available at
http://danger.rulez.sk/nanobsd.sgml
>How-To-Repeat:
>Fix:
--- chapter.sgml begins here ---
<!--
The FreeBSD Documentation Project
$FreeBSD: $
-->
<chapter id="nanobsd">
<chapterinfo>
<authorgroup>
<author>
<firstname>Daniel</firstname>
<surname>Gerzo</surname>
<contrib>Written by </contrib>
<!-- 13 March 2006 -->
</author>
</authorgroup>
</chapterinfo>
<title>NanoBSD</title>
<sect1 id="nanobsd-intro">
<title>Introduction to <application>NanoBSD</application></title>
<para><application>NanoBSD</application> is tool currently
developed by &a.phk;. It creates a &os; system image for embedded
applications, suitable for use on a Compact Flash card (or other
mass storage medium).</para>
<para>It can probably be used to build a specialized server designed
for easy installation and maintenance called computer applicance.
Computer appliances have their hardware and software bundled in
the product, so all applications are pre-installed. The appliance
is plugged into an existing network and can begin working (almost)
immediately.</para>
<para>Features of <application>NanoBSD</application>:</para>
<itemizedlist>
<listitem>
<para>Ports and packages work like in &os;.</para>
</listitem>
<listitem>
<para>No missing functionality — If it is possible to do
with &os;, it is possible to do with
<application>NanoBSD</application>, unless it was removed in
compile time.</para>
</listitem>
<listitem>
<para>Everything is read-only at run-time — It is safe to
pull the power-plug. &man.fsck.8; is not necessary.</para>
</listitem>
<listitem>
<para>Easy to build and customize.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="nanobsd-howto">
<title><application>NanoBSD</application> Howto</title>
<sect2 id="nanobsd-design">
<title>The design of <application>NanoBSD</application></title>
<para>Once the image is present on the medium, it is possible to
boot the <application>NanoBSD</application>. The mass storage
medium is divided into three parts, two image partitions -
<literal>code#1</literal> and <literal>code#2</literal>, and the
configuration file partition -
<filename role="directory">/cfg</filename>, which are normally
mounted read-only. This means that it is safe to pull the power
plug on a <application>NanoBSD</application> machine and that
Flash based storage is not worn out with file system metadata
writes.</para>
<para><filename role="directory">/etc</filename> and
<filename role="directory">/var</filename> directories are
&man.md.4; (malloc) disks.</para>
<para>The configuration file partition persists under the <filename
role="directory">/cfg</filename> directory. This partition
contains files for <filename role="directory">/etc</filename>
directory and is briefly mounted read-only right after the system
boot. Note that this partition should be mounted only at
boot-time and while overriding the configuration files.</para>
<para>After some modifications have been done in files in
<filename role="directory">/etc</filename> and they are proposed
to exist after next boot, it is required to copy them to the
<filename role="directoru">/cfg</filename> directory. For
example:</para>
<screen>&prompt.root; <userinput>vim /etc/resolv.conf</userinput>
[...]
&prompt.root; <userinput>mount /cfg</userinput>
&prompt.root; <userinput>cp /etc/resolv.conf /cfg</userinput>
&prompt.root; <userinput>umount /cfg</userinput></screen>
</sect2>
<sect2>
<title>Building <application>NanoBSD</application> images</title>
<para>The <application>NanoBSD</application> is built using a simple
<filename>nanobsd.sh</filename> script, which can be found in the
<filename role="directory"><replaceable>/usr</replaceable>/src/tools/tools/nanobsd</filename>
directory. This script creates an image, which can be copied on
the storage medium using the &man.dd.1; command.</para>
<para>The necessary commands to build a
<application>NanoBSD</application> image are:</para>
<screen>&prompt.root; <userinput>cd /usr/src/tools/tools/nanobsd</userinput>
&prompt.root; <userinput>sh nanobsd.sh</userinput>
&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput>
&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput></screen>
</sect2>
<sect2>
<title>Customizing <application>NanoBSD</application> images</title>
<para>This is probably the most important and most interesting
feature of <application>NanoBSD</application>. This is also
place where you will be spending most of the time when
developing with <application>NanoBSD</application>.</para>
<para>Invocation of the following command will force the
<filename>nanobsd.sh</filename> to read its configuration from
the <filename>myconf.nano</filename> file located in the current
directory:</para>
<screen>&prompt.root; <userinput>sh nanobsd.sh -c myconf.nano</userinput></screen>
<para>Customization is done in two ways:</para>
<itemizedlist>
<listitem>
<para>Configuration options</para>
</listitem>
<listitem>
<para>Custom functions</para>
</listitem>
</itemizedlist>
<sect3>
<title>Configuration options</title>
<para>With configuration settings, it is possible to configure
options passed to both buildworld and installworld as well as
internal options passed to the main build process of
<application>NanoBSD</application>. Through these options it
is possible to cut the system down, so it will fit on as
little as 64MB medium. If much time is spent here, it can be
cut down even further, until it will consists of just the
kernel and two or three files in the userland.</para>
<para>Configuration file consists of configuration options,
which override the default values. The most important
directives are:</para>
<itemizedlist>
<listitem>
<para><literal>NANO_NAME</literal> — Name of build
(Used to construct the workdir names).</para>
</listitem>
<listitem>
<para><literal>NANO_SRC</literal> — Path to the source
tree used to build the image.</para>
</listitem>
<listitem>
<para><literal>NANO_KERNEL</literal> — Name of kernel
configuration file used to build kernel.</para>
</listitem>
<listitem>
<para><literal>CONF_BUILD</literal> — Options passed
to the buildworld.</para>
</listitem>
<listitem>
<para><literal>CONF_INSTALL</literal> — Options passed
to the installworld.</para>
</listitem>
<listitem>
<para><literal>CONF_WORLD</literal> — Options passed
to both buildworld and installworld.</para>
</listitem>
<listitem>
<para><literal>FlashDevice</literal> — Defines what
type of media to use. Check the
<filename>FlashDevice.sub</filename> file for more
details.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Custom functions</title>
<para>It is possible to fine-tune
<application>NanoBSD</application> using shell functions in
configuration file. The following example illustrates the
basic model of custom functions:</para>
<programlisting>cust_foo () (
echo "bar="topless" > \
${NANO_WORLDDIR}/etc/foo
)
customize_cmd cust_foo</programlisting>
<para>More useful example of usage of custom functions can
represent the following function, which changes the default
size of <filename role="directory">/etc</filename> from 5MB to
30MB:</para>
<programlisting>cust_etc_size () (
cd ${NANO_WORLDDIR}/conf
echo 30000 > default/etc/md_size
)
customize_cmd cust_etc_size</programlisting>
<para>There are a few default pre-defined customization
functions ready for use:</para>
<itemizedlist>
<listitem>
<para><literal>cust_comconsole</literal> — Disables
&man.getty.8; on the VGA devices (
<filename>/dev/ttyv*</filename>) and enables console in
the COM1 serial port.</para>
</listitem>
<listitem>
<para><literal>cust_allow_ssh_root</literal> — Allow
<username>root</username> to login via
&man.sshd.8;.</para>
</listitem>
<listitem>
<para><literal>cust_install_files</literal> —
Installs files from
<filename role="directory">nanobsd/Files</filename>
directory, which contains some useful scripts for system
administration.</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Configuration file example</title>
<para>The example of configuration file might be
following:</para>
<programlisting>NANO_NAME=custom
NANO_SRC=/usr/src
NANO_KERNEL=MYKERNEL
NANO_IMAGES=2
CONF_BUILD='
NO_KLDLOAD=YES
NO_NETGRAPH=YES
NO_PAM=YES
'
CONF_INSTALL='
NO_ACPI=YES
NO_BLUETOOTH=YES
NO_CVS=YES
NO_FORTRAN=YES
NO_HTML=YES
NO_LPR=YES
NO_MAN=YES
NO_SENDMAIL=YES
NO_SHAREDOCS=YES
NO_EXAMPLES=YES
NO_INSTALLLIB=YES
NO_CALENDAR=YES
NO_MISC=YES
NO_SHARE=YES
'
CONF_WORLD='
NO_BIND=YES
NO_MODULES=YES
NO_KERBEROS=YES
NO_GAMES=YES
NO_RESCUE=YES
NO_LOCALES=YES
NO_SYSCONS=YES
NO_INFO=YES
'
FlashDevice SanDisk 1G
cust_nobeastie() (
touch ${NANO_WORLDDIR}/boot/loader.conf
echo "beastie_disable=\"YES\"" >> ${NANO_WORLDDIR}/boot/loader.conf
)
customize_cmd cust_comconsole
customize_cmd cust_install_files
customize_cmd cust_allow_ssh_root
customize_cmd cust_nobeastie</programlisting>
</sect3>
</sect2>
<sect2>
<title>Updating <application>NanoBSD</application></title>
<para>Update of <application>NanoBSD</application> is very simple.
This involves the steps of building
<application>NanoBSD</application> image described above and
installing it onto the partition. The only difference is that
the <filename>_.disk.image</filename> image (which contains the
system for only one partition) is used instead of
<filename>_.disk.full</filename>.</para>
<para>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.</para>
<para>To install new image onto the running
<application>NanoBSD</application> system, it is possible to use
either the <filename>updatep1</filename> or
<filename>updatep2</filename> script located in the
<filename role="directory">/root</filename> directory, depending
from which partition is running the current system.</para>
<para>It is possible to exampine one of these three ways:</para>
<sect3>
<title>Using &man.nc.1;</title>
<screen>myhost&prompt.root; <userinput>nc -l 2222 < _.disk.image</userinput></screen>
<screen>&prompt.root; <userinput>nc myhost 2222 | sh updatep1</userinput></screen>
</sect3>
<sect3>
<title>Using &man.ftp.1;</title>
<screen>&prompt.root; <userinput>ftp myhost
get _.disk.image "| sh updatep1"</userinput></screen>
</sect3>
<sect3>
<title>Using &man.ssh.1;</title>
<screen>&prompt.root; <userinput>ssh myhost cat _.disk.image.gz | zcat | sh updatep1</userinput></screen>
</sect3>
</sect2>
</sect1>
</chapter>
--- chapter.sgml ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list