#
-# $Id: README 4396 2009-12-09 21:52:46Z luigi $
+# $Id: README 8977 2011-07-04 11:47:59Z luigi $
#
-This directory contains a port of ipfw and dummynet to Linux and OpenWrt
-(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
-
+This directory contains a port of ipfw and dummynet to Linux/OpenWrt
+(including PlanetLab) and Windows. This version of ipfw and dummynet
+is called "ipfw3" as it is the third major rewrite of the code.
The source code here comes straight from FreeBSD (roughly the
-version in RELENG_7 and HEAD as of December 2009), plus some glue code
+version in HEAD as of February 2010), plus some glue code
and headers written from scratch.
Unless specified otherwise, all the code here is under a BSD license.
+Specific build instructions are below, and in general produce
+
+ a kernel module, ipfw_mod.ko (ipfw.sys on windows)
+ a userland program, /sbin/ipfw (ipfw.exe on windows)
+
+which you need to install on your system.
+
+CREDITS:
+ Luigi Rizzo (main design and development)
+ Marta Carbone (Linux and Planetlab ports)
+ Riccardo Panicucci (modular scheduler support)
+ Francesco Magno (Windows port)
+ Fabio Checconi (the QFQ scheduler)
+ Funding from Universita` di Pisa (NETOS project),
+ European Commission (ONELAB2 project)
+
+=========== INSTALL/REMOVE INSTRUCTIONS ========================
+
+FreeBSD, OSX:
+ INSTALL:
+ kldload ipfw.ko ; kldload dummynet.ko
+ REMOVE:
+ kldunload dummynet.ko; kldunload ipfw.ko
+
+Linux
+ INSTALL:
+ # Do the following as root
+ insmod ./dummynet2/ipfw_mod.ko
+ cp ipfw/ipfw /usr/local/sbin
+ REMOVE:
+ rmmod ipfw_mod.ko
+
+OpenWRT
+ INSTALL: # use the correct name for your system
+ opkg install kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
+ ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
+ insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
+ /lib/modules/2.4.35.4/ipfw show # launch the userspace tool
+ REMOVE:
+ rmmod ipfw_mod.o # remove the module
+
+Windows:
+ INSTALL THE NDIS DRIVER
+
+ - open the configuration panel for the network card in use
+ (right click on the icon on the SYSTRAY, or go to
+ Control Panel -> Network and select one card)
+
+ - click on Properties->Install->Service->Add
+ - click on 'Driver Disk' and select 'netipfw.inf' in this folder
+ - select 'ipfw+dummynet' which is the only service you should see
+ - click accept on the warnings for the installation of an unknown
+ driver (roughly twice per existing network card)
+
+ Now you are ready to use the emulator. To configure it, open a 'cmd'
+ window and you can use the ipfw command from the command line.
+ Otherwise click on the 'TESTME.bat' which is a batch program that
+ runs various tests.
+
+ REMOVE:
+ - select a network card as above.
+ - click on Properties
+ - select 'ipfw+dummynet'
+ - click on 'Remove'
+
+
=================== BUILD INSTRUCTIONS ==========================
+***** Windows (XPi, Windows7) ******
+ You can find a pre-built version in the binary/ subdirectory.
+ To build your own version of the package you need:
+ - MSVC DDK available from
+ http://msdn.microsoft.com/en-us/windows/hardware/gg487463.aspx
+
+ - optionally, DbgView if you want to see diagnostic
+ http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
+
+ - cygwin, http://www.cygwin.com/
+ with base packages, make, c compiler, possibly an editor
+ and subversion (suggest: tortoiseSvn)
+
+ Edit Makefile in the root directory, and set configuration
+ variables to match your current system (hard drive
+ and path where DDK is installed)
+ Open a shell from cygwin, move to this directory, and simply
+ run "make". The output of the build will be in this
+ directory, made of 4 files:
+ ipfw.exe (you also need cygwin.dll)
+ ipfw.sys (an NDIS intermediate filter driver)
+ dummynet.inf and dummynet_m.inf (installer files)
+
+ Cross compilation of the userland side under FreeBSD is possible with
+ gmake TCC=`pwd`/tcc-0.9.25-bsd/win32 CC=`pwd`/tcc-0.9.25-bsd/win32/bin/wintcc
+ (wintcc is a custom version of tcc which produces Windows code)
+
+***** Windows crosscompilation for 64 bit using DDK ******
+ Edit root directory's Makefile and set target
+ operating system
+ From the root directory, run 'make win64', this will:
+ - create ipfw-64 and dummynet2-64 subdirs
+ - patch ipfw makefile to support comunication
+ with 64bit module and build it
+ - replace dummynet makefile with proprietary
+ WinDDK one, named 'sources', and build the module
+ - create a binary64 directory containing
+ module and .inf install files, program
+ binary and relative cygwin dll
+ - install the driver from this directory in the
+ usual way.
+
***** Linux 2.6.x ******
make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
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
+ configuration file. You need the ncurses devel library,
+ that can be installed according your distro with:
+ apt-get install ncurses-dev # for debian based distro
+ yum -y install ncurses-dev # for fedora based distro
+ You can enable CONFIG_NETFILTER by doing:
"(cd ${KERNELPATH}; make menuconfig)"
Networking options --->
[*] Network packet filtering framework (Netfilter)
+ If you have not yet compiled your kernel source, you need to
+ prepare the build environment:
+
+ (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
***** Linux 2.4.x *****
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
netfilter in the kernel options:
wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
tar xvjf kamikaze_8.09.1_source.tar.bz2
- + "cd" to the directory with the OpenWrt sources (the one that
+ + move to the directory with the OpenWrt sources (the one that
contains Config.in, rules.mk ...)
cd kamikaze_8.09.1
+ + Optional: Add support for 1ms resolution.
+
+ By default OpenWRT kernel is compiled with HZ=100; this implies
+ that all timeouts are rounded to 10ms, too coarse for dummynet.
+ The file 020-mips-hz1000.patch contains a kernel patch to build
+ a kernel with HZ=1000 (i.e. 1ms resolution) as in Linux/FreeBSD.
+ To apply this patch, go in the kernel source directory and
+ patch the kernel
+
+ cd build_dir/linux-brcm-2.4/linux-2.4.35.4
+ cat $IPFW3_SOURCES/020-mips-hz1000.patch | patch -p0
+
+ where IPFW3_SOURCES contains the ipfw3 source code.
+ Now, the next kernel recompilation will use the right HZ value
+
+ Optional: to be sure that the tools are working, make a first
- compilation as follows:
+ build as follows:
- run "make menuconfig" and set the correct target device,
drivers, and so on;
- run "make" to do the build
- + Add ipfw2 to the openwrt package, as follows:
+ + Add ipfw3 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-20090724.tgz;\
- tar xvzf ipfw_linux-20090724.tgz; mv ipfw_linux-20090724 ipfw_mod;)
+ cp -Rp /path_to_ipfw3 ../ipfw3;
- (but you should have done it already)
+ If you want, you can fetch a newer version from the web
+ (cd ..; rm -rf ipfw3; \
+ wget http://info.iet.unipi.it/~luigi/dummynet/ipfw3-latest.tgz;\
+ tar xvzf ipfw3-latest.tgz)
- run the following commands:
- (mkdir package/ipfw2;
- cp ../ipfw_linux/Makefile.openwrt package/ipfw2/Makefile)
+ (mkdir package/ipfw3; \
+ cp ../ipfw3/Makefile.openwrt package/ipfw3/Makefile)
- to create the package/ipfw2 directory in the OpenWrt source
- directory, and copy Makefile.openwrt to package/ipfw2/Makefile:
+ to create the package/ipfw3 directory in the OpenWrt source
+ directory, and copy Makefile.openwrt to package/ipfw3/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);
+ - if necessary, edit package/ipfw3/Makefile and set IPFW_DIR to point to
+ the directory ipfw3, which contains the sources;
- - run "make menuconfig" and select ipfw2 as a module <M> in
- Kernel Modules -> Other modules -> ipfw2
+ - run "make menuconfig" and select kmod-ipfw3 as a module <M> in
+ Kernel Modules -> Other modules -> kmod-ipfw3
- run "make" to build the package, "make V=99" for verbose build.
- The resulting package is located in bin/packages/mipsel/kmod-ipfw2*,
+ - to modify the code, assuming you are in directory "kamikaze_8.09.1"
+
+ (cd ../ipfw3 && vi ...the files you are interested in )
+ rm -rf build_dir/linux-brcm-2.4/kmod-ipfw3
+ make package/ipfw3/compile V=99
+
+ The resulting package is located in bin/packages/mipsel/kmod-ipfw3*,
upload the file and install on the target system, as follows:
- opkg install kmod-ipfw2_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
+ opkg install kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
ls -l ls -l /lib/modules/2.4.35.4/ipfw* # check
insmod /lib/modules/2.4.35.4/ipfw_mod.o # load the module
/lib/modules/2.4.35.4/ipfw show # launch the userspace tool
rmmod ipfw_mod.o # remove the module
-***** PLANETLAB BUILD *****
-
------------------------------------------------------------------------------
+***** 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
+ # the linux kernel and the ipfw source can be fetched by git
+ sudo yum -y install git
+
+ # create and move to a work directory
+ mkdir -p test
+ # extract a planetlab distribution to directory XYZ
+ (cd test; git clone git://git.onelab.eu/build ./XYZ)
+ # download the specfiles and do some patching.
+ # Results are into SPEC/ (takes 5 minutes)
+ (cd test/XYZ; make stage1=true PLDISTRO=onelab)
+ # 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 PLDISTRO=onelab)
+ (cd test/XYZ; sudo make ipfwroot PLDISTRO=onelab)
+
+ 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)
+
+--- 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
git://git.onelab.eu / ipfw.git / blobdiff