NanoBSD NG

Motivation

An attempt at pulling the nanobsd development fragmentation back into a single place.

How to get it

Sources can be checked out from subversion:

svn co http://svn.tomjudge.com/freebsd/nanobsd

Or viewed in ViewVC.

New Features

• Disk Image Formats
  • Arm (Imported from BSDRP)
  • Sparc64 (Imported from BSDRP)
  • ISO Image support on i386 and amd64 (Imported from tools/tools/nanobsd/rescue)
• Use geom_label to locate the slices not device names. (Imported from BSDRP)
• Fixes from PR misc/136889 (Imported from BSDRP)
• Modular functions (each function in its own file).
• Modular target support.

Targets

What is a target?

A target is a NanoBSD configuration that can build images for multiple hardware platforms. Each target has the following basic structure (relative to nanobsd installation base):

targets
target/{target name}
target/{target name}/nanobsd.conf
target/{target name}/make.conf.build
target/{target name}/make.conf.install
target/{target name}/Files
target/{target name}/{target arch}/nanobsd.conf
target/{target name}/{target arch}/make.conf.build
target/{target name}/{target arch}/make.conf.install
target/{target name}/{target arch}/Files

Configuration processing

Each of the configuration files in the base of the target are processed first at the relevant stages. After these have been processed then the script will check to see if there is a config file in the target architecture sub directory and include it to override options on per platform basis.

Restricting valid platforms for a target

You can add lines like those that follow to the nanobsd.conf in base of the target to restrict the supported architectures:

case ${NANO_ARCH} 
in 
i386)
    ;;
*)
    echo "$0: Target ${NANO_TARGET} does not support the requested architecture ${NANO_ARCH}" >&2 
    exit 1
esac

This snippet will allow the target to built only on i386 systems.

How it works

1. Setup default config
2. Parse config file
3. Setup build
   1. Clean out build tree (optional)
4. Build
   1. Generate make.conf.build
   2. Build World
   3. Build Kernel
5. Generate the installed world
   1. Clean out _.w
   2. Generate make.conf.install
   3. Install world (make installworld)
   4. Install etc (make distribution)
   5. Customize install for nanobsd
   6. Setup nanobsd etc
   7. Install kernel
   8. Run all scripts registeres with customize_cmd
   9. Setup nanobsd disk layout for ramdisks
   10. Prune empty dirs in /usr
   11. Run all scripts registered with late_customize_cmd
6. Create the disk image
7. Run last_orders.

Functions

In the original nanobsd there is a core set of functions embedded in the shell script and if you want to make changes to them you have to redefine them; also if you wanted to add extra functions you would normally end up defining them in the config file. Personally I find this solution rather ugly, so one of the main features of NanoBSD NG is to split each function into a separate file.

Source Build Functions

build_kernel

Builds the kernel specified in NANO_KERNEL

build_world

Builds the world from the specified source directory.

clean_build

Cleanup

clean_world

Cleanup

install_etc

Use distribution target to install files for /etc and create an empty make.conf

install_kernel

Installs the kernel specified in NANO_KERNEL

install_world

Install world.

make_conf_build

Concatenate all target make.conf.build's into the build environment.

make_conf_install

Concatenate all the target make.conf.build's and make.conf.install's into the build environment.

prune_usr

Remove empty directories from under /usr

setup_nanobsd

Configure the filesystem layout to work in the nanobsd fasion.

setup_nanobsd_etc

Configure settings under /etc in the image to work with nanobsd.

Storage Definition Functions

These functions setup the following variables based on the manufacturer/type and size of the media:

• NANO_HEADS
• NANO_SECTS
• NANO_MEDIASIZE

FlashDevice

This function takes manufacturer name and size as arguments.

UsbDevice

This functions takes generic-hdd/generic-fdd and a size as arguments.

Image Building Functions

NanoBSD currently provides support for creating disk images for the following platforms:

• amd64
• arm
• i386
• sparc64

Platform support is provided by create_{arch}_diskimage functions.

Customization Functions

These functions are covered in detail in the customization section of usage.

Utility Functions

pprint

Pretty print a log message at a level.

run_customize

Run the commands registered with customize_cmd

run_late_customize

Run the commands registered with late_customize_cmd

How to use it

This assumes we are creating a target called: tiny.

Basics

Check out a working copy of NanoBSD NG:

cd /usr/local
svn co http://svn.tomjudge.com/freebsd/nanobsd nanobsd
cd nanobsd

I would recommend you take a look at targets/default/nanobsd.conf, this file contains the default settings for the configuration options.

Now you need create the target directory and create some config files:

mkdir targets/tiny

We are going to put the following settings in targets/tiny/nanobsd.conf

NANO_NAME=TINY
NANO_SRC=/usr/src
NANO_KERNEL=GENERIC
NANO_IMAGES=2
 
FlashDevice Sandisk 2g

If you want to make a bootable CD (you will need cdrtools installed) then you can replace the FlashDevice line with:

NANO_IMAGE_TYPE=cd

Now you can place tunable knobs (see src.conf(5) and make.conf(5)) to the the targets build configuration files:

We don't bind or games in our build so we add the following to targets/tiny/make.conf.build

WITHOUT_BIND=YES
WITHOUT_GAMES=YES

We also don't want to install a tool chain into the image so we add the following to targets/tiny/make.conf.install

WITHOUT_TOOLCHAIN=YES

Now we can generate the build:

./nanobsd.sh -t tiny

If we want to cross build an amd64 image we can do the following:

./nanobsd.sh -t tiny -a amd64

Customization

The nanobsd framework is very flexiable and will allow you to customize the created image in any way you want. The system ships with a number of functions out the box to help you customize you images.

You can register customization functions to run using one of the following configuration directives in your nanobsd.conf.

customize_cmd

Register a command to run as part of the normal customization process.

late_customize_cmd

Register a command to run as part of the late customization process.

Example:

customize_cmd cust_pkg
customize_cmd cust_console_serial

Console Settings

The variable NANO_SERIAL_SPEED is used by all of the console customization functions to set the speed of the serial ports. This variable should contain the port speed in bps. The default speed is 9600 baud.

cust_console_dual

Configure the image in dual console mode. This will activate the serial console and VGA console on the system and allow logins on the serial ports as well as the VGA console.

cust_console_serial

Configure the image to only have a serial console. This will activate the serial console and disable the VGA console.

cust_console_vga

This will set the VGA console to be the main console but will also activate the serial ports to access VT100 logins.

Package Installation

The system includes two functions to help you install packages in your images. These functions are only compatible with image creation for the same target architecture as the host environment. The only notable exception to this is building i386 images on amd64 hosts, this should work but at the time of writing is untested.

cust_pkg

This function copies the packages from targets/{target}/{target arch}/Pkg into the image and installs them with pkg_add.

cust_pkg_fetch

This function looks for lists of packages to be installed in the following files: targets/{target}/package.list and targets/{target}/{target arch}/package.list. For each file the script will iterate though the lines executing pkg_add -r on each entry. This function also temporarily copies the hosts resolv.conf into the image so that DNS works.

Packages can have post customize functions associated with them that are called at the end of the standard customization phase of the build. These are useful for example to correct the permissions of files that have been copied into the image with cust_install_files. These functions live in functions/pacakges/pkg_{package_name}. Some example functions are included with nanobsd.

Other Functions

cust_allow_ssh_root

Set "PermitRootLogin yes" in sshd_config

cust_install_files

Install files stored in the following Files directories:

• targets/default/Files
• targets/{target}/Files
• targets/{target}/{target arch}/Files

cust_remove_paths

This function looks for files containing lists of paths to remove from the image in the following files: targets/{target}/remove.list and targets/{target}/{target arch}/remove.list

TODO

Incorporate the following PR's

• PR:151695
• PR:151696
• PR:151697
• PR:151698

Possible Targets

• http://www.db.net/hamfreesbie/