User Tools

Site Tools


documentation:technical_docs

Differences

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

Link to this comparison view

documentation:technical_docs [2018/08/20 07:46] (current)
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: 2018/08/20 07:46 (external edit)