NanoBSD tru2life style :-)

Table of Contents

Introduction to NanoBSD

NanoBSD Howto

references

NanoBSD files

NanoBSD script

NanoBSD obj files/directories

tru2life NanoBSD packages

Man Pages useful with NanoBSD

Commands used with NanoBSD

This document provides information about the NanoBSD tools, which can be used to create FreeBSD system images for embedded applications, suitable for use on a Compact Flash card (or other mass storage medium).

Introduction to NanoBSD

NanoBSD is a tool currently developed by Poul-Henning Kamp <phk@FreeBSD.org> . It creates a FreeBSD system image for embedded applications, suitable for use on a Compact Flash card (or other mass storage medium).

It can be used to build specialized install images, designed for easy installation and maintenance of systems commonly called “computer appliances”. 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.

The features of NanoBSD include:

• Ports and packages work as in FreeBSD -- Every single application can be installed and used in a NanoBSD image, the same way as in FreeBSD.

• No missing functionality -- If it is possible to do something with FreeBSD, it is possible to do the same thing with NanoBSD, unless the specific feature or features were explicitly removed from the NanoBSD image when it was created.

• Everything is read-only at run-time -- It is safe to pull the power-plug. There is no necessity to run fsck(8) after a non-graceful shutdown of the system.

• Easy to build and customize -- 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.

NanoBSD Howto

The design of NanoBSD

Once the image is present on the medium, it is possible to boot NanoBSD. The mass storage medium is divided into three parts by default:

• Two image partitions: code#1 and code#2.

• The configuration file partition, which can be mounted under the /cfg directory at run time.

These partitions are normally mounted read-only.

The /etc and /var directories are md(4) (malloc) disks.

The configuration file partition persists under the /cfg directory. It contains files for /etc directory and is briefly mounted read-only right after the system boot, therefore it is required to copy modified files from /etc back to the /cfg directory if changes are expected to persist after the system restarts.

# vi /etc/resolv.conf
  [...]
# mount /cfg
# cp /etc/resolv.conf /cfg
# umount /cfg

Building a NanoBSD image

A NanoBSD image is built using a simple nanobsd.sh shell script, which can be found in the /usr/src/tools/tools/nanobsd directory. This script creates an image, which can be copied on the storage medium using the dd(1) utility.

The necessary commands to build a NanoBSD image are:

(1) # cd /usr/src/tools/tools/nanobsd
(2) # sh nanobsd.sh -c nanobsd.conf
(3) # cd /usr/obj/nanobsd.${NANO_NAME}(ie: full, custom, tru2life)...
(4) # dd if=_.disk.full of=/dev/da0 bs=64k

1. Change the current directory to the base directory of the NanoBSD build script.
2. Start the build process.
3. Change the current directory to the place where the built images are located.
4. Install NanoBSD onto the storage medium.

Customizing a NanoBSD image

This is probably the most important and most interesting feature of NanoBSD.

This is also where you will be spending most of the time when developing with NanoBSD.

Invocation of the following command will force the nanobsd.sh to read its configuration from the nanobsd.conf file located in the current directory:

# sh nanobsd.sh -c conf.nano

Customization is done in two ways:

• Configuration options

• Custom functions

2.3.1 Configuration options

With configuration settings, it is possible to configure options passed to both the buildworld and installworld stages of the NanoBSD build process, as well as internal options passed to the main build process of NanoBSD. 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 FreeBSD even more, until it will consists ofjust the kernel and two or three files in the userland.

The configuration file consists of configuration options, which override the default values. The most important directives are:

• NANO_NAME -- Name of build (used to construct the workdir names).

• NANO_SRC -- Path to the source tree used to build the image.

• NANO_KERNEL -- Name of kernel configuration file used to build kernel.

• CONF_BUILD -- Options passed to the buildworld stage of the build.

• CONF_INSTALL -- Options passed to the installworld stage of the build.

• CONF_WORLD -- Options passed to both the buildworld and the installworld stage of the build.

• nanobsd_dev -- Defines what type of media to use. Check the nanobsd.dev file for more details.

2.3.2 Custom functions

It is possible to fine-tune NanoBSD using shell functions in the configuration file. The following example illustrates the basic model of custom functions:

cust_foo()
(
  echo "bar=topless" > \
  ${NANO_WORLDDIR}/etc/foo
)

customize_cmd cust_foo

A more useful example of a customization function is the following, which changes the default size of the /etc directory from 5MB to 30MB:

cust_etc_size()
(
  cd ${NANO_WORLDDIR}/conf
  echo 30000 > default/etc/md_size
)

customize_cmd cust_etc_size

There are a few default pre-defined customization functions ready for use:

• cust_comconsole -- Disables getty(8) on the VGA devices (the /dev/ttyv* device nodes) and enables the use of the COM1 serial port as the system console.

• cust_allow_ssh_root -- Allow root to login via sshd(8).

• cust_install_files -- Installs files from the nanobsd/Files directory, which contains some useful scripts for system administration.

2.3.3 Adding packages

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

