2 # $Id: README 8977 2011-07-04 11:47:59Z luigi $
5 This directory contains a port of ipfw and dummynet to Linux/OpenWrt
6 (including PlanetLab) and Windows. This version of ipfw and dummynet
7 is called "ipfw3" as it is the third major rewrite of the code.
8 The source code here comes straight from FreeBSD (roughly the
9 version in HEAD as of February 2010), plus some glue code
10 and headers written from scratch.
11 Unless specified otherwise, all the code here is under a BSD license.
13 Specific build instructions are below, and in general produce
15 a kernel module, ipfw_mod.ko (ipfw.sys on windows)
16 a userland program, /sbin/ipfw (ipfw.exe on windows)
18 which you need to install on your system.
21 Luigi Rizzo (main design and development)
22 Marta Carbone (Linux and Planetlab ports)
23 Riccardo Panicucci (modular scheduler support)
24 Francesco Magno (Windows port)
25 Fabio Checconi (the QFQ scheduler)
26 Funding from Universita` di Pisa (NETOS project),
27 European Commission (ONELAB2 project)
29 =========== INSTALL/REMOVE INSTRUCTIONS ========================
33 kldload ipfw.ko ; kldload dummynet.ko
35 kldunload dummynet.ko; kldunload ipfw.ko
39 # Do the following as root
40 insmod ./dummynet2/ipfw_mod.ko
41 cp ipfw/ipfw /usr/local/sbin
46 INSTALL: # use the correct name for your system
47 opkg install kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
48 ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
49 insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
50 /lib/modules/2.4.35.4/ipfw show # launch the userspace tool
52 rmmod ipfw_mod.o # remove the module
55 INSTALL THE NDIS DRIVER
57 - open the configuration panel for the network card in use
58 (right click on the icon on the SYSTRAY, or go to
59 Control Panel -> Network and select one card)
61 - click on Properties->Install->Service->Add
62 - click on 'Driver Disk' and select 'netipfw.inf' in this folder
63 - select 'ipfw+dummynet' which is the only service you should see
64 - click accept on the warnings for the installation of an unknown
65 driver (roughly twice per existing network card)
67 Now you are ready to use the emulator. To configure it, open a 'cmd'
68 window and you can use the ipfw command from the command line.
69 Otherwise click on the 'TESTME.bat' which is a batch program that
73 - select a network card as above.
75 - select 'ipfw+dummynet'
79 =================== BUILD INSTRUCTIONS ==========================
81 ***** Windows (XPi, Windows7) ******
82 You can find a pre-built version in the binary/ subdirectory.
83 To build your own version of the package you need:
84 - MSVC DDK available from
85 http://msdn.microsoft.com/en-us/windows/hardware/gg487463.aspx
87 - optionally, DbgView if you want to see diagnostic
88 http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
90 - cygwin, http://www.cygwin.com/
91 with base packages, make, c compiler, possibly an editor
92 and subversion (suggest: tortoiseSvn)
94 Edit Makefile in the root directory, and set configuration
95 variables to match your current system (hard drive
96 and path where DDK is installed)
97 Open a shell from cygwin, move to this directory, and simply
98 run "make". The output of the build will be in this
99 directory, made of 4 files:
100 ipfw.exe (you also need cygwin.dll)
101 ipfw.sys (an NDIS intermediate filter driver)
102 dummynet.inf and dummynet_m.inf (installer files)
104 Cross compilation of the userland side under FreeBSD is possible with
105 gmake TCC=`pwd`/tcc-0.9.25-bsd/win32 CC=`pwd`/tcc-0.9.25-bsd/win32/bin/wintcc
106 (wintcc is a custom version of tcc which produces Windows code)
108 ***** Windows crosscompilation for 64 bit using DDK ******
109 Edit root directory's Makefile and set target
111 From the root directory, run 'make win64', this will:
112 - create ipfw-64 and dummynet2-64 subdirs
113 - patch ipfw makefile to support comunication
114 with 64bit module and build it
115 - replace dummynet makefile with proprietary
116 WinDDK one, named 'sources', and build the module
117 - create a binary64 directory containing
118 module and .inf install files, program
119 binary and relative cygwin dll
120 - install the driver from this directory in the
123 ***** Linux 2.6.x ******
125 make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
127 where the two variables are optional an point to the linux kernel
128 sources and the /usr directory. Defaults are USRDIR=/usr and
129 KERNELPATH=/lib/modules/`uname -r`/build --- XXX check ?
131 NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
132 configuration file. You need the ncurses devel library,
133 that can be installed according your distro with:
134 apt-get install ncurses-dev # for debian based distro
135 yum -y install ncurses-dev # for fedora based distro
136 You can enable CONFIG_NETFILTER by doing:
138 "(cd ${KERNELPATH}; make menuconfig)"
140 and enabling the option listed below:
143 Networking options --->
144 [*] Network packet filtering framework (Netfilter)
146 If you have not yet compiled your kernel source, you need to
147 prepare the build environment:
149 (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
151 ***** Linux 2.4.x *****
153 Almost as above, with an additional VER=2.4
155 make VER=2.4 KERNELPATH=...
157 For 2.4, if KERNELPATH is not specified then we use
158 KERNELPATH ?= /usr/src/`uname -r`/build
160 You need to follow the same instruction for the 2.6 kernel, enabling
161 netfilter in the kernel options:
163 Networking options --->
164 [*] Network packet filtering (replaces ipchains)
166 ***** Openwrt package *****
168 (Tested with kamikaze_8.09.1 and Linux 2.4)
170 + Download and extract the OpenWrt package, e.g.
172 wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
173 tar xvjf kamikaze_8.09.1_source.tar.bz2
175 + move to the directory with the OpenWrt sources (the one that
176 contains Config.in, rules.mk ...)
180 + Optional: Add support for 1ms resolution.
182 By default OpenWRT kernel is compiled with HZ=100; this implies
183 that all timeouts are rounded to 10ms, too coarse for dummynet.
184 The file 020-mips-hz1000.patch contains a kernel patch to build
185 a kernel with HZ=1000 (i.e. 1ms resolution) as in Linux/FreeBSD.
186 To apply this patch, go in the kernel source directory and
189 cd build_dir/linux-brcm-2.4/linux-2.4.35.4
190 cat $IPFW3_SOURCES/020-mips-hz1000.patch | patch -p0
192 where IPFW3_SOURCES contains the ipfw3 source code.
193 Now, the next kernel recompilation will use the right HZ value
195 + Optional: to be sure that the tools are working, make a first
198 - run "make menuconfig" and set the correct target device,
200 - run "make" to do the build
202 + Add ipfw3 to the openwrt package, as follows:
204 - copy the code from this directory to the place used for the build:
206 cp -Rp /path_to_ipfw3 ../ipfw3;
208 If you want, you can fetch a newer version from the web
209 (cd ..; rm -rf ipfw3; \
210 wget http://info.iet.unipi.it/~luigi/dummynet/ipfw3-latest.tgz;\
211 tar xvzf ipfw3-latest.tgz)
213 - run the following commands:
214 (mkdir package/ipfw3; \
215 cp ../ipfw3/Makefile.openwrt package/ipfw3/Makefile)
217 to create the package/ipfw3 directory in the OpenWrt source
218 directory, and copy Makefile.openwrt to package/ipfw3/Makefile ;
220 - if necessary, edit package/ipfw3/Makefile and set IPFW_DIR to point to
221 the directory ipfw3, which contains the sources;
223 - run "make menuconfig" and select kmod-ipfw3 as a module <M> in
224 Kernel Modules -> Other modules -> kmod-ipfw3
226 - run "make" to build the package, "make V=99" for verbose build.
228 - to modify the code, assuming you are in directory "kamikaze_8.09.1"
230 (cd ../ipfw3 && vi ...the files you are interested in )
231 rm -rf build_dir/linux-brcm-2.4/kmod-ipfw3
232 make package/ipfw3/compile V=99
234 The resulting package is located in bin/packages/mipsel/kmod-ipfw3*,
235 upload the file and install on the target system, as follows:
237 opkg install kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
238 ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
239 insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
240 /lib/modules/2.4.35.4/ipfw show # launch the userspace tool
241 rmmod ipfw_mod.o # remove the module
243 ***** PLANETLAB BUILD (within a slice) *****
244 These instruction can be used by PlanetLab developers to compile
245 the dummynet module on a node. To install the module on the node
246 users need root access in root context. PlanetLab users that want
247 to use the dummynet package should ask to PlanetLab support for
248 nodes with dummynet emulation capabilities.
250 Follow the instructions below. You can just cut&paste
252 # install the various tools if not available
253 sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
254 # new build installation requires the gnupg package
255 sudo yum -y install gnupg
256 # the linux kernel and the ipfw source can be fetched by git
257 sudo yum -y install git
259 # create and move to a work directory
261 # extract a planetlab distribution to directory XYZ
262 (cd test; git clone git://git.onelab.eu/build ./XYZ)
263 # download the specfiles and do some patching.
264 # Results are into SPEC/ (takes 5 minutes)
265 (cd test/XYZ; make stage1=true PLDISTRO=onelab)
266 # Building the slice code is fast, the root code takes longer
267 # as it needs to rebuild the whole kernel
268 (cd test/XYZ; sudo make ipfwslice PLDISTRO=onelab)
269 (cd test/XYZ; sudo make ipfwroot PLDISTRO=onelab)
271 The kernel dependency phase is a bit time consuming, but does not
272 need to be redone if we are changing the ipfw sources only.
273 To clean up the code do
274 (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
275 then after you have updated the repository again
276 (cd test/XYZ; sudo make ipfwslice ipfwroot)
279 [1] https://svn.planet-lab.org/wiki/VserverCentos
280 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
281 [3] http://mirror.centos.org/centos/5/isos/
282 [4] More information are in /build/README* files