====== Technical documentation for developers ======
{{description>Advanced technical documentation for contributing to BSD Router Project}}


====== NanoBSD ======

The first step was to understand [[Documentation:Technical docs:NanoBSD|what is NanoBSD ?]]

====== How to build BSDRP images ======

All theses steps are done from a FreeBSD system (release 8.2 minimum).

===== Prerequisite =====

You need 3G of free space (1,5G for full FreeBSD+ports source, and 1,5G for the working dir).

==== Installing Subversion ====

Before downloading BSD Router Project source code, you need to install subversion:

By downloading/installing the package:
<code>
pkg_add -r subversion
</code>

Or by compiling it:
<code>
cd /usr/ports/devel/subversion
make install clean
</code>

==== Getting BSDRP source code ====

Once subversion installed, you can download the source code of BSDRP with theses commands:

<code>
svn co https://bsdrp.svn.sourceforge.net/svnroot/bsdrp/trunk BSDRP
cd BSDRP
</code>

Once you download the code, you can kept your BSDRP sources up-to-date with these commands:
<code>
cd /usr/src/tools/tools/nanobsd/BSDRP
svn update
</code>

===== Running the build script =====

Display the options proposed by the make.sh script :

<code>
./make.sh -h
</code>

The FreeBSD code include all architecture and limited cross-compiling tools: You can generate an i386 BSDRP image from a FreeBSD amd64, but you can't generate a sparc64 image from an i386/amd64 host.

===== Current problems with make =====

==== Disk image creation can fail ====

If you had installed gamin on your FreeBSD, sometimes NanoBSD can't umount the md during image creation.
"fstat /usr/obj/nanobsd.bsdrp/_.mnt" show that the process gam_server (gamin) lock the mount point.

here is the log of a failed build:

<code>

Copying worlddir...
307484 blocks
Filesystem  1K-blocks   Used  Avail Capacity iused ifree %iused  Mounted on
/dev/md0s1a    293632 157919 112222    58%    4831 34335   12%   /usr/obj/nanobsd.bsdrp/_.mnt
Generating mtree...
umount: unmount of /usr/obj/nanobsd.bsdrp/_.mnt failed: Device busy
Filesystem  1K-blocks   Used  Avail Capacity iused ifree %iused  Mounted on
/dev/md0s1a    293632 157453 112688    58%    4831 34335   12%   /usr/obj/nanobsd.bsdrp/_.mnt
umount: unmount of /usr/obj/nanobsd.bsdrp/_.mnt failed: Device busy
mdconfig: ioctl(/dev/mdctl): Device busy

</code>

For prevent gamin to lock the working mount point, create this configuration file and force a restart of gamin:
<code>
mkdir /usr/local/etc/gamin
echo "fsset ufs poll 10" > /usr/local/etc/gamin/gaminrc
killall -9 gam_server
</code>

====== How to generate customized BSDRP images (from sources) ======

If you want to generate your customized BSDRP image, first try to build one generic BSDRP image from source.

If this step works for you, then you can begin to customize it.

==== BSDRP.nano ====

This file include all majors information for the build process of the image.

You can change the:
  * Size of target BSDRP media (UsbDevice Generic)
  * Size of configuration partition NANO_CONFSIZE)
  * Size of data partition (NANO_DATASIZE)
  * Size of the /etc RAM disk (NANO_RAM_ETCSIZE)
  * Size of the /tmp, /var disk (NANO_RAM_TMPVARSIZE)
  * and so one…
  * 
You can declare new package (and their dependency if there use special option) to be installed: For example, if you want to add vim-lite, you add theses lines:

<code>
add_port "converters/libiconv" "-DNO_INSTALL_MANPAGES -DFORCE_PKG_REGISTER -DNOPORTDOCS"
add_port "editors/vim-lite" "-DWITHOUT_X11 -DNO_INSTALL_MANPAGES -DNOPORTDOCS"
</code>

If you need to set special permission on some file after their installation, you need to add these steps on the bsdrp_custom () function.

==== Files directory ====

All files put in the Files/ directory will be copied on the BSDRP image.

==== Kernels directory ====

You can change the kernel configuration used by BSDRP by editing the file in the kernels/ directory.

====== How to modify an existing image ======

All theses step are done from a FreeBSD system using a unziped BSDRP full-image.

===== Partition layout of a BSDRP image =====

Here are all partition found in a BSDRP-full image:

  * s1a: first system partition (UFS labeled as BSDRPs1a)
  * s2a: Second system partition, didn't exist if the system was never upgraded (UFS labeled as BSDRPs2a)
  * s3: cfg partition (UFS labeled as BSDRPs3)
  * s4: data partition (UFS labeled as BSDRPs4)

FreeBSD call "slide" (s) an MBR partition.

===== Mounting a BSDRP image as a memory disk =====

==== Automated way ====

Use the script include with BSDRP sources:
./image_tool.sh mount <filename>
./image_tool.sh umount

==== Manual way ====
Using the BSDRP image file, create a memory disk (md):

<code>
mdconfig -a -t vnode -f BSDRP_0.35_full_i386_serial.img -x 63 -y 16
</code>
The system will display the md name created:

<code>
md0
</code>

Now list all partitions on this md:

