Table of Contents
Technical documentation for developers
Advanced technical documentation for contributing to BSD Router Project
The first step was to understand what is NanoBSD ?
Note that work-in-progess to migrate from the old NanoBSD to the new poudriere image framework.
How to build BSDRP images
All theses steps are done from a FreeBSD system.
You need 21G of free space (1G for FreeBSD installation, 2G for FreeBSD sources, 10G for ports sources, and 8G for the working dir).
Getting BSDRP source code
pkg install git-lite git clone https://github.com/ocochard/BSDRP.git BSDRP
Once you download the code, you can kept your BSDRP sources up-to-date with these commands:
tools/update-src.sh ./make -u
Running the build script
Display the options proposed by the make.sh script :
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
On FreeBSD dektop, sometimes NanoBSD can't umount the md during image creation.
“fstat | grep BSDRP” display the name of the process locking the temporary mount point. It can be:
here is the log of a failed build:
### log : /usr/obj/BSDRP.amd64/_.di Error encountered. Check errors in last log file. Running exit trap code root@dev # tail -n 4 /usr/obj/BSDRP.amd64/_.di unmount: unmount of /usr/obj/BSDRP.amd64/_.mnt failed: Device busy
For preventing gamin to lock the working mount point, create this configuration file and force a restart of gamin:
mkdir /usr/local/etc/gamin echo "fsset ufs poll 10" > /usr/local/etc/gamin/gaminrc killall -9 gam_server
I don't know how to fix this gvfs bug.
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 its 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.
Customizing BSDRP in few slides
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 parent project
- SVN_SRC_PATH: SVN URL for the source tree
- SVN_PORTS_PATH: SVN URL for the port source tree
- FREEBSD_SRC: directory for locally stored FreeBSD source tree
- SRC_PATCH_DIR: Directory for FreeBSD patches
- PORTS_SRC: Directory for locally stored ports source tree
- PORT_PATCH_DIR: Directory for port patches
- DISK_SIZE : Size in MB of the destination disk
- NANOBSD_DIR: Where the nanobsd tree lives
- NANO_MODULES_ARCH: List of kernel modules to build for ARCH
This file include all the customization steps:
You can change the:
- 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 RAM 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:
add_port "converters/libiconv" "-DNO_INSTALL_MANPAGES -DFORCE_PKG_REGISTER -DNOPORTDOCS" add_port "editors/vim-lite" "-DWITHOUT_X11 -DNO_INSTALL_MANPAGES -DNOPORTDOCS"
If you need to set special permission on some file after their installation, you need to add these steps on the bsdrp_custom () function.
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.
All files put in the Files/ directory will be copied to the BSDRP image. Pay attention to the owner, group, and permissions.
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:
Now we need to configure a minimum project configuration file:
echo 'NAME="WEBSRV"' > WEBSRV/make.conf echo 'MASTER_PROJECT="BSDRP"' >> WEBSRV/make.conf
Listing all run-dependency of your ports
We want to add the port www/mohawk.
The first step is to list all run-deps of this port.
You need to have downloaded the FreeBSD port-tree first (automatically done if you've already generated one BSDRP image).
If you've installed BSDRP on /usr/local/BSDRP, here is an example for displaying the run-deps:
setenv PORTSDIR /usr/local/BSDRP/BSDRP/FreeBSD/ports cd $PORTSDIR/www/mohawk make run-depends-list devel/libevent
Here we need devel/libevent is a running dependency for www/mohawk.
Now we will copy the nanobsd configuration file from BSDRP:
cp BSDRP/BSDRP.nano WEBSRV/WEBSRV.nano
Edit the file WEBSRV/WEBSRV.nano and delete all lines related to routing ports like that:
add_port "category/port_name" "build options"
And add (in the #### Ports list section #####) all the running dependency and your port:
add_port "devel/libevent" add_port "www/mohawk"
Remove theses lines that compile and install extra small tools too:
Then modify the bsdrp_custom () function in this file too for removing the quagga chown hack.
Now set-up the version number:
mkdir -p WEBSRV/Files/etc echo '1' > WEBSRV/Files/etc/version
Now you should generate a full new image:
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:00 # NanoBSD image WEBSRV build starting 00:00:00 ## Clean and create object directory (/usr/obj/WEBSRV.amd64) 00:00:00 ## Construct build make.conf (/usr/obj/WEBSRV.amd64/make.conf.build) 00:00:00 ## run buildworld 00:00:00 ### log: /usr/obj/WEBSRV.amd64/_.bw 00:15:03 ## build kernel (amd64) 00:15:03 ### log: /usr/obj/WEBSRV.amd64/_.bk 00:17:50 ## Clean and create world directory (/usr/obj/WEBSRV.amd64/_.w) 00:17:50 ## Construct install make.conf (/usr/obj/WEBSRV.amd64/make.conf.install) 00:17:50 ## installworld 00:17:50 ### log: /usr/obj/WEBSRV.amd64/_.iw 00:18:29 ## install /etc 00:18:29 ### log: /usr/obj/WEBSRV.amd64/_.etc 00:18:30 ## configure nanobsd /etc 00:18:30 ## install kernel (amd64) 00:18:30 ### log: /usr/obj/WEBSRV.amd64/_.ik 00:18:33 ## run customize scripts 00:18:33 ## customize "add_port_devel_libevent2" 00:18:33 ### log: /usr/obj/WEBSRV.amd64/_.cust.add_port_devel_libevent2 00:18:33 ## customize "add_port_www_mohawk" 00:18:33 ### log: /usr/obj/WEBSRV.amd64/_.cust.add_port_www_mohawk 00:18:34 ## customize "cleanup_ports" 00:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.cleanup_ports 00:18:34 ## customize "shrink_md_fbsize" 00:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.shrink_md_fbsize 00:18:34 ## customize "cust_install_files" 00:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.cust_install_files 00:18:34 ## customize "bsdrp_custom" 00:18:34 ### log: /usr/obj/WEBSRV.amd64/_.cust.bsdrp_custom 00:18:38 ## customize "cust_allow_ssh_root" 00:18:38 ### log: /usr/obj/WEBSRV.amd64/_.cust.cust_allow_ssh_root 00:18:38 ## customize "bsdrp_console_vga" 00:18:38 ### log: /usr/obj/WEBSRV.amd64/_.cust.bsdrp_console_vga 00:18:38 ## configure nanobsd setup 00:18:38 ### log: /usr/obj/WEBSRV.amd64/_.dl 00:18:39 ## run late customize scripts 00:18:39 ## build diskimage 00:18:39 ### log: /usr/obj/WEBSRV.amd64/_.di 00: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) 100 % 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) 100 % 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) 100 % 262.3 KiB / 1753.4 KiB = 0.150 HIDS reference file here: /usr/obj/WEBSRV.amd64/WEBSRV-1-amd64-vga.mtree.xz Done !
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
Use the script include with BSDRP sources: ./image_tool.sh mount <filename> ./image_tool.sh umount
Using the BSDRP image file, create a memory disk (md):
mdconfig -a -t vnode -f BSDRP_0.35_full_i386_serial.img -x 63 -y 16
The system will display the md name created:
Now list all partitions on this md:
# ls /dev/md0* # /dev/md0 /dev/md0s1 /dev/md0s1a /dev/md0s2 /dev/md0s3
You should found the s1a (system) and s3 (cfg) partition. Mount the system partition for example:
mount /dev/md0s1a /mnt
Now you can do all your changes on the image.
And the end, umount and close the memory disk:
umount /mnt mdconfig -d -u 0
Increasing /etc and /var RAM disk size
Mount the filesystem in read-write mode:
[root@BSDRP]/# mount -uw /
And change the value in these files:
The remount the filesystem in read-only and reboot (answer “no” if it detect configuration changes)
[root@BSDRP]/conf/base/var# mount -ur / [root@BSDRP]/conf/base/var# reboot
How to debug
Here are some advice for debugging.
You can found more information about FreeBSD on the FreeBSD forwarding Performance page.
Start your script with “sh -x”:
[root@router]~#sh -x /usr/local/sbin/system
If you want to create some RC scripts, you need to start by reading Practical rc.d scripting in BSD.