os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a chapter about "NanoBSD". This probably needs a bit more work,

Browse source 
and I may have missed some SGML-ification, but let's give more
visibility to the chapter, so others can help me improve it too.

PR:             docs/94419
Submitted by:   Daniel Gerzo <danger@rulez.sk>
This commit is contained in:
Giorgos Keramidas 2006-05-04 16:21:08 +00:00
parent 5427b85b50
commit e48fa8dedb
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=27714
5 changed files with 488 additions and 0 deletions
en_US.ISO8859-1/books/handbook
Makefilebook.sgmlchapters.ent
nanobsd
Makefilechapter.sgml

1
en_US.ISO8859-1/books/handbook/Makefile
View file

@ -176,6 +176,7 @@ SRCS+= mac/chapter.sgml
SRCS+= mail/chapter.sgml
SRCS+= mirrors/chapter.sgml
SRCS+= multimedia/chapter.sgml
SRCS+= nanobsd/chapter.sgml
SRCS+= network-servers/chapter.sgml
SRCS+= pgpkeys/chapter.sgml
SRCS+= ports/chapter.sgml

2
en_US.ISO8859-1/books/handbook/book.sgml
View file

@ -38,6 +38,7 @@
<!ENTITY % chap.network-servers "IGNORE">
<!ENTITY % chap.mail "IGNORE">
<!ENTITY % chap.cutting-edge "IGNORE">
<!ENTITY % chap.nanobsd "IGNORE">
<!ENTITY % chap.linuxemu "IGNORE">
<!ENTITY % chap.mirrors "IGNORE">
<!ENTITY % chap.bibliography "IGNORE">
@ -269,6 +270,7 @@
<![ %chap.vinum; [ &chap.vinum; ]]>
<![ %chap.l10n; [ &chap.l10n; ]]>
<![ %chap.cutting-edge; [ &chap.cutting-edge; ]]>
<![ %chap.nanobsd; [ &chap.nanobsd; ]]>
</part>
<part id="network-communication">

1
en_US.ISO8859-1/books/handbook/chapters.ent
View file

@ -37,6 +37,7 @@
<!ENTITY chap.vinum SYSTEM "vinum/chapter.sgml">
<!ENTITY chap.l10n SYSTEM "l10n/chapter.sgml">
<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.sgml">
<!ENTITY chap.nanobsd SYSTEM "nanobsd/chapter.sgml">
<!-- Part four -->
<!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.sgml">

15
en_US.ISO8859-1/books/handbook/nanobsd/Makefile Normal file
View file

@ -0,0 +1,15 @@
#
# Build the Handbook with just the content from this chapter.
#
# $FreeBSD$
#
CHAPTERS= nanobsd/chapter.sgml
VPATH= ..
MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
DOC_PREFIX?= ${.CURDIR}/../../../..
.include "../Makefile"

469
en_US.ISO8859-1/books/handbook/nanobsd/chapter.sgml Normal file
View file

