2 # $Id: README 4502 2009-12-15 11:10:33Z marta $
5 This directory contains a port of ipfw and dummynet to Linux and OpenWrt
6 (including PlanetLab). A Windows version is in the works but not ready yet.
7 Building the code produces:
9 a kernel module, ipfw_mod.ko
10 a userland program, /sbin/ipfw
12 The source code here comes straight from FreeBSD (roughly the
13 version in RELENG_7 and HEAD as of December 2009), plus some glue code
14 and headers written from scratch.
15 Unless specified otherwise, all the code here is under a BSD license.
17 =================== BUILD INSTRUCTIONS ==========================
19 ***** Linux 2.6.x ******
21 make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
23 where the two variables are optional an point to the linux kernel
24 sources and the /usr directory. Defaults are USRDIR=/usr and
25 KERNELPATH=/lib/modules/`uname -r`/build --- XXX check ?
27 NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
28 configuration file. You can enable it by doing
30 "(cd ${KERNELPATH}; make menuconfig)"
32 and enabling the option listed below:
35 Networking options --->
36 [*] Network packet filtering framework (Netfilter)
39 ***** Linux 2.4.x *****
41 Almost as above, with an additional VER=2.4
43 make VER=2.4 KERNELPATH=...
45 For 2.4, if KERNELPATH is not specified then we use
46 KERNELPATH ?= /usr/src/`uname -r`/build
48 You need to follow the same instruction for the 2.6 kernel, enabling
49 netfilter in the kernel options:
51 Networking options --->
52 [*] Network packet filtering (replaces ipchains)
54 ***** Openwrt package *****
56 (Tested with kamikaze_8.09.1 and Linux 2.4)
58 + Download and extract the OpenWrt package, e.g.
60 wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
61 tar xvjf kamikaze_8.09.1_source.tar.bz2
63 + "cd" to the directory with the OpenWrt sources (the one that
64 contains Config.in, rules.mk ...)
68 + Optional: to be sure that the tools are working, make a first
69 compilation as follows:
71 - run "make menuconfig" and set the correct target device,
73 - run "make" to do the build
75 + Add ipfw2 to the openwrt package, as follows:
77 - copy the code from this directory to the place used for the build:
79 cp -Rp /path_to_ipfw_mod ../ipfw_mod;
81 If you want, you can fetch a newer version from the web
82 (cd ..; rm -rf ipfw_mod;
83 wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz;\
84 tar xvzf ipfw_mod-latest.tgz)
86 - run the following commands:
88 cp ../ipfw_mod/Makefile.openwrt package/ipfw2/Makefile)
90 to create the package/ipfw2 directory in the OpenWrt source
91 directory, and copy Makefile.openwrt to package/ipfw2/Makefile:
93 - if necessary, edit package/ipfw2/Makefile and set IPFW_DIR to point to
94 the directory ipfw_mod, which contains the ipfw sources
96 - run "make menuconfig" and select ipfw2 as a module <M> in
97 Kernel Modules -> Other modules -> kmod-ipfw2
99 - run "make" to build the package, "make V=99" for verbose build.
101 - to modify the code, assuming you are in directory "kamikaze_8.09.1"
103 (cd ../ipfw_mod && vi ...the files you are interested in )
104 rm -rf build_dir/linux-brcm-2.4/kmod-ipfw2
105 make package/ipfw2/compile V=99
107 The resulting package is located in bin/packages/mipsel/kmod-ipfw2*,
108 upload the file and install on the target system, as follows:
110 opkg install kmod-ipfw2_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
111 ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
112 insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
113 /lib/modules/2.4.35.4/ipfw show # launch the userspace tool
114 rmmod ipfw_mod.o # remove the module
116 ***** PLANETLAB BUILD (within a slice) *****
118 Follow the instructions below. You can just cut&paste
120 # install the various tools if not available
121 sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
122 # new build installation requires the gnupg package
123 sudo yum -y install gnupg
125 # create and move to a work directory
127 # extract a planetlab distribution to directory XYZ
128 (cd test; svn co http://svn.planet-lab.org/svn/build/trunk XYZ)
129 # copy the planetlab/*mk files here, overriding existing ones
130 cp planetlab/*mk test/XYZ
131 # download the specfiles and do some patching.
132 # Results are into SPEC/ (takes 5 minutes)
133 (cd test/XYZ; make stage1=true PLDISTRO=planetlab )
134 # Building the slice code is fast, the root code takes longer
135 # as it needs to rebuild the whole kernel
136 (cd test/XYZ; sudo make ipfwslice ipfwroot)
138 The kernel dependency phase is a bit time consuming, but does not
139 need to be redone if we are changing the ipfw sources only.
140 To clean up the code do
141 (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
142 then after you have updated the repository again
143 (cd test/XYZ; sudo make ipfwslice ipfwroot)
145 --- other, instructions (to be verified) ---
147 To build a kernel module for the PlanetLab distribution you need a build system.
148 For an up-to-date and detailed information on how to build a local myplc installation,
149 a local mirror, a PlanetLab test system see[1]
151 To create a build system you need to do the following steps:
153 1. install CentOS 5, detailed information[2]
155 1.A download the image from the main site[3] for example:
157 wget http://mi.mirror.garr.it/mirrors/CentOS/5.4/isos/i386/CentOS-5.4-i386-netinstall.iso
159 1.B Add the repository
161 cat >> /etc/yum.repos.d/dhozac-vserver.repo <<EOF
163 name=Linux-VServer related packages for CentOS $releasever - $basearch
164 baseurl=http://rpm.hozac.com/dhozac/centos/$releasever/vserver/$basearch
165 gpgkey=http://rpm.hozac.com/conf/keys/RPM-DHOZAC-GPG-KEY
168 1.C Update, install and config the system
172 yum install util-vserver{,-core,-lib,-sysv,-build}
174 yum install subversion
175 /etc/init.d/vprocunhide start
176 chkconfig vservers-default on
180 2.A Checkout the planetlab build
183 svn co http://svn.planet-lab.org/svn/build/trunk svn-build
185 2.B Search for a working RPM distribution in:
187 http://build.onelab.eu/onelab/
188 # good distribution ends in .ok, bad in .ko
189 # in this example we used the following:
190 http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/
192 2.C Creating a vserver
195 ./vtest-init-vserver.sh -f f8 -d onelab -p linux32 mybuild \
196 http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/ \
197 -- --interface eth0:138.96.255.221 --hostname vnode01.inria.fr &> mybuild.log&
201 3.A Enter on the vserver, and create the build
203 vserver mybuild enter
205 svn co http://svn.planet-lab.org/svn/build/trunk build
215 # the compilation is composed by several steps,
216 # make help for more information
217 # the first for the onelab compilation will download
218 # the SPEC file from the repository specified in
220 make stage1=true PLDISTRO=onelab
222 # to download and build a module, for example ipfw:
225 # to do local changes
228 # download the ipfw sources and extract it into ./ipfw
230 svn+ssh://onelab2.iet.unipi.it/home/svn/ports-luigi/dummynet-branches/ipfw_mod ./ipfw
232 wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz
233 tar xvzf ipfw_mod-latest.tgz
235 # start the compilation
237 rm -rf BUILD/ipfw-0.1/
239 rm -rf RPMS/i386/ipfw*
242 5. download and install sources into a node
244 5.A Copy RPMS into the node and install it:
245 # exit from the root context
247 scp /vserver/mybuild/build/RPMS/i386/ipfw-* root@node.iet.unipi.it:
248 ssh root@node.iet.unipi.it
250 rpm -ivh ./ipfw-0-9...TAB
253 # the ipfw package should be installed
257 [1] https://svn.planet-lab.org/wiki/VserverCentos
258 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
259 [3] http://mirror.centos.org/centos/5/isos/
260 [4] More information are in /build/README* files