<code>
# ls /dev/md0*
# /dev/md0    /dev/md0s1  /dev/md0s1a /dev/md0s2  /dev/md0s3
</code>

You should found the s1a (system) and s3 (cfg) partition.
Mount the system partition for example:

<code>
mount /dev/md0s1a /mnt
</code>

Now you can do all your changes on the image.

And the end, umount and close the memory disk:
<code>
umount /mnt
mdconfig -d -u 0
</code>

==== Increasing /etc and /var RAM disk size =====

Mount the filesystem in read-write mode:

<code>
[root@BSDRP]/# mount -uw /
</code>

And change the value in these files:

  * /conf/base/etc/md_size
  * /conf/base/var/md_size

The remount the filesystem in read-only and reboot (answer "no" if it detect configuration changes)

<code>
[root@BSDRP]/conf/base/var# mount -ur /
[root@BSDRP]/conf/base/var# reboot
</code>
====== How to run ======
===== Qemu =====
==== Convert image to Qemu format ====

Is not mandatory to convert raw BSDRP image for being use under Qemu, but the qcow2 image is a lot's smaller.

<code>
unxz BSDRP_0.35_full_amd64_serial.img.xz
qemu-img convert -f raw -O qcow2 BSDRP_0.35_full_amd64_vga.img BSDRP_0.35_full_amd64_vga.qcow2
</code>

==== Starting amd64 release ====

If you generated an amd64 release, with console as "vga" and disk as "ad0":
<code>
qemu-system-x86_64 -hda /usr/obj/nanobsd.BSDRP.amd64/BSDRP_0.35_full_amd64_vga.img
</code>
If you generated an amd64 release, with console as "serial" and disk as "ad0":

You can tell to qemu option to will disable vga card, and redirect serial to standard output:
<code>
qemu-system-x86_64 -nographic -hda /usr/obj/nanobsd.BSDRP.amd64/BSDRP_0.35_full_amd64_serial.img
</code>
Or you can use a vnc as a console:
<code>
qemu-system-x86_64 -hda /usr/obj/nanobsd.BSDRP.amd64/BSDRP_0.35_full_amd64_vga.img -vnc :0
vncviewer localhost
</code>

==== Starting i386 release ====
For the i386-vga release:
<code>
qemu -net nic -net user -hda BSDRP_0.35_full_i386_vga.img
</code>


==== Create an Ethernet link between your host and the virtual machine ====

As root (under a FreeBSD), create the virtual TAP interface and assign it an IP address:
<code>
ifconfig tap0 create
</code>

Then start qemu linked to this TAP interface:
<code>
qemu -hda /BSDRP_0.35_full_i386_vga.img -net nic -net tap,ifname=tap0 -localtime -kernel-kqemu
</code>

At the end, you can delete the TAP interface:
<code>
ifconfig tap0 destroy
</code>

When you shutdown your qemu machine, the tap interface change to state "down", you need to re-configure it to up before re-use it:
<code>
ifconfig tap0 up
</code>

===== Oracle VirtualBox  =====

How to use Oracle VirtualBox (Ver 3.0.4).

  * Convert Image
  * Creating multi images (setting different UUID)

==== Convert raw image file to vdi image file ====

Using the Virtual Box command line tool, convert the raw image file to vdi:
<code>
unxz BSDRP_0.35_full_amd64_vga.img.xz

VBoxManage convertfromraw BSDRP_0.35_full_amd64_vga.img BSDRP_0.35_full_amd64_vga.vdi --format vdi
VirtualBox Command Line Management Interface Version 3.0.4
(C) 2005-2009 Sun Microsystems, Inc.
All rights reserved.

Converting from raw image file="BSDRP_0.35_full_amd64_vga.img" to file="BSDRP_0.35_full_amd64_vga.vdi"...
Creating dynamic image with size 999968256 bytes (954MB)...
</code>

==== Creating multiple images ====

Create a copy for example R1
<code>
VBoxManage clonehd bsdrp.vdi r1.vdi --format VDI
VirtualBox Command Line Management Interface Version 3.0.4
(C) 2005-2009 Sun Microsystems, Inc.
All rights reserved.

0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
Clone hard disk created in format 'VDI'. UUID: 87002bab-42ec-4656-9658-6ebe27178445
</code>
If you copied an image with the file system of the operating system, you need to generate a new UUID for the disk or it will not be accepted in VirtualBox if you are using the original.

Change the UUID of vdi image R2.vdi for example
<code>
VBoxManage internalcommands sethduuid r2.vdi
VirtualBox Command Line Management Interface Version 3.0.4
(C) 2005-2009 Sun Microsystems, Inc.
All rights reserved.

UUID changed to: da4de103-c139-436f-a76a-b8f1e743f269

</code>

====== How to debug ======

Here are some advice for debugging.

===== Performance optimization =====

You can found more information about FreeBSD on the [[Documentation:Technical docs:Performance|Performance]] page.

===== Shell script =====

Start your script with "sh -x":

<code>
[root@router]~#sh -x /usr/local/sbin/system
</code>

===== RC script ======

If you want to create some RC scripts, you need to start by reading [[http://www.freebsd.org/doc/en_US.ISO8859-1/articles/rc-scripting/| Practical rc.d scripting in BSD]].