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.
18 - the linux version miss the "one_pass" feature
20 =================== BUILD INSTRUCTIONS ==========================
22 ***** Linux 2.6.x ******
24 make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
26 where the two variables are optional an point to the linux kernel
27 sources and the /usr directory. Defaults are USRDIR=/usr and
28 KERNELPATH=/lib/modules/`uname -r`/build --- XXX check ?
30 NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
31 configuration file. You can enable it by doing
33 "(cd ${KERNELPATH}; make menuconfig)"
35 and enabling the option listed below:
38 Networking options --->
39 [*] Network packet filtering framework (Netfilter)
41 If you have not yet compiled your kernel source, you need to
42 prepare the build environment:
44 (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
46 ***** Linux 2.4.x *****
48 Almost as above, with an additional VER=2.4
50 make VER=2.4 KERNELPATH=...
52 For 2.4, if KERNELPATH is not specified then we use
53 KERNELPATH ?= /usr/src/`uname -r`/build
55 You need to follow the same instruction for the 2.6 kernel, enabling
56 netfilter in the kernel options:
58 Networking options --->
59 [*] Network packet filtering (replaces ipchains)
61 ***** Openwrt package *****
63 (Tested with kamikaze_8.09.1 and Linux 2.4)
65 + Download and extract the OpenWrt package, e.g.
67 wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
68 tar xvjf kamikaze_8.09.1_source.tar.bz2
70 + "cd" to the directory with the OpenWrt sources (the one that
71 contains Config.in, rules.mk ...)
75 + Optional: to be sure that the tools are working, make a first
76 compilation as follows:
78 - run "make menuconfig" and set the correct target device,
80 - run "make" to do the build
82 + Add ipfw2 to the openwrt package, as follows:
84 - copy the code from this directory to the place used for the build:
86 cp -Rp /path_to_ipfw_mod ../ipfw_mod;
88 If you want, you can fetch a newer version from the web
89 (cd ..; rm -rf ipfw_mod;
90 wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz;\
91 tar xvzf ipfw_mod-latest.tgz)
93 - run the following commands:
95 cp ../ipfw_mod/Makefile.openwrt package/ipfw2/Makefile)
97 to create the package/ipfw2 directory in the OpenWrt source
98 directory, and copy Makefile.openwrt to package/ipfw2/Makefile:
100 - if necessary, edit package/ipfw2/Makefile and set IPFW_DIR to point to
101 the directory ipfw_mod, which contains the ipfw sources
103 - run "make menuconfig" and select ipfw2 as a module <M> in
104 Kernel Modules -> Other modules -> kmod-ipfw2
106 - run "make" to build the package, "make V=99" for verbose build.
108 - to modify the code, assuming you are in directory "kamikaze_8.09.1"
110 (cd ../ipfw_mod && vi ...the files you are interested in )
111 rm -rf build_dir/linux-brcm-2.4/kmod-ipfw2
112 make package/ipfw2/compile V=99
114 The resulting package is located in bin/packages/mipsel/kmod-ipfw2*,
115 upload the file and install on the target system, as follows:
117 opkg install kmod-ipfw2_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
118 ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
119 insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
120 /lib/modules/2.4.35.4/ipfw show # launch the userspace tool
121 rmmod ipfw_mod.o # remove the module
123 ***** PLANETLAB BUILD (within a slice) *****
124 These instruction can be used by PlanetLab developers to compile the dummynet module
125 on a node. To install the module on the node users need root access in root context.
126 PlanetLab users that want to use the dummynet package should ask to PlanetLab support
127 for nodes with dummynet emulation capabilities.
129 Follow the instructions below. You can just cut&paste
131 # install the various tools if not available
132 sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
133 # new build installation requires the gnupg package
134 sudo yum -y install gnupg
136 # create and move to a work directory
138 # extract a planetlab distribution to directory XYZ
139 (cd test; svn co http://svn.planet-lab.org/svn/build/trunk XYZ)
140 # copy the planetlab/*mk files here, overriding existing ones
141 cp planetlab/*mk test/XYZ
142 # download the specfiles and do some patching.
143 # Results are into SPEC/ (takes 5 minutes)
144 (cd test/XYZ; make stage1=true PLDISTRO=planetlab )
145 # Building the slice code is fast, the root code takes longer
146 # as it needs to rebuild the whole kernel
147 (cd test/XYZ; sudo make ipfwslice ipfwroot)
149 The kernel dependency phase is a bit time consuming, but does not
150 need to be redone if we are changing the ipfw sources only.
151 To clean up the code do
152 (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
153 then after you have updated the repository again
154 (cd test/XYZ; sudo make ipfwslice ipfwroot)
156 --- other, instructions (to be verified) ---
158 To build a kernel module for the PlanetLab distribution you need a build system.
159 For an up-to-date and detailed information on how to build a local myplc installation,
160 a local mirror, a PlanetLab test system see[1]
162 To create a build system you need to do the following steps:
164 1. install CentOS 5, detailed information[2]
166 1.A download the image from the main site[3] for example:
168 wget http://mi.mirror.garr.it/mirrors/CentOS/5.4/isos/i386/CentOS-5.4-i386-netinstall.iso
170 1.B Add the repository
172 cat >> /etc/yum.repos.d/dhozac-vserver.repo <<EOF
174 name=Linux-VServer related packages for CentOS $releasever - $basearch
175 baseurl=http://rpm.hozac.com/dhozac/centos/$releasever/vserver/$basearch
176 gpgkey=http://rpm.hozac.com/conf/keys/RPM-DHOZAC-GPG-KEY
179 1.C Update, install and config the system
183 yum install util-vserver{,-core,-lib,-sysv,-build}
185 yum install subversion
186 /etc/init.d/vprocunhide start
187 chkconfig vservers-default on
191 2.A Checkout the planetlab build
194 svn co http://svn.planet-lab.org/svn/build/trunk svn-build
196 2.B Search for a working RPM distribution in:
198 http://build.onelab.eu/onelab/
199 # good distribution ends in .ok, bad in .ko
200 # in this example we used the following:
201 http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/
203 2.C Creating a vserver
206 ./vtest-init-vserver.sh -f f8 -d onelab -p linux32 mybuild \
207 http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/ \
208 -- --interface eth0:138.96.255.221 --hostname vnode01.inria.fr &> mybuild.log&
212 3.A Enter on the vserver, and create the build
214 vserver mybuild enter
216 svn co http://svn.planet-lab.org/svn/build/trunk build
226 # the compilation is composed by several steps,
227 # make help for more information
228 # the first for the onelab compilation will download
229 # the SPEC file from the repository specified in
231 make stage1=true PLDISTRO=onelab
233 # to download and build a module, for example ipfw:
236 # to do local changes
239 # download the ipfw sources and extract it into ./ipfw
241 svn+ssh://onelab2.iet.unipi.it/home/svn/ports-luigi/dummynet-branches/ipfw_mod ./ipfw
243 wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz
244 tar xvzf ipfw_mod-latest.tgz
246 # start the compilation
248 rm -rf BUILD/ipfw-0.1/
250 rm -rf RPMS/i386/ipfw*
253 5. download and install sources into a node
255 5.A Copy RPMS into the node and install it:
256 # exit from the root context
258 scp /vserver/mybuild/build/RPMS/i386/ipfw-* root@node.iet.unipi.it:
259 ssh root@node.iet.unipi.it
261 rpm -ivh ./ipfw-0-9...TAB
264 # the ipfw package should be installed
268 [1] https://svn.planet-lab.org/wiki/VserverCentos
269 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
270 [3] http://mirror.centos.org/centos/5/isos/
271 [4] More information are in /build/README* files