Date: Mon, 13 Mar 2006 19:22:07 +0000 (UTC) From: Daniel Gerzo <danger@rulez.sk> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/94419: [patch] NanoBSD chapter for Handbook Message-ID: <20060313192207.D7488483FB8@tomas.elvandar.org> Resent-Message-ID: <200603131930.k2DJU6Ev094335@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060313192207.D7488483FB8>