#
-# $Id$
+# $Id: README 4502 2009-12-15 11:10:33Z marta $
#
This directory contains a port of ipfw and dummynet to Linux and OpenWrt
-(a Windows version is in the works but not ready yet).
+(including PlanetLab). A Windows version is in the works but not ready yet.
Building the code produces:
a kernel module, ipfw_mod.ko
a userland program, /sbin/ipfw
The source code here comes straight from FreeBSD (roughly the
-version in RELENG_7 and HEAD as of June 2009), plus some glue code
+version in RELENG_7 and HEAD as of December 2009), plus some glue code
and headers written from scratch.
Unless specified otherwise, all the code here is under a BSD license.
-=== To compile for a 2.6 kernel, simply run
+Note:
+ - the linux version miss the "one_pass" feature
- make
+=================== BUILD INSTRUCTIONS ==========================
- Make sure that kernel headers (or sources) are installed on your
- system, and that the link "/lib/modules/`uname -r`/build" points
- to the header/source tree matching your kernel.
+***** Linux 2.6.x ******
- You can override the default kernel tree with
+ make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
- make KERNELPATH=your_kernel_source_tree
+ where the two variables are optional an point to the linux kernel
+ sources and the /usr directory. Defaults are USRDIR=/usr and
+ KERNELPATH=/lib/modules/`uname -r`/build --- XXX check ?
NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
configuration file. You can enable it by doing
Networking options --->
[*] Network packet filtering framework (Netfilter)
+ If you have not yet compiled your kernel source, you need to
+ prepare the build environment:
-=== To compile for a 2.4 kernel:
+ (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
+
+***** Linux 2.4.x *****
+
+ Almost as above, with an additional VER=2.4
make VER=2.4 KERNELPATH=...
+ For 2.4, if KERNELPATH is not specified then we use
+ KERNELPATH ?= /usr/src/`uname -r`/build
+
You need to follow the same instruction for the 2.6 kernel, enabling
- the kernel options:
+ netfilter in the kernel options:
Networking options --->
[*] Network packet filtering (replaces ipchains)
-=== To build an Openwrt package
+***** Openwrt package *****
(Tested with kamikaze_8.09.1 and Linux 2.4)
+ Add ipfw2 to the openwrt package, as follows:
- - fetch and extract the code e.g.
+ - copy the code from this directory to the place used for the build:
- (cd ..; \
- wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_linux-20090622.tgz;\
- tar xvzf ipfw_linux-20090622.tgz)
+ cp -Rp /path_to_ipfw_mod ../ipfw_mod;
- (but you should have done it already)
+ If you want, you can fetch a newer version from the web
+ (cd ..; rm -rf ipfw_mod;
+ wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz;\
+ tar xvzf ipfw_mod-latest.tgz)
- run the following commands:
- (mkdir packages/ipfw2;
- cp ../ipfw_mod/Makefile.openwrt packages/ipfw2/Makefile)
+ (mkdir package/ipfw2;
+ cp ../ipfw_mod/Makefile.openwrt package/ipfw2/Makefile)
to create the package/ipfw2 directory in the OpenWrt source
directory, and copy Makefile.openwrt to package/ipfw2/Makefile:
- if necessary, edit package/ipfw2/Makefile and set IPFW_DIR to point to
- the directory with the ipfw sources (the directory
- which contains this README, dummynet/ ipfw/ and so on);
+ the directory ipfw_mod, which contains the ipfw sources
- run "make menuconfig" and select ipfw2 as a module <M> in
- Kernel Modules -> Other modules -> ipfw2
+ Kernel Modules -> Other modules -> kmod-ipfw2
- run "make" to build the package, "make V=99" for verbose build.
+ - to modify the code, assuming you are in directory "kamikaze_8.09.1"
+
+ (cd ../ipfw_mod && vi ...the files you are interested in )
+ rm -rf build_dir/linux-brcm-2.4/kmod-ipfw2
+ make package/ipfw2/compile V=99
+
The resulting package is located in bin/packages/mipsel/kmod-ipfw2*,
upload the file and install on the target system, as follows:
/lib/modules/2.4.35.4/ipfw show # launch the userspace tool
rmmod ipfw_mod.o # remove the module
------------------------------------------------------------------------------
+***** PLANETLAB BUILD (within a slice) *****
+These instruction can be used by PlanetLab developers to compile the dummynet module
+on a node. To install the module on the node users need root access in root context.
+PlanetLab users that want to use the dummynet package should ask to PlanetLab support
+for nodes with dummynet emulation capabilities.
+
+ Follow the instructions below. You can just cut&paste
+
+ # install the various tools if not available
+ sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
+ # new build installation requires the gnupg package
+ sudo yum -y install gnupg
+
+ # create and move to a work directory
+ mkdir -p test
+ # extract a planetlab distribution to directory XYZ
+ (cd test; svn co http://svn.planet-lab.org/svn/build/trunk XYZ)
+ # copy the planetlab/*mk files here, overriding existing ones
+ cp planetlab/*mk test/XYZ
+ # download the specfiles and do some patching.
+ # Results are into SPEC/ (takes 5 minutes)
+ (cd test/XYZ; make stage1=true PLDISTRO=planetlab )
+ # Building the slice code is fast, the root code takes longer
+ # as it needs to rebuild the whole kernel
+ (cd test/XYZ; sudo make ipfwslice ipfwroot)
+
+ The kernel dependency phase is a bit time consuming, but does not
+ need to be redone if we are changing the ipfw sources only.
+ To clean up the code do
+ (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
+ then after you have updated the repository again
+ (cd test/XYZ; sudo make ipfwslice ipfwroot)
+
+--- other, instructions (to be verified) ---
+
+To build a kernel module for the PlanetLab distribution you need a build system.
+For an up-to-date and detailed information on how to build a local myplc installation,
+a local mirror, a PlanetLab test system see[1]
+
+To create a build system you need to do the following steps:
+
+ 1. install CentOS 5, detailed information[2]
+
+ 1.A download the image from the main site[3] for example:
+
+ wget http://mi.mirror.garr.it/mirrors/CentOS/5.4/isos/i386/CentOS-5.4-i386-netinstall.iso
+
+ 1.B Add the repository
+
+ cat >> /etc/yum.repos.d/dhozac-vserver.repo <<EOF
+ [dhozac-vserver]
+name=Linux-VServer related packages for CentOS $releasever - $basearch
+baseurl=http://rpm.hozac.com/dhozac/centos/$releasever/vserver/$basearch
+gpgkey=http://rpm.hozac.com/conf/keys/RPM-DHOZAC-GPG-KEY
+EOF
+
+ 1.C Update, install and config the system
+
+ yum update yum
+ yum install kernel
+ yum install util-vserver{,-core,-lib,-sysv,-build}
+ yum install vim
+ yum install subversion
+ /etc/init.d/vprocunhide start
+ chkconfig vservers-default on
+
+ 2. create a vserver
+
+ 2.A Checkout the planetlab build
+
+ cd
+ svn co http://svn.planet-lab.org/svn/build/trunk svn-build
+
+ 2.B Search for a working RPM distribution in:
+
+ http://build.onelab.eu/onelab/
+ # good distribution ends in .ok, bad in .ko
+ # in this example we used the following:
+ http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/
+
+ 2.C Creating a vserver
+
+ cd ~/svn-build
+ ./vtest-init-vserver.sh -f f8 -d onelab -p linux32 mybuild \
+ http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/ \
+ -- --interface eth0:138.96.255.221 --hostname vnode01.inria.fr &> mybuild.log&
+
+ 3. create the build
+
+ 3.A Enter on the vserver, and create the build
+
+ vserver mybuild enter
+ cd \
+ svn co http://svn.planet-lab.org/svn/build/trunk build
+
+ 4. build
+
+ 4.A build[4]
+ cd /build
+
+ # full cleanup
+ make distclean
+
+ # the compilation is composed by several steps,
+ # make help for more information
+ # the first for the onelab compilation will download
+ # the SPEC file from the repository specified in
+ # onelab-tags.mk
+ make stage1=true PLDISTRO=onelab
+
+ # to download and build a module, for example ipfw:
+ make ipfw
+
+ # to do local changes
+ cd /build/CODEBASE
+ rm -rf ipfw
+ # download the ipfw sources and extract it into ./ipfw
+ # by svn
+ svn+ssh://onelab2.iet.unipi.it/home/svn/ports-luigi/dummynet-branches/ipfw_mod ./ipfw
+ # from web
+ wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz
+ tar xvzf ipfw_mod-latest.tgz
+
+ # start the compilation
+ rm -rf SOURCES/ipfw*
+ rm -rf BUILD/ipfw-0.1/
+ rm -rf SRPMS/ipfw*
+ rm -rf RPMS/i386/ipfw*
+ make ipfw
+
+ 5. download and install sources into a node
+
+ 5.A Copy RPMS into the node and install it:
+ # exit from the root context
+ exit
+ scp /vserver/mybuild/build/RPMS/i386/ipfw-* root@node.iet.unipi.it:
+ ssh root@node.iet.unipi.it
+ rpm -e ipfw
+ rpm -ivh ./ipfw-0-9...TAB
+ modprobe ipfw_mod
+
+ # the ipfw package should be installed
+ ipfw show
+
+--- References
+[1] https://svn.planet-lab.org/wiki/VserverCentos
+[2] http://wiki.linux-vserver.org/Installation_on_CentOS
+[3] http://mirror.centos.org/centos/5/isos/
+[4] More information are in /build/README* files