@ -0,0 +1,469 @@
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="nanobsd">
<chapterinfo>
<authorgroup>
<author>
<firstname>Daniel</firstname>
<surname>Gerzo</surname>
<contrib>Written by </contrib>
<!-- 14 March 2006 -->
</author>
</authorgroup>
</chapterinfo>
<title>NanoBSD</title>
<sect1 id="nanobsd-intro">
<title>Introduction to NanoBSD</title>
<indexterm><primary>NanoBSD</primary></indexterm>
<para><application>NanoBSD</application> is a 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 be used to build specialized install images, designed
for easy installation and maintenance of systems commonly called <quote>computer appliances</quote>.
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.</para>
<para>The features of <application>NanoBSD</application> include:</para>
<itemizedlist>
<listitem>
<para>Ports and packages work as in &os; &mdash; Every single
application can be installed and used in a <application>NanoBSD</application> image, the same way as in
&os;.</para>
</listitem>
<listitem>
<para>No missing functionality &mdash; If it is possible to do
something with &os;, it is possible to do the same thing with
<application>NanoBSD</application>, unless the specific feature
or features were explicitly removed from
the <application>NanoBSD</application> image when it was
created.</para>
</listitem>
<listitem>
<para>Everything is read-only at run-time &mdash; It is safe to
pull the power-plug. There is no necessity to run
&man.fsck.8; after a non-graceful shutdown of the system.</para>
</listitem>
<listitem>
<para>Easy to build and customize &mdash; 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.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="nanobsd-howto">
<title>NanoBSD Howto</title>
<sect2 id="nanobsd-design">
<title>The design of NanoBSD</title>
<para>Once the image is present on the medium, it is possible to
boot <application>NanoBSD</application>. The mass storage
medium is divided into three parts by default:</para>
<itemizedlist>
<listitem>
<para>Two image partitions: <literal>code#1</literal>
and <literal>code#2</literal>.</para>
</listitem>
<listitem>
<para>The configuration file partition, which can be mounted
under the <filename role="directory">/cfg</filename> directory at run
time.</para>
</listitem>
</itemizedlist>
<para>These partitions are normally mounted read-only.</para>
<para>The <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. It
contains files for <filename role="directory">/etc</filename>
directory and is briefly mounted read-only right after the
system boot, therefore it is required to copy modified files
from <filename role="directory">/etc</filename> back to the
<filename role="directory">/cfg</filename> directory if changes
are expected to persist after the system restarts.</para>
<example>
<title>Making persistent changes to <filename>/etc/resolv.conf</filename></title>
<screen>&prompt.root; <userinput>vi /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>
</example>
<note>
<para>The partition containing
<filename role="directory">/cfg</filename> should be mounted
only at boot time and while overriding the configuration
files.</para>
<para>Keeping <filename role="directory">/cfg</filename> mounted
at all times is not a good idea, especially if the <application>NanoBSD</application>
system runs off a mass storage medium that may be adversely
affected by a large number of writes to the partition
(i.e. when the filesystem syncer flushes data to the system
disks).</para>
</note>
</sect2>
<sect2>
<title>Building a NanoBSD image</title>
<para>A <application>NanoBSD</application> image is built using a
simple <filename>nanobsd.sh</filename> shell 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; utility.</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> <co id="nbsd-cd">
&prompt.root; <userinput>sh nanobsd.sh</userinput> <co id="nbsd-sh">
&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co id="nbsd-cd2">
&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co id="nbsd-dd"></screen>
<calloutlist>
<callout arearefs="nbsd-cd">
<para>Change the current directory to the base directory of the
<application>NanoBSD</application> build script.</para>
</callout>
<callout arearefs="nbsd-sh">
<para>Start the build process.</para>
</callout>
<callout arearefs="nbsd-cd2">
<para>Change the current directory to the place where the built
images are located.</para>
</callout>
<callout arearefs="nbsd-dd">
<para>Install <application>NanoBSD</application> onto the
storage medium.</para>
</callout>
</calloutlist>
</sect2>
<sect2>
<title>Customizing a NanoBSD image</title>
<para>This is probably the most important and most interesting
feature of <application>NanoBSD</application>. This is also
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 the <literal>buildworld</literal>
and <literal>installworld</literal> stages of the
<application>NanoBSD</application> build process, 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. You can use the configuration options to trim down &os; even
more, until it will consists of just the kernel and two or three
files in the userland.</para>
<para>The configuration file consists of configuration options,
which override the default values. The most important
directives are:</para>
<itemizedlist>
<listitem>
<para><literal>NANO_NAME</literal> &mdash; Name of build
(used to construct the workdir names).</para>
</listitem>
<listitem>
<para><literal>NANO_SRC</literal> &mdash; Path to the source
tree used to build the image.</para>
</listitem>
<listitem>
<para><literal>NANO_KERNEL</literal> &mdash; Name of kernel
configuration file used to build kernel.</para>
</listitem>
<listitem>
<para><literal>CONF_BUILD</literal> &mdash; Options passed
to the <literal>buildworld</literal> stage of the build.</para>
</listitem>
<listitem>
<para><literal>CONF_INSTALL</literal> &mdash; Options passed
to the <literal>installworld</literal> stage of the build.</para>
</listitem>
<listitem>
<para><literal>CONF_WORLD</literal> &mdash; Options passed to both
the <literal>buildworld</literal> and
the <literal>installworld</literal> stage of the build.</para>
</listitem>
<listitem>
<para><literal>FlashDevice</literal> &mdash; 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
the configuration file. The following example illustrates the
basic model of custom functions:</para>
<programlisting>cust_foo () (
echo "bar=topless" &gt; \
&dollar;{NANO_WORLDDIR}/etc/foo
)
customize_cmd cust_foo</programlisting>
<para>A more useful example of a customization function is the
following, which changes the default size of the
<filename role="directory">/etc</filename> directory
from 5MB to 30MB:</para>
<programlisting>cust_etc_size () (
cd &dollar;{NANO_WORLDDIR}/conf
echo 30000 &gt; 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> &mdash; Disables
&man.getty.8; on the VGA devices
(the <filename>/dev/ttyv*</filename> device nodes) and enables
the use of the COM1 serial port as the system console.</para>
</listitem>
<listitem>
<para><literal>cust_allow_ssh_root</literal> &mdash; Allow
<username>root</username> to login via &man.sshd.8;.</para>
</listitem>
<listitem>
<para><literal>cust_install_files</literal> &mdash;
Installs files from the <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>A complete example of a configuration file for building a
custom <application>NanoBSD</application> image can be:</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 &dollar;{NANO_WORLDDIR}/boot/loader.conf
echo "beastie_disable=\"YES\"" &gt;&gt; &dollar;{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 NanoBSD</title>
<para>The update process of <application>NanoBSD</application> is
relatively simple:</para>
<procedure>
<step>
<para>Build a new <application>NanoBSD</application> image, as
usual.</para>
</step>
<step>
<para>Upload the new image into an unused partition of a
running <application>NanoBSD</application> appliance.</para>
<para>The most important difference of this step from the
initial <application>NanoBSD</application> installation is that
now instead of using the <filename>_.disk.full</filename> file
(which contains an image of the entire disk),
the <filename>_.disk.image</filename> image is installed (which
contains an image of a single system partition).</para>
</step>
<step>
<para>Reboot, and start the system from the newly installed
partition.</para>
</step>
<step>
<para>If all goes well, the upgrade is finished.</para>
</step>
<step>
<para>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.</para>
</step>
</procedure>
<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>According to which services are available on host serving
new <application>NanoBSD</application> image and what type of
transfer is prefered, it is possible to examine one of these
three ways:</para>
<sect3>
<title>Using &man.ftp.1;</title>
<para>If the transfer speed is in first place, use this
example:</para>
<screen>&prompt.root; <userinput>ftp myhost
get _.disk.image "| sh updatep1"</userinput></screen>
</sect3>
<sect3>
<title>Using &man.ssh.1;</title>
<para>If a secure transfer is prefered, consider using this
example:</para>
<screen>&prompt.root; <userinput>ssh myhost cat _.disk.image.gz | zcat | sh updatep1</userinput></screen>
</sect3>
<sect3>
<title>Using &man.nc.1;</title>
<para>Try this example if the remote host is not running neither
&man.ftp.1; or &man.sshd.8; service:</para>
<procedure>
<step>
<para>At first, open a TCP listener on host serving the
image and make it send the image to client:</para>
<screen>myhost&prompt.root; <userinput>nc -l <replaceable>2222</replaceable> &lt; _.disk.image</userinput></screen>
<note>
<para>Make sure that the used port is not blocked to
receive incomming connections from
<application>NanoBSD</application> host by
firewall.</para>
</note>
</step>
<step>
<para>Connect to the host serving new image and execute
<filename>updatep1</filename> sript:</para>
<screen>&prompt.root; <userinput>nc myhost <replaceable>2222</replaceable> | sh updatep1</userinput></screen>
</step>
</procedure>
</sect3>
</sect2>
</sect1>
</chapter>