====== NanoBSD ======
{{description>Unofficial NanoBSD technical resources}}
====== Externals links about NanoBSD ======

Here are a list of docs and tutorials about NanoBSD:
  *  [[http://www.freebsd.org/doc/en/articles/nanobsd/index.html|Introduction to NanoBSD]] : Official presentation page on FreeBSD website
  *  [[http://www.bsdcan.org/2006/papers/nanobsd.pdf|Building a FreeBSD Appliance With NanoBSD]] (pdf) : Presentation during the BSD Can 2006
  *  [[http://www.freebsd.org/cgi/man.cgi?query=nanobsd&apropos=0&sektion=0&manpath=FreeBSD+8-current&format=html|NanoBSD man page]] : The man page
  *  [[http://www.gitoyen.net/Howto-NanoBSD-quagga-router|Gitoyen NanoBSD quagga router]] (french only) : One of the most close project to this, with a very smart idea of manage configuration by an external svn server and most interressing: A patch for adding ports compilation support

====== Understanding NanoBSD ======

===== What is NanoBSD ? =====

It's a shell script (/usr/src/tools/tools/nanobsd/) that generate embedded FreeBSD image disk.

===== Images generated by NanoBSD =====

After using NanoBSD, you will found a full disk image (_.disk.full) that contains 2 partitions (p1 and p2) (both copy of _.disk.image file).
The file _.disk.image is the light FreeBSD filesystem (in [[http://www.freebsd.org/cgi/man.cgi?query=diskless&apropos=0&sektion=0&manpath=FreeBSD+8.1-RELEASE&format=html|diskless mode]]).
Using 2 partitions permit to use a simple and safe upgrading process: The new _.disk.image file is copied over the non-active partition, and the bootloader is modified for boot on the non-active partition at the next boot. There are the scripts updatep1 and updatep2 for this task.

===== Using NanoBSD =====

NanoBSD manage flash device and prevent fsck by mounting the filesystem read-only.
For saving configuration file, you need to copy /etc into /conf: There is the script save_cfg for this task.

====== Studying NanoBSD ======

===== Command options =====

Here are the command line options of NanoBSD:
<code>
Usage: $0 [-bikqvw] [-c config_file]
  -b      suppress builds (both kernel and world)
  -i      suppress disk image build
  -k      suppress buildkernel
  -n      add -DNO_CLEAN to buildworld, buildkernel, etc
  -q      make output more quite
  -v      make output more verbose
  -w      suppress buildworld
  -c      specify config file
  -h      Display usage information.

</code>

===== Steps =====

Here are the functions steps:

  - clean_build
  - make_conf_build
  - build_world
  - build_kernel
  - clean_world
  - make_conf_install
  - install_world
  - install_etc
  - setup_nanobsd_etc
  - install_kernel
  - run_customize
  - setup_nanobsd
  - prune_usr
  - run_late_customize
  - create_${NANO_ARCH}_diskimage
  - last_orders
===== Variables Table =====

FIXME

^ Name      ^ Value (in BSDRP)     ^ Description ^ 
| CONF_BUILD | | Options to put in make.conf during buildworld only |
| CONF_WORLD | A big list of [[http://phk.freebsd.dk/misc/build_options_stable_8_210741/|WITHOUT_]] | Options to put in make.conf during both build- & installworld |
| CONF_INSTALL | A big list of [[http://phk.freebsd.dk/misc/build_options_stable_8_210741/|WITHOUT_]] too| Options to put in make.conf during installworld only |
| MAKEOBJDIRPREFIX    | /usr/obj/nanobsd.BSDRP.{ARCH}   | object directory |
| NANO_ARCH | i386/amd | Target architecture|
| NANO_BOOT0CFG | -o packet -s 1 -m 3 | Boot0cfg configuration mode |
| NANO_CONFSIZE | 2048 | Size of configuration file system in 512 bytes sectors |
| NANO_CUSTOMIZE | | Customize commands |
| NANO_DATASIZE | 2048 | Size of data file system in 512 bytes sectors |
| NANO_DISKIMGDIR | /usr/obj/nanobsd.BSDRP.{ARCH}  | The directory to put the final images |
| NANO_DRIVE | ad0 (TO ADD in BSDRP make!) | The drive name of the media at runtime | 
| NANO_GLABEL_SYS | BSDRP | glabel name for system partition |
| NANO_GLABEL_CFG | cfg | glabel name for configuration partition |
| NANO_GLABEL_DATA | data | glabel name for data partition |
| NANO_IMAGES | 2 | Number of code images on media (1 or 2) |
| NANO_IMGNAME | BSDRP.img | The default name for any image we create |
| NANO_INIT_IMG2 | 0 | What to do with the second image partition: 0 (empty), 1 (copy twice the image) |
| NANO_KERNEL | BSDRP-I386 / BSDRP-AMD64 | Name of the kernel config file |
| NANO_LATE_CUSTOMIZE | | Late customize commands |
| NANO_MAKE_CONF_INSTALL | /usr/obj/nanobsd.BSDRP.{ARCH}/make.conf.install | |
| NANO_MAKE_CONF_BUILD | /usr/obj/nanobsd.BSDRP.{ARCH}/make.conf.build | |
| NANO_MD_BACKING | file | Backing type of md(4) device (file or swap) |
| NANO_MEDIASIZE | 1200000 | Target media size in 512 bytes sectors |
| NANO_NAME | BSDRP | Name of the obj dir |
| NANO_NEWFS | -b 4096 -f 512 -i 8192 -O1 -m 2 -U | Newfs paramters to use |
| NANO_OBJ | /usr/obj/nanobsd.BSDRP.{ARCH} | Object tree directory |
| NANO_PACKAGE_DIR | /usr/src/tools/tools/nanobsd/BSDRP/Pkg | Where cust_pkg() finds packages to install |
| NANO_PMAKE | make -j 3 | Parallel Make |
| NANO_RAM_ETCSIZE | 10204 | Size of the /etc ramdisk in 512 bytes sectors |
| NANO_RAM_TMPVARSIZE | 20480 | Size of the /tmp+/var ramdisk in 512 bytes sectors |
| NANO_SRC | /usr/src | Source tree directory |
| NANO_TOOLS | tools/tools/nanobsd/BSDRP | Where nanobsd additional files live under the source tree |
| NANO_WORLDDIR | /usr/obj/nanobsd.BSDRP.{ARCH}/_.w | Target World directory |


===== Functions Table =====

FIXME

^ Name      ^ Description ^ 
| build_kernel   | Copy kernel config file and Build Kernel |
| build_world    | Run Build World     |
| clean_build    | Delete and create object directory     |
| clean_world    | Clean and create object directory     |
| cust_install_files | Copy all files under Files to nanobsd target |
| FlashDevice    | Load FlashDevice.sub     |
| install_world    | Install all binary (make installworld)       |
| install_etc | Install /etc (make distribution|
| install_kernel | Install kernel (make installkernel) |
| make_conf_build | Construct build make.conf using $CONF_WORLD and $CONF_BUILD      |
| make_conf_install | Construct install make.conf using $CONF_WORLD and $CONF_BUILD    |
| prune_usr | Remove all empty directories in target /usr |
| run_customize | run customize scripts (commands in $NANO_CUSTOMIZE) |
| run_late_customize | run late customize scripts (commands in $NANO_LATE_CUSTOMIZE and cust_ functions) |
| setup_nanobsd | configure nanobsd setup: Move /usr/local/etc to /etc/local |
| setup_nanobsd_etc | configure target nanobsd /etc: enable diskless, enable r/o of /, create fstab |
| UsbDevice | USB device geometries |
| create_${NANO_ARCH}_diskimage | Build disk image (partition, format, bootloader, etc.)|
| last_orders | Empty function to be customized by user (ex: copy diskimage to other place)|

===== NanoBSD logs files =====

^ Name      ^ Description ^ 
| _.bk    | Build Kernel log    |
| _.bw    | Build World log     |
| _.di | Disk image creation log |
| _.dl    | nanobsd setup creation log (/etc, /conf, etc..)   |
| _.du    | nanobsd disk usage (du) output       |
| _.env | All environnement used during nanobsd runs |
| _.etc | Install etc log |
| _.fdisk | File used for fdisk the nanoBSD image      |
| _.ik | Install kernel log files    |
| _.iw | Install world log files |
| _.mtree | Light mtree file of the nanoBSD image |



====== BSDRP patches for NanoBSD ======

===== Port compiling patches =====

This patches is an improvement of the method used by [[http://www.gitoyen.net/Howto-NanoBSD-quagga-router|Gitoyen NanoBSD router]].

It replaces the installation of package by compiling ports during NanoBSD image build: This permit to add ports during build process of NanoBSD images.

This patch support cross-compilation i386 ports from an amd64 release.

You can found this patches as the function add_port () in the [[https://github.com/ocochard/BSDRP/blob/master/BSDRP/BSDRP.nano|BSDRP nano configuration file]].

But the best solution should to use poudriere to generate packages.