path: root/en_US.ISO8859-1/articles/nanobsd/article.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:lang="en"> <info>
    <title>Introduction to NanoBSD</title>

    <authorgroup>
      <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname></author>
    </authorgroup>

    <copyright>
      <year>2006</year>
      <holder>The FreeBSD Documentation Project</holder>
    </copyright>

    <legalnotice xml:id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.general;
    </legalnotice>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>This document provides information about the
	<application>NanoBSD</application> tools, which can be used to
	create &os; system images for embedded applications, suitable
	for use on a Compact Flash card (or other mass storage
	medium).</para>
    </abstract>
  </info>

  <sect1 xml:id="intro">
    <title>Introduction to NanoBSD</title>

    <indexterm><primary>NanoBSD</primary></indexterm>

    <para><application>NanoBSD</application> is a tool currently
      developed by &a.phk.email;.  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 xml:id="howto">
    <title>NanoBSD Howto</title>

    <sect2 xml:id="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>/cfg</filename> directory
	    at run time.</para>
	</listitem>
      </itemizedlist>

      <para>These partitions are normally mounted read-only.</para>

      <para>The <filename>/etc</filename> and
	<filename>/var</filename> directories are
	&man.md.4; (malloc) disks.</para>

      <para>The configuration file partition persists under the
	<filename>/cfg</filename> directory.  It
	contains files for <filename>/etc</filename>
	directory and is briefly mounted read-only right after the
	system boot, therefore it is required to copy modified files
	from <filename>/etc</filename> back to the
	<filename>/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>/cfg</filename> should be mounted
	  only at boot time and while overriding the configuration
	  files.</para>

	<para>Keeping <filename>/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 (like 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><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 xml:id="nbsd-cd"/>
&prompt.root; <userinput>sh nanobsd.sh</userinput> <co xml:id="nbsd-sh"/>
&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co xml:id="nbsd-cd2"/>
&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co xml: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
	<filename>myconf.nano</filename> 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
	  <buildtarget>buildworld</buildtarget> and
	  <buildtarget>installworld</buildtarget> 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 <buildtarget>buildworld</buildtarget> stage of
	      the build.</para>
	  </listitem>

	  <listitem>
	    <para><literal>CONF_INSTALL</literal> &mdash; Options
	      passed to the <buildtarget>installworld</buildtarget>
	      stage of the build.</para>
	  </listitem>

	  <listitem>
	    <para><literal>CONF_WORLD</literal> &mdash; Options passed
	      to both the <buildtarget>buildworld</buildtarget> and
	      the <buildtarget>installworld</buildtarget> stage of the
	      build.</para>
	  </listitem>

	  <listitem>
	    <para><literal>FlashDevice</literal> &mdash; Defines what
	      type of media to use.  Check
	      <filename>FlashDevice.sub</filename> 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=baz" &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>/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
	      <systemitem class="username">root</systemitem> to login
	      via &man.sshd.8;.</para>
	  </listitem>

	  <listitem>
	    <para><literal>cust_install_files</literal> &mdash;
	      Installs files from the
	      <filename>nanobsd/Files</filename>
	      directory, which contains some useful scripts for system
	      administration.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Adding Packages</title>

	<para>Packages can be added to a
	  <application>NanoBSD</application> image using a custom
	  function.  The following function will install all the
	  packages located in
	  <filename>/usr/src/tools/tools/nanobsd/packages</filename>:</para>

	<programlisting>install_packages () (
mkdir -p ${NANO_WORLDDIR}/packages
cp /usr/src/tools/tools/nanobsd/packages/* ${NANO_WORLDDIR}/packages
cp $(which pkg-static) ${NANO_WORLDDIR}/
chroot ${NANO_WORLDDIR} sh -c 'cd packages; /pkg-static add *;cd ..;'
rm -rf ${NANO_WORLDDIR}/packages ${NANO_WORLDDIR}/pkg-static
)
customize_cmd install_packages</programlisting>
      </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='
WITHOUT_KLDLOAD=YES
WITHOUT_NETGRAPH=YES
WITHOUT_PAM=YES
'

CONF_INSTALL='
WITHOUT_ACPI=YES
WITHOUT_BLUETOOTH=YES
WITHOUT_FORTRAN=YES
WITHOUT_HTML=YES
WITHOUT_LPR=YES
WITHOUT_MAN=YES
WITHOUT_SENDMAIL=YES
WITHOUT_SHAREDOCS=YES
WITHOUT_EXAMPLES=YES
WITHOUT_INSTALLLIB=YES
WITHOUT_CALENDAR=YES
WITHOUT_MISC=YES
WITHOUT_SHARE=YES
'

CONF_WORLD='
WITHOUT_BIND=YES
WITHOUT_MODULES=YES
WITHOUT_KERBEROS=YES
WITHOUT_GAMES=YES
WITHOUT_RESCUE=YES
WITHOUT_LOCALES=YES
WITHOUT_SYSCONS=YES
WITHOUT_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 <filename>_.disk.full</filename>
	    (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>/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 preferred, 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 preferred, 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.ftpd.8; 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 incoming 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> script:</para>

	    <screen>&prompt.root; <userinput>nc myhost <replaceable>2222</replaceable> | sh updatep1</userinput></screen>
	  </step>
	</procedure>
      </sect3>
    </sect2>
  </sect1>

  <index/>
</article>