install_packages()
(
  mkdir -p ${NANO_WORLDDIR}/packages

  cp /usr/src/tools/tools/nanobsd/packages/* ${NANO_WORLDDIR}/packages

  chroot ${NANO_WORLDDIR} sh -c 'cd packages; pkg_add -v *;cd ..;'

  rm -rf ${NANO_WORLDDIR}/packages
)

customize_cmd install_packages

2.3.4 Configuration file example

A complete example of a configuration file for building a custom NanoBSD image can be:

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
'

nanobsd_dev 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

Updating NanoBSD

The update process of NanoBSD is relatively simple:

To install new image onto the running NanoBSD system, it is possible to use either the updatep1 or updatep2 script located in the /root directory, depending from which partition is running the current system.

According to which services are available on host serving new NanoBSD image and what type of transfer is preferred, it is possible to examine one of these three ways:

2.4.1 Using ftp(1)

If the transfer speed is in first place, use this example:

# ftp myhost get _.disk.image "| sh updatep1"

2.4.2 Using ssh(1)

If a secure transfer is preferred, consider using this example:

# ssh myhost cat _.disk.image.gz | zcat | sh updatep1

2.4.3 Using nc(1)

Try this example if the remote host is not running neither ftp(1) or sshd(8) service:

NanoBSD References

Poul-Henning Kamp, Author of NanoBSD...

FreeBSD Mailing Lists:

FreeBSD Documents

The original NanoBSD article is here (tru2life copy): NanoBSD

The original NanoBSD article is here (at FreeBSD site): NanoBSD

For questions about FreeBSD, read the: FreeBSD Documents.

FreeBSD documents, can be downloaded from: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

NanoBSD files

nanobsd.dev

Info on nanobsd.dev file use at tru2life...
Clone/copy of original FlashDevice.sub file...
Descriptions added for pny4g, pny8g, sandisk256m, and kingston256m usb flash drives.

nanobsd.conf

config file for NanoBSD (tru2life style of course :-)
Includes knobs for Files/root/updatep1 and Files/root/updatep2

nanobsd.sh

NanoBSD Build Script
(includes functions from updatep1 and updatep2 with knobs in nanobsd.conf)...

build_options

Local copy of build_options from Poul-Henning Kamp's web site...

docs/

NanoBSD Documents

orig/

Original files (b4 i hacked em :-)

Pkg/

Packages installed in the tru2life NanoBSD image

Files/

NanoBSD update support scripts

change_password

save_sshkeys

updatep1

updatep2

NanoBSD script

Running the tru2life version of the script nanobsd.sh requires a bit more setup up front than the original version.

Much of the original flavor has been retained, so it should not be hard to follow...

The following shows how to go about it:

• Edit the file nanobsd.conf to configure settings.
• View/edit the file nanobsd.dev to ensure your desired device is present.
• Run the command "sh nanobsd.sh -c nanobsd.conf".

tru2life NanoBSD obj files/directories

Current directory is /usr/obj/nanobsd.tru2life/

Subdirectories:

    drwxr-xr-x    2 root     wheel        512 Oct 12 10:20 _.mnt
    drwxr-xr-x   18 root     wheel        512 Oct 12 10:19 _.w
    drwxr-xr-x    3 root     wheel        512 Oct 12 08:24 usr

Files:

    -rw-r--r--    1 root     wheel    2526128 Oct 12 10:15 _.bk
    -rw-r--r--    1 root     wheel    11122475 Oct 12 09:49 _.bw
    -rw-r--r--    1 root     wheel       3958 Oct 12 10:44 _.di
    -rw-r--r--    1 root     wheel    -289288192 Oct 12 10:36 _.disk.full
    -rw-r--r--    1 root     wheel    1990485504 Oct 12 10:44 _.disk.image
    -rw-r--r--    1 root     wheel         53 Oct 12 10:19 _.dl
    -rw-r--r--    1 root     wheel      21823 Oct 12 10:25 _.du
    -rw-r--r--    1 root     wheel       1045 Oct 12 08:24 _.env
    -rw-r--r--    1 root     wheel      12373 Oct 12 10:18 _.etc
    -rw-r--r--    1 root     wheel        134 Oct 12 10:20 _.fdisk
    -rw-r--r--    1 root     wheel     111667 Oct 12 10:19 _.ik
    -rw-r--r--    1 root     wheel    1615879 Oct 12 10:18 _.iw
    -rw-r--r--    1 root     wheel    1130704 Oct 12 10:25 _.mtree
    -rw-r--r--    1 root     wheel          4 Oct 12 10:15 make.conf

 clean_build()
 ...
 printenv > ${MAKEOBJDIRPREFIX}/_.env

build_world()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.bw"

build_kernel()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.bk"

install_world()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.iw"

install_etc()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.etc"

install_kernel()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.ik"

run_customize()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.cust.$c"

setup_nanobsd()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.dl"

create_i386_diskimage()
(
  ...
  echo "### log: ${MAKEOBJDIRPREFIX}/_.di"

create_i386_diskimage()
(
  ...
    awk '
    {
      #-----------------------------------------------------------------------
      # ...top.[awk.code]...
      #-----------------------------------------------------------------------
      ...
      #-----------------------------------------------------------------------
      # ...end.[awk.code]...
      #-----------------------------------------------------------------------
    }

    ' > ${MAKEOBJDIRPREFIX}/_.fdisk
  ...
)

# 7807590 2 63 255 0 2048 -1
g c486 h255 s63
p 1 165 63 3887667
p 2 165 3887793 3887667
p 3 165 7775460 16065
p 4 165 7791525 7807590

tru2life NanoBSD packages

Man Pages useful with NanoBSD

Commands used with NanoBSD

command	man page	command	man page	command	man page	command	man page
command	man page	command	man page	command	man page	command	man page
awk		basename		boot0cfg		bsdlabel
case		cd		chflags		chroot
cp		cut		dd		df
echo		expr		fdisk		find
grep		for		fsck_ffs		getopt
if		ln		ls		mdconfig
mkdir		mount		mtree		nc
newfs		passwd		pkg_add		print
printenv		printf		rc.conf		rm
rmdir		sed		set -e		ssh
touch		tr		trap		umount
while		xargs