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)