Differences

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

--- documentation:technical_docs [2012/08/02 13:57]
+++ documentation:technical_docs [2013/04/03 09:03] (current)
olivier [Little child project example]
@@ Line 1: / Line 1: @@
+====== 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.3 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 install 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 svn://svn.code.sf.net/p/bsdrp/code/trunk BSDRP
+cd BSDRP
+</code>
+Once you download the code, you can kept your BSDRP sources up-to-date with these commands:
+<code>
+svn update
+</code>
+===== make.sh flowshart =====
+Here is the big picture regarding BSDRP image build process:
+{{BSDRP.framework.flowshart.png| BSDRP build framework flowshart}}
+===== 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...
+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 ======
+If you want to generate your customized BSDRP image, first try to build one generic BSDRP image from source.
+You can check the files of the project "BSDRP" and it's child project "BSDRPcur".
+A child project overwrite the MASTER_PROJECT files/kernels settings.
+If this step works for you, then you can begin to customize it.
+==== make.conf ====
+This file include the main global information for building the image:
+  * NAME: Name of the Project
+  * MASTER_PROJECT: For a child project, name of the father project
+  * SVN_SRC_PATH: SVN URL for the source tree
+  * SVN_PORTS_PATH: SVN URL for the port source tree
+  * FREEBSD_SRC: directory for localy stored FreeBSD source tree
+  * SRC_PATCH_DIR: Directory for FreeBSD patches
+  * PORTS_SRC: Directory for localy stored ports source tree
+  * PORT_PATCH_DIR: Directory for port patches
+  * NANOBSD_DIR: Where the nanobsd tree lives
+  * NANO_MODULES_ARCH: List of kernel modules to build for ARCH
+==== $PROJECT/$PROJECT.nano ====
+This file include all the customization steps:
+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, but only if they 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.
+==== $PROJECT/kernels/$ARCH ====
+This directory include the kernel configuration files.
+You need to edit these files and the NANO_MODULES_$ARCH variable in the make.conf for customizing your own kernel and modules.
+==== $PROJECT/Files directory ====
+All files put in the Files/ directory will be copied as it on the BSDRP image.
+==== Little child project example ====
+Here is a little example (minimum modification) for building a new project based on BSDRP, but for a web server appliance:
+This project will be a child project of BSDRP.
+Start by downloading BSDRP source code (refers to getting BSDRP source code chapter) and go in the BSDRP directory.
+Then create a new directory using your project name:
+<code>mkdir WEBSRV</code>
+=== make.conf ===
+Now we need to configure a minimum project configuration file:
+<code>
+echo 'NAME="WEBSRV"' > WEBSRV/make.conf
+echo 'MASTER_PROJECT="BSDRP"' >> WEBSRV/make.conf
+</code>
+=== project.nano ===
+Now we will copy the nanobsd configuration file from BSDRP:
+<code>
+cp BSDRP/BSDRP.nano WEBSRV/WEBSRV.nano
+</code>
+Edit the file WEBSRV/WEBSRV.nano and delete all lines related to routing ports like that:
+<code>
+add_port "category/port_name" "build options"
+</code>
+And add (in the #### Ports list section #####) this line:
+<code>
+add_port "www/mohawk"
+</code>
+Remove theses lines that compile and install extra small tools too:
+<code>
+customize_cmd add_netrate
+customize_cmd add_quagga-bgp-netgen
+</code>
+Then modify the bsdrp_custom () function in this file too for removing the quagga chown hack.
+=== Files/etc/version ===
+Now set-up the version number:
+<code>
+mkdir -p WEBSRV/Files/etc
+echo '1' > WEBSRV/Files/etc/version
+</code>
+=== Generating image ===
+Now you should generate a full new image:
+<code>
+root@laptop:/usr/local/BSDRP # ./make.sh -p WEBSRV
+BSD Router Project image build script
+Will generate an WEBSRV image with theses values:
+- Target architecture: amd64
+- Console : -vga
+- Source Updating/installing: NO
+- Build the full world (take about 1 hour): YES
+- FAST mode (skip compression and checksumming): NO
+- TMPFS: NO
+- Debug image type: NO
+Copying amd64 Kernel configuration file
+Launching NanoBSD build process...
+:00:00 # NanoBSD image WEBSRV build starting
+:00:00 ## Clean and create object directory (/usr/obj/WEBSRV.amd64)
+:00:00 ## Construct build make.conf (/usr/obj/WEBSRV.amd64/make.conf.build)
+:00:00 ## run buildworld
+:00:00 ### log: /usr/obj/WEBSRV.amd64/_.bw
+:15:03 ## build kernel (amd64)
+:15:03 ### log: /usr/obj/WEBSRV.amd64/_.bk
+:17:50 ## Clean and create world directory (/usr/obj/WEBSRV.amd64/_.w)
+:17:50 ## Construct install make.conf (/usr/obj/WEBSRV.amd64/make.conf.install)
+:17:50 ## installworld
+:17:50 ### log: /usr/obj/WEBSRV.amd64/_.iw
+:18:29 ## install /etc
+:18:29 ### log: /usr/obj/WEBSRV.amd64/_.etc
+:18:30 ## configure nanobsd /etc
+:18:30 ## install kernel (amd64)
+:18:30 ### log: /usr/obj/WEBSRV.amd64/_.ik
+:18:33 ## run customize scripts
+:18:33 ## customize "add_port_www_mohawk"
+:18:33 ### log: /usr/obj/WEBSRV.amd64/_.cust.add_port_www_mohawk
+:18:34 ## customize "cleanup_ports"
+:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.cleanup_ports
+:18:34 ## customize "shrink_md_fbsize"
+:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.shrink_md_fbsize
+:18:34 ## customize "cust_install_files"
+:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.cust_install_files
+:18:34 ## customize "bsdrp_custom"
+:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.bsdrp_custom
+:18:38 ## customize "cust_allow_ssh_root"
+:18:38 ### log: /usr/obj/WEBSRV.amd64/_.cust.cust_allow_ssh_root
+:18:38 ## customize "bsdrp_console_vga"
+:18:38 ### log: /usr/obj/WEBSRV.amd64/_.cust.bsdrp_console_vga
+:18:38 ## configure nanobsd setup
+:18:38 ### log: /usr/obj/WEBSRV.amd64/_.dl
+:18:39 ## run late customize scripts
+:18:39 ## build diskimage
+:18:39 ### log: /usr/obj/WEBSRV.amd64/_.di
+:19:02 # NanoBSD image WEBSRV completed
+unmounting  /usr/local/BSDRP/WEBSRV/kernels
+ /usr/local/BSDRP/WEBSRV/Files
+NanoBSD build seems finish successfully.
+Compressing WEBSRV upgrade image...
+/usr/obj/WEBSRV.amd64/WEBSRV-1-upgrade-amd64-vga.img (1/1)
+%        26.2 MiB / 101.9 MiB = 0.257   3.0 MiB/s       0:34
+Generating checksum for WEBSRV upgrade image...
+WEBSRV upgrade image file here:
+/usr/obj/WEBSRV.amd64/WEBSRV-1-upgrade-amd64-vga.img.xz
+Compressing WEBSRV full image...
+/usr/obj/WEBSRV.amd64/WEBSRV-1-full-amd64-vga.img (1/1)
+%        26.2 MiB / 244.1 MiB = 0.107   5.3 MiB/s       0:45
+Generating checksum for WEBSRV full image...
+Zipped WEBSRV full image file here:
+/usr/obj/WEBSRV.amd64/WEBSRV-1-full-amd64-vga.img.xz
+Zipping and renaming mtree...
+/usr/obj/WEBSRV.amd64/WEBSRV-1-amd64-vga.mtree (1/1)
+%      262.3 KiB / 1753.4 KiB = 0.150
+HIDS reference file here:
+/usr/obj/WEBSRV.amd64/WEBSRV-1-amd64-vga.mtree.xz
+Done !
+</code>
+====== 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 debug ======
+Here are some advice for debugging.
+===== Performance optimization =====
+You can found more information about FreeBSD on the [[Documentation:Technical docs:Performance|FreeBSD forwarding 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]].

BSD Router Project

User Tools

Site Tools

Differences

Page Tools