2 # $Id: README 11691 2012-08-12 21:32:37Z luigi $
5 This directory contains a port of ipfw and dummynet to Linux and Windows.
6 This version of ipfw and dummynet is called "ipfw3" as it is the
7 third major rewrite of the code. The source code here comes straight
8 from FreeBSD (roughly the version in HEAD as of February 2010),
9 plus some glue code and headers written from scratch. Unless
10 specified otherwise, all the code here is under a BSD license.
12 Specific build instructions are below, and in general produce
14 a kernel module, ipfw_mod.ko (ipfw.sys on windows)
15 a userland program, /sbin/ipfw (ipfw.exe on windows)
17 which you need to install on your system.
20 Luigi Rizzo (main design and development)
21 Marta Carbone (Linux and Planetlab ports)
22 Riccardo Panicucci (modular scheduler support)
23 Francesco Magno (Windows port)
24 Fabio Checconi (the QFQ scheduler)
25 Funding from Universita` di Pisa (NETOS project),
26 European Commission (ONELAB2 project)
27 ACM SIGCOMM (Sigcomm Community Projects Award, April 2012)
29 ------ INSTALL/REMOVE INSTRUCTIONS ------
33 # Do the following as root
34 insmod ./dummynet2/ipfw_mod.ko
35 cp ipfw/ipfw /usr/local/sbin
40 INSTALL: # use the correct name for your system
41 opkg install kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
42 ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
43 insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
44 /lib/modules/2.4.35.4/ipfw show # launch the userspace tool
46 rmmod ipfw_mod.o # remove the module
49 A pre-built version is in binary/ and binary64/ directories.
51 INSTALL THE NDIS DRIVER
52 - open the configuration panel for the network card in use
53 (right click on the icon on the SYSTRAY, or go to
54 Control Panel -> Network and select one card)
55 - click on Properties->Install->Service->Add
56 - click on 'Driver Disk' and select 'netipfw.inf' in this folder
57 - select 'ipfw+dummynet' which is the only service you should see
58 - click accept on the warnings for the installation of an unsigned
59 driver (roughly twice per existing network card)
61 Now you are ready to use the emulator. To configure it, open a 'cmd'
62 window (REMEMBER to run it as Administrator)
63 and you can use the ipfw command from the command line.
64 Otherwise click on the 'TESTME.bat' which is a batch program that
66 REMEMBER: you need to run ipfw as administrator.
69 - select a network card as above.
71 - select 'ipfw+dummynet'
75 ------ BUILD INSTRUCTIONS ------
77 + Windows 32 bit and 64 bit (XP, Windows7)
79 To build your own version of the package you need:
80 - cygwin, http://www.cygwin.com/ with base packages, make,
81 c compiler, possibly an editor and subversion.
82 This is used to build the userspace control program, ipfw.exe
84 - Microsoft Windows Driver Kit Version 7.1.0, available from
85 http://www.microsoft.com/en-us/download/details.aspx?id=11800
86 (ISO image, GRMWDK_EN_7600_1.ISO)
87 This is used to build the kernel module.
89 - optionally, DbgView if you want to see diagnostics coming from
90 the kernel module. You can find it at
92 http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
94 Check the Makefile in the root directory to make sure that the WDK is
95 installed in the place indicated by DRIVE and DDKDIR variables
96 (otherwise pass the correct values to the Makefile).
97 Open a shell from cygwin, move to this directory, and run "make" for
98 the 32-bit version, "make win64" for the 64 bit version.
99 This will produce in the binary/ or binary64/ directory the
101 ipfw.exe (you also need cygwin1.dll)
102 ipfw.sys (an NDIS intermediate filter driver)
103 netipfw.inf and netipfw_m.inf (installer files)
105 Cross compilation of the userland side under FreeBSD is possible with
106 gmake TCC=`pwd`/tcc-0.9.25-bsd/win32 CC=`pwd`/tcc-0.9.25-bsd/win32/bin/wintcc
107 (wintcc is a custom version of tcc which produces Windows code)
109 NOTE: the 64-bit version is compiled as a 32-bit executable for userspace,
110 with appropriate changes to produce 64-bit pointers.
111 The kernel module is built using the MSC 'build' utility instead
112 of 'make'. THE MODULE IS NOT SIGNED.
113 IMPORTANT: Windows 64-bit will not load unsigned kernel modules unless
114 you boot with 'F8' and disable checks for signed modules.
116 ***** Linux 2.6 and above ******
118 make [KSRC=/path/to/linux USRDIR=/path/to/usr]
120 where the two variables are optional an point to the linux kernel
121 sources and the /usr directory. Defaults are USRDIR=/usr and
122 KSRC=/lib/modules/`uname -r`/build --- XXX check ?
124 NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
125 configuration file. You need the ncurses devel library,
126 that can be installed according your distro with:
127 apt-get install ncurses-dev # for debian based distro
128 yum -y install ncurses-dev # for fedora based distro
129 You can enable CONFIG_NETFILTER by doing:
131 "(cd ${KSRC}; make menuconfig)"
133 and enabling the option listed below:
136 Networking options --->
137 [*] Network packet filtering framework (Netfilter)
139 If you have not yet compiled your kernel source, you need to
140 prepare the build environment:
142 (cd $(KSRC); make oldconfig; make prepare; make scripts)
144 ***** Linux 2.4.x *****
146 Almost as above, with an additional VER=2.4
148 make VER=2.4 KSRC=...
150 For 2.4, if KSRC is not specified then we use
151 KSRC ?= /usr/src/`uname -r`/build
153 You need to follow the same instruction for the 2.6 kernel, enabling
154 netfilter in the kernel options:
156 Networking options --->
157 [*] Network packet filtering (replaces ipchains)
159 ***** Openwrt package *****
161 (Tested with kamikaze_8.09.1 and Linux 2.4)
163 + Download and extract the OpenWrt package, e.g.
165 wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
166 tar xvjf kamikaze_8.09.1_source.tar.bz2
168 + move to the directory with the OpenWrt sources (the one that
169 contains Config.in, rules.mk ...)
173 + Optional: Add support for 1ms resolution.
175 By default OpenWRT kernel is compiled with HZ=100; this implies
176 that all timeouts are rounded to 10ms, too coarse for dummynet.
177 The file 020-mips-hz1000.patch contains a kernel patch to build
178 a kernel with HZ=1000 (i.e. 1ms resolution) as in Linux/FreeBSD.
179 To apply this patch, go in the kernel source directory and
182 cd build_dir/linux-brcm-2.4/linux-2.4.35.4
183 cat $IPFW3_SOURCES/020-mips-hz1000.patch | patch -p0
185 where IPFW3_SOURCES contains the ipfw3 source code.
186 Now, the next kernel recompilation will use the right HZ value
188 + Optional: to be sure that the tools are working, make a first
191 - run "make menuconfig" and set the correct target device,
193 - run "make" to do the build
195 + Add ipfw3 to the openwrt package, as follows:
197 - copy the code from this directory to the place used for the build:
199 cp -Rp /path_to_ipfw3 ../ipfw3;
201 If you want, you can fetch a newer version from the web
202 (cd ..; rm -rf ipfw3; \
203 wget http://info.iet.unipi.it/~luigi/dummynet/ipfw3-latest.tgz;\
204 tar xvzf ipfw3-latest.tgz)
206 - run the following commands:
207 (mkdir package/ipfw3; \
208 cp ../ipfw3/Makefile.openwrt package/ipfw3/Makefile)
210 to create the package/ipfw3 directory in the OpenWrt source
211 directory, and copy Makefile.openwrt to package/ipfw3/Makefile ;
213 - if necessary, edit package/ipfw3/Makefile and set IPFW_DIR to point to
214 the directory ipfw3, which contains the sources;
216 - run "make menuconfig" and select kmod-ipfw3 as a module <M> in
217 Kernel Modules -> Other modules -> kmod-ipfw3
219 - run "make" to build the package, "make V=99" for verbose build.
221 - to modify the code, assuming you are in directory "kamikaze_8.09.1"
223 (cd ../ipfw3 && vi ...the files you are interested in )
224 rm -rf build_dir/linux-brcm-2.4/kmod-ipfw3
225 make package/ipfw3/compile V=99
227 The resulting package is located in bin/packages/mipsel/kmod-ipfw3*,
228 upload the file and install on the target system, as follows:
230 opkg install kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
231 ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
232 insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
233 /lib/modules/2.4.35.4/ipfw show # launch the userspace tool
234 rmmod ipfw_mod.o # remove the module
236 ***** PLANETLAB BUILD (within a slice) *****
237 These instruction can be used by PlanetLab developers to compile
238 the dummynet module on a node. To install the module on the node
239 users need root access in root context. PlanetLab users that want
240 to use the dummynet package should ask to PlanetLab support for
241 nodes with dummynet emulation capabilities.
243 Follow the instructions below. You can just cut&paste
245 # install the various tools if not available
246 sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
247 # new build installation requires the gnupg package
248 sudo yum -y install gnupg
249 # the linux kernel and the ipfw source can be fetched by git
250 sudo yum -y install git
252 # create and move to a work directory
254 # extract a planetlab distribution to directory XYZ
255 (cd test; git clone git://git.onelab.eu/build ./XYZ)
256 # download the specfiles and do some patching.
257 # Results are into SPEC/ (takes 5 minutes)
258 (cd test/XYZ; make stage1=true PLDISTRO=onelab)
259 # Building the slice code is fast, the root code takes longer
260 # as it needs to rebuild the whole kernel
261 (cd test/XYZ; sudo make ipfwslice PLDISTRO=onelab)
262 (cd test/XYZ; sudo make ipfwroot PLDISTRO=onelab)
264 The kernel dependency phase is a bit time consuming, but does not
265 need to be redone if we are changing the ipfw sources only.
266 To clean up the code do
267 (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
268 then after you have updated the repository again
269 (cd test/XYZ; sudo make ipfwslice ipfwroot)
272 [1] https://svn.planet-lab.org/wiki/VserverCentos
273 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
274 [3] http://mirror.centos.org/centos/5/isos/
275 [4] More information are in /build/README* files