git: f2a33a330d - main - articles/nanobsd: Add section on customizing NanoBSD
Daniel Ebdrup Jensen
debdrup at FreeBSD.org
Tue Jan 19 02:17:10 UTC 2021
The branch main has been updated by debdrup:
URL: https://cgit.FreeBSD.org/doc/commit/?id=f2a33a330d5ac238aa9b2f1c4fadb9f7265577d5
commit f2a33a330d5ac238aa9b2f1c4fadb9f7265577d5
Author: Yoan Adida <yoanadida at gmail.com>
AuthorDate: 2021-01-17 10:55:07 +0000
Commit: Daniel Ebdrup Jensen <debdrup at FreeBSD.org>
CommitDate: 2021-01-19 02:16:17 +0000
articles/nanobsd: Add section on customizing NanoBSD
nanobsd.sh can be passed several options, and having this documented is
a good idea, as it even includes the ability to customize the
third-party software on the NanoBSD image.
While here, fix up some uses of applications tags, and some incorrect
capitalization.
Submitted by: Yoan Adida <yoanadida at gmail.com> (previous version)
Reviewed by: bcr, imp, wblock (some of an earlier version),
Mina Galić <me at igalic.co>, PauAmma
Differential Revision: https://reviews.freebsd.org/D7406
---
en_US.ISO8859-1/articles/nanobsd/article.xml | 407 +++++++++++++++++++++++++--
1 file changed, 387 insertions(+), 20 deletions(-)
diff --git a/en_US.ISO8859-1/articles/nanobsd/article.xml b/en_US.ISO8859-1/articles/nanobsd/article.xml
index 16623c3486..29293887af 100644
--- a/en_US.ISO8859-1/articles/nanobsd/article.xml
+++ b/en_US.ISO8859-1/articles/nanobsd/article.xml
@@ -28,8 +28,8 @@
<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>
+ for use on a USB key, memory card or other mass
+ storage media.</para>
</abstract>
</info>
@@ -38,10 +38,11 @@
<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><application>NanoBSD</application> is a tool developed by
+ &a.phk.email; and now maintained by &a.imp.email;. It
+ creates a &os; system image for embedded applications,
+ suitable for use on a USB key, memory card or other mass
+ storage media.</para>
<para>It can be used to build specialized install images, designed
for easy installation and maintenance of systems commonly called
@@ -190,6 +191,148 @@
storage medium.</para>
</callout>
</calloutlist>
+
+ <sect3>
+ <title>Options When Building a NanoBSD Image</title>
+
+ <para>When building a <application>NanoBSD</application>
+ image, several build options can be passed to
+ <filename>nanobsd.sh</filename> on the
+ command line. These options can have a significant
+ impact on the build process.</para>
+
+ <para>Some options are for verbosity purposes:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>-h</literal>: prints the help
+ summary page.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-q</literal>: makes output quieter.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-v</literal>: makes output more
+ verbose</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Some other options can be used to restrict the
+ building process. Sometimes it is not necessary to
+ rebuild everything from sources, especially if an
+ image has already been built, and only little change
+ is made.</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>-k</literal>: do not build the
+ kernel</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-w</literal>: do not build world</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-b</literal>: do not build either
+ kernel and world</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-i</literal>: do not build a disk
+ image at all. As a file will not be created, it
+ will not be possible to &man.dd.1; it to a
+ storage media.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-f</literal>: do not build a disk
+ image of the first partition (which is useful for
+ upgrade purposes)</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>-n</literal>: add <literal>-DNO_CLEAN</literal>
+ to <buildtarget>buildworld</buildtarget>,
+ <buildtarget>buildkernel</buildtarget>. Also,
+ all the files that have already been built in a
+ previous run are kept.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A configuration file can be used to tweak as
+ many elements as desired. Load it with <option>-c</option></para>
+
+ <para>The last options are:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>-K</literal>: do not install a kernel.
+ A disk image without a kernel will not be able
+ to achieve a normal boot sequence.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>The Complete Image Building Process</title>
+
+ <para>The complete image building process is going through
+ a lot of steps. The exact steps taken will depend on the
+ chosen options when starting the script. Assuming the
+ script is run with no particular options, this is what
+ will happen.</para>
+
+ <orderedlist>
+ <listitem><para><literal>run_early_customize</literal>:
+ commands that are defined in a supplied configuration
+ file.</para></listitem>
+ <listitem><para><literal>clean_build</literal>: Just cleans
+ the build environment by deleting the previously built files.</para></listitem>
+ <listitem><para><literal>make_conf_build</literal>: Assemble
+ make.conffrom the <literal>CONF_WORLD</literal> and
+ <literal>CONF_BUILD</literal> variables.</para></listitem>
+ <listitem><para><literal>build_world</literal>: Build world.</para></listitem>
+ <listitem><para><literal>build_kernel</literal>: Build the
+ kernel files.</para></listitem>
+ <listitem><para><literal>clean_world</literal>: Clean the
+ destination directory.</para></listitem>
+ <listitem><para><literal>make_conf_install</literal>:
+ Assemble make.conf from the <literal>CONF_WORLD</literal>
+ and <literal>CONF_INSTALL</literal> variables.</para></listitem>
+ <listitem><para><literal>install_world</literal>: Install
+ all files built during <buildtarget>buildworld</buildtarget>.</para></listitem>
+ <listitem><para><literal>install_etc</literal>: Install
+ the necessary files in the <filename>/etc</filename>
+ directory, based on the <literal>make distribution</literal>
+ command.</para></listitem>
+ <listitem><para><literal>setup_nanobsd_etc</literal>: the
+ first configuration specific to <application>NanoBSD</application>
+ takes place at this stage. The <filename>/etc/diskless</filename> is
+ created and the root filesystem is defined as read-only.</para></listitem>
+ <listitem><para><literal>install_kernel</literal>: the
+ kernel and modules files are installed.</para></listitem>
+ <listitem><para><literal>run_customize</literal>: all
+ the customizing routines defined by the user will be called.</para></listitem>
+ <listitem><para><literal>setup_nanobsd</literal>: a special
+ configuration directory layout is setup. The
+ <filename>/usr/local/etc</filename> gets moved to
+ <filename>/etc/local</filename> and a symbolic link is
+ created back from <filename>/etc/local</filename> to
+ <filename>/usr/local/etc</filename>.</para></listitem>
+ <listitem><para><literal>prune_usr</literal>: the empty
+ directories from <filename>/usr</filename> are removed.</para></listitem>
+ <listitem><para><literal>run_late_customize</literal>:
+ the very last custom scripts can be run at this point.</para></listitem>
+ <listitem><para><literal>fixup_before_diskimage</literal>:
+ List all installed files in a metalog</para></listitem>
+ <listitem><para><literal>create_diskimage</literal>: creates
+ the actual disk image, based on the disk geometries provides
+ parameters.</para></listitem>
+ <listitem><para><literal>last_orders</literal>: does nothing
+ for now.</para></listitem>
+ </orderedlist>
+ </sect3>
</sect2>
<sect2>
@@ -280,6 +423,184 @@
details.</para>
</listitem>
</itemizedlist>
+
+ <para>There are many more configuration options that could
+ be relevant depending upon the kind of
+ <application>NanoBSD</application> that is desired.</para>
+
+ <sect4>
+ <title>General Customization</title>
+
+ <para>There are three stages, by design, at which
+ it is possible to make changes that affect the
+ building process, just by setting up a variable in the
+ provided configuration file:</para>
+
+ <itemizedlist>
+
+ <listitem><para><literal>run_early_customize</literal>:
+ before anything else happens.</para></listitem>
+
+ <listitem><para><literal>run_customize</literal>: after all
+ the standard files have been laid out</para></listitem>
+
+ <listitem><para><literal>run_late_customize</literal>: at
+ the very end of the process, just before the actual
+ <application>NanoBSD</application> image is built.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To customize a <application>NanoBSD</application> image, at any of these steps,
+ it is best to add a specific value to one of the corresponding
+ variables.</para>
+
+ <para>The <literal>NANO_EARLY_CUSTOMIZE</literal> variable is
+ used at the first step of the building process. At this point,
+ there is no example as to what can be done using that variable,
+ but it may change in the future.</para>
+
+ <para>The <literal>NANO_CUSTOMIZE</literal> variable is used
+ after the kernel, world and etc configuration files have been
+ installed, and the etc files have been setup as to be a
+ NanoBSD installation. So it is the correct step in the
+ building process to tweak configuration options and add
+ packages, like in the cust_nobeastie example.</para>
+
+ <para>The <literal>NANO_LATE_CUSTOMIZE</literal> variable is
+ used just before the disk image is created, so it is the very
+ last moment to change anything. Remember that the
+ <literal>setup_nanobsd</literal> routine already executed and
+ that the <filename>etc</filename>, <filename>conf</filename>
+ and <filename>cfg</filename>directories and subdirectories are
+ already modified, so it is not time to change them at this
+ point. Rather, it is possible to add or remove specific files.</para>
+ </sect4>
+
+ <sect4>
+ <title>Booting Options</title>
+
+ <para>There are also variables that can change the way the
+ NanoBSD image boots. Two options are passed to
+ &man.boot0cfg.8; to initialize the boot sector of the disk image:</para>
+ <itemizedlist>
+ <listitem><para><literal>NANO_BOOT0CFG</literal></para></listitem>
+ <listitem><para><literal>NANO_BOOTLOADER</literal></para></listitem>
+ </itemizedlist>
+
+ <para>With <literal>NANO_BOOTLOADER</literal> a bootloader
+ file can be chosen. The most common possible options are between
+ <filename>boot0sio</filename> and <filename>boot0</filename>
+ depending on whether the appliance has a serial port or not. It is best
+ to avoid supplying a different bootloader, but it is possible.
+ To do so, it is best to have checked the
+ <link xlink:href="&url.books.handbook;/boot.html">&os; Handbook</link>
+ chapter on the boot process.</para>
+
+ <para>With <literal>NANO_BOOT0CFG</literal>, the booting
+ process can be tweaked, like selecting on which partition the
+ <application>NanoBSD</application> image will actually boot.
+ It is best to check the &man.boot0cfg.8; page before changing
+ the default value of this variable. One option that could be
+ interesting to change is the timeout of the booting procedure.
+ To do so, the <literal>NANO_BOOT0CFG</literal> variable can be
+ changed to <literal>"-o packet -s 1 -m 3 -t 36"</literal>.
+ That way the booting process would start after approximately 2
+ seconds; because it is rare that waiting 10 seconds before
+ actually booting is desired.</para>
+
+ <para>Good to know: the <literal>NANO_BOOT2CFG</literal>
+ variable is only used in the <literal>cust_comconsole</literal>
+ routine that can be called at the
+ <literal>NANO_CUSTOMIZE</literal> step if the appliance has a
+ serial port and all console input and output has to take place through
+ it. Be sure to check the relevant parameters of the serial
+ port, as setting a bad parameter value can make it useless.</para>
+ </sect4>
+
+ <sect4>
+
+ <title>Disk Image Creation</title>
+ <para>In the end of the boot process is the disk image
+ creation. With this step, the <application>NanoBSD</application>
+ script provides a file that can simply be copied onto a disk
+ for the appliance, and that will make it boot and start.</para>
+
+ <para>There are many variable that need to be set just right
+ for the script to produce a usable disk image.</para>
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>NANO_DRIVE</literal> variable must be set
+ to the drive name of the media at runtime. Usually, the
+ default value <literal>ada0</literal>, which represents the first
+ <literal>IDE</literal>/<literal>ATA</literal>/<literal>SATA</literal>
+ device on the appliance is expected to be the correct one, but
+ a different type of storage could also be used - like a USB
+ key, in which case, it would rather be da0.</para>
+ </listitem>
+ <listitem>
+ <para>The <literal>NANO_MEDIASIZE</literal> variable must be
+ set to the size (in 512 bytes sectors) of the storage media
+ that will be used. If you set it wrong, it is possible that
+ the <application>NanoBSD</application> image will not boot
+ at all, and a message at boot time will be warning about
+ incorrect disk geometry.</para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>The <filename>/etc</filename>, <filename>/var</filename>,
+ and <filename>/tmp</filename> directories are allocated as
+ &man.md.4; (malloc) disks at boot time; so their sizes can be
+ tailored to suit the appliance needs. The <literal>NANO_RAM_ETCSIZE</literal>
+ variable sets the size of the <filename>/etc</filename>; and the
+ <literal>NANO_RAM_TMPVARSIZE</literal> variable sets the size of
+ both the <filename>/var</filename> and <filename>/tmp</filename>
+ directory, as <filename>/tmp</filename> is symbolically linked to
+ <filename>/var/tmp</filename>. By default, both malloc disks
+ sizes are set at 20MB each. They can always be changed, but
+ usually the <filename>/etc</filename> does not grow too much
+ in size, so 20MB is a good starting point, whereas the
+ <filename>/var</filename> and especially <filename>/tmp</filename>
+ can grow much larger if not careful about it. For
+ memory constrained systems, smaller filesystem sizes
+ may be chosen.
+ </para>
+ </listitem>
+ <listitem>
+ <para>As <application>NanoBSD</application> is
+ mainly designed to build a system image for an
+ appliance, it is assumed that the storage media used
+ will be relatively small. For that reason,
+ the filesystem that is laid out is configured to have
+ a small block size (4Kb) and a small fragment size (512b).
+ The configuration options of the filesystem can be
+ modified through the <literal>NANO_NEWFS</literal>
+ variable, but the syntax must respect the
+ &man.newfs.8; command format. Also, by default, the
+ filesystem has Soft Updates enabled. The
+ <link xlink:href="&url.books.handbook;">&os; Handbook</link>
+ can be checked about this.</para>
+ </listitem>
+ <listitem>
+ <para>The different partition sizes can be set through the
+ use of <literal>NANO_CODESIZE</literal>,
+ <literal>NANO_CONFSIZE</literal>, and <literal>NANO_DATASIZE</literal>
+ as a multiple of 512 bytes sectors.
+ <literal>NANO_CODESIZE</literal> defines the size of the first
+ two image partitions: <literal>code#1</literal> and
+ <literal>code#2</literal>. They have to be big enough to hold
+ all the files that will be produced as a result of the
+ <literal>buildworld</literal> and <literal>buildkernel</literal>
+ processes. <literal>NANO_CONFSIZE</literal> defines the size
+ of the configuration file partition, so it does not need to be
+ very big; but do not make it so small that it will not hold all
+ configuration files. Finally, <literal>NANO_DATASIZE</literal>
+ defines the size of an optional partition, that can be used
+ on the appliance. The last partition can be used,
+ for example, to keep files created on the fly on disk.</para>
+ </listitem>
+ </itemizedlist>
+ </sect4>
</sect3>
<sect3>
@@ -337,20 +658,43 @@ customize_cmd cust_etc_size</programlisting>
<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>
+ <para>Packages can be added to a <application>NanoBSD</application>
+ image, to provide specific functionalities on the
+ appliance. To do so, either:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Add the <literal>cust_pkgng</literal> to the
+ <literal>NANO_CUSTOMIZE</literal> variable, or</para>
+ </listitem>
+
+ <listitem>
+ <para>Add a <literal>'customize_cmd cust_pkgng'</literal>
+ command in a customized configuration file.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Both methods achieve the same result: launching
+ the <literal>cust_pkgng</literal> routine. This routine
+ will go through <literal>NANO_PACKAGE_DIR</literal>
+ directory to find either all packages or just the list of
+ packages in the <literal>NANO_PACKAGE_LIST</literal> variable.</para>
+ <para>It is common, when installing applications through
+ pkg on a standard &os; environment, that the install
+ process puts configuration files, in the
+ <filename>usr/local/etc</filename> directory, and
+ startup scripts in the <filename>/usr/local/etc/rc.d</filename>
+ directory. So, after the required packages have been
+ installed, they need to be configured in order
+ for them to start right out of the box. To do so,
+ the necessary configuration files have to be installed in the
+ correct directories. This can be achieved by writing
+ dedicated routines or the generic <literal>cust_install_files</literal>
+ routine can be used to lay out files properly from the
+ <filename><replaceable>/usr</replaceable>/src/tools/tools/nanobsd/Files</filename> directory.
+ Usually a statement, sometimes multiple statements,
+ in the <filename>/etc/rc.conf</filename> also needs to be
+ added for each package.</para>
+
</sect3>
<sect3>
@@ -409,6 +753,29 @@ customize_cmd cust_comconsole
customize_cmd cust_install_files
customize_cmd cust_allow_ssh_root
customize_cmd cust_nobeastie</programlisting>
+
+ <para>All the build and install compilation options can be found in
+ the &man.src.conf.5; man page, but not all options can or should be
+ used when building a <application>NanoBSD</application> image.
+ The build and install options should be defined according to the
+ needs of the image being built.</para>
+
+ <para>For example, the ftp client and server might not be needed.
+ Adding <literal>WITHOUT_FTP=TRUE</literal> to a configuration file
+ in the <literal>CONF_BUILD</literal> section will avoid having
+ them built. Also, if the <application>NanoBSD</application>
+ appliance will not be used to build programs then it is possible
+ to add the <literal>WITHOUT_BINUTILS=TRUE</literal> in the
+ <literal>CONF_INSTALL</literal> section; but not
+ in the <literal>CONF_BUILD</literal> section as they will be
+ used to build the <application>NanoBSD</application> image.</para>
+
+ <para>Not building a particular set of programs —
+ through a compilation option — shortens the overall building
+ time and lowers the required size for the disk image,
+ whereas not installing the same specific set of programs
+ does not lower the overall building time.</para>
+
</sect3>
</sect2>
More information about the dev-commits-doc-all
mailing list