Skip to content

Home

Jump to bottom Edit New page
ocochard edited this page Mar 6, 2012 · 4 revisions

Table of Contents

NanoBSD NG

Motivation

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

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
git clone git://github.com/amishHammer/NanoBSD-NG.git 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







Possible Targets







              


              

                
                   Add a custom footer
              

          



  
          

            

              

                
                   Add a custom sidebar
              


            
Clone this wiki locally