User Tools

Site Tools


documentation:technical_docs:nanobsd

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

documentation:technical_docs:nanobsd [2011/12/27 14:37] (current)
Line 1: Line 1:
 +====== 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 ======
 +
 +All this patchs were wrote for NanoBSD included in FreeBSD 8.1-Release.
 +
 +===== AMD64 support =====
 +
 +This very small patch permit to generate NanoBSD amd64 image.
 +
 +This patch [[http://​www.freebsd.org/​cgi/​query-pr.cgi?​pr=135588&​cat=|was proposed to be added into the official NanoBSD]] the Mon, 15 Jun 2009 05:51:53 GMT and was included in FreeBSD 8.1.
 +
 +===== Label support: No more hardcoded ad0/da0 for root filesystem =====
 +
 +The image of NanoBSD hardcode the device type use for mounting the root filesystem:
 +  * ad0 for the first ATA device
 +  * da0 for the first SCSI device (used for USB key)
 +This mean, that a "​ad0-nanobsd"​ image can't be installed on a USB key: It will not correctly boot (because the fstab will indicate the root filesystem on the ad0 drive, but when booting from a USB key, it's on da0).
 +
 +The pfSense team meet the same problem, and Scott Ullrich give me this big advice: Use label in your fstab for avoiding this problem!
 +
 +Then, here is the patch, and the new update script (merged updatep1 and updatep2 nanoBSD script):
 +
 +  * [[http://​bsdrp.svn.sourceforge.net/​viewvc/​bsdrp/​tags/​1.0/​patches/​nanobsd.glabel.patch|nanobsd.glabel.patch]]
 +  * [[http://​bsdrp.svn.sourceforge.net/​viewvc/​bsdrp/​trunk/​Files/​usr/​local/​sbin/​upgrade|New update script that support glabel]]
 +
 +This patch [[http://​lists.freebsd.org/​pipermail/​freebsd-embedded/​2009-July/​000791.html|was proposed to be added into NanoBSD on the FreeBSD-embedded mailing-list]] the Sun Jul 5 22:12:38 UTC 2009, and a modified version is committed in -current.
 +
 +===== 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 [[http://​bsdrp.svn.sourceforge.net/​viewvc/​bsdrp/​trunk/​BSDRP.nano|BSDRP nano configuration file]].
 +
 +===== Improving mtree generation =====
 +
 +NanoBSD generate a mtree reference file, but for system security audit the default nanoBSD mtree file didn't contain enough parameters
 +
 +This patch add sha256digest to mtree function of nanoBSD:
 +
 +[[http://​bsdrp.svn.sourceforge.net/​viewvc/​bsdrp/​tags/​1.0/​patches/​nanobsd.mtree.patch|nanobsd.mtree.patch]]
 +
 +===== sparc64 support (work in progress) =====
 +
 +This patch is to be used with the nanobsd glabel patch:
 +
 +[[http://​bsdrp.svn.sourceforge.net/​viewvc/​bsdrp/​tags/​1.0/​patches/​nanobsd.sparc64.patch|nanobsd.sparc64.patch]]
 +
 +<note important>​Cross-compilation of port is not possible: This patch is usable from a sparc64 computer only.
 +
 +Upgrading nanoBSD image is not supported: There is no FreeBSD bootloader available on sparc64 (the Sun OBP permit to select the partition from where to boot).
 +</​note>​
 +
 +Actual State: Commenting net/bird and net/​openlldp permit to build the sparc64 BSDRP image, but the resulting image don't accept to login (Generate a "​__sparc_utrap:​ fatal illegal instruction"​).
 +
 +===== arm support (work in progress) =====
 +
 +<note warning>​This patch, prensently didn't fully works because I didn't found a solution for cross-compil arm ports from an i386/amd64 FreeBSD. ​
 +
 +But it should work from an arm FreeBSD (not tested, I didn't have arm computer)</​note>​
 +
 +This patch permit to generate NanoBSD arm image: It's came from the nanobsd/​gateworks exemples.
 +
 +[[http://​bsdrp.svn.sourceforge.net/​viewvc/​bsdrp/​tags/​1.0/​patches/​nanobsd.arm.patch|nanobsd.arm.patch]]
documentation/technical_docs/nanobsd.txt · Last modified: 2011/12/27 14:37 (external edit)