BSD Router Project

User Tools

Site Tools

Trace:
documentation:technical_docs
no way to compare when less than two revisions

Differences

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


Next revision
—documentation:technical_docs [2018/08/20 07:46] – external edit 127.0.0.1
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.
 +
 +
 +
 +
 +===== Prerequisite =====
 +
 +You need 3G of free space (1G for FreeBSD installation, 5G for downloading full FreeBSD and ports sources, and 4G for the working dir).
 +
 +
 +==== Getting BSDRP source code ====
 +
 +You can download the source code of BSDRP with svnlite (included in FreeBSD):
 +
 +<code>
 +pkg install ca_root_nss
 +svnlite co https://github.com/ocochard/BSDRP/trunk BSDRP
 +cd BSDRP
 +</code>
 +
 +or using git if you had installed it:
 +<code>
 +pkg install ca_root_nss
 +git clone https://github.com/ocochard/BSDRP.git BSDRP
 +</code>
 +
 +Once you download the code, you can kept your BSDRP sources up-to-date with these commands:
 +<code>
 +svnlite update | git pull
 +./make -u
 +</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 ====
 +
 +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:
 +    * gam_server
 +    * gvfsd-trash
 +
 +here is the log of a failed build:
 +
 +<code>
 +### 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
 +</code>
 +
 +==== gam_server ====
 +For preventing 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>
 +
 +==== gvfsd-trash ====
 +
 +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 =====
 +
 +[[https://docs.google.com/presentation/pub?id=1d-CqdLljaCcO-sdyfqOn4pLR-wzWaIGC9JeetcU97ks&start=false&loop=false&delayms=5000|Short presentation of NanoBSD and BSD Router Project]].
 +
 +===== main files =====
 +
 +==== 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 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
 +
 +
 +==== $PROJECT/$PROJECT.nano ====
 +
 +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:
 +
 +<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 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:
 +<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>
 +
 +=== 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:
 +<code>
 +setenv PORTSDIR /usr/local/BSDRP/BSDRP/FreeBSD/ports
 +cd $PORTSDIR/www/mohawk
 +make run-depends-list
 +devel/libevent
 +</code>
 +
 +Here we need devel/libevent is a running dependency for www/mohawk.
 +
 +=== 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 #####) all the running dependency and your port:
 +
 +<code>
 +add_port "devel/libevent"
 +add_port "www/mohawk"
 +</code>
 +
 +Remove theses lines that compile and install extra small tools too:
 +<code>
 +customize_cmd add_netrate
 +</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: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 !
 +</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]].
 +
  
documentation/technical_docs.txt · Last modified: 2024/04/04 13:05 by olivier
Except where otherwise noted, content on this wiki is licensed under the following license: BSD 2-Clause
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki