This repo is obsolete, please see git://git.code.sf.net/p/dummynet/code@master

[ipfw.git] / README

diff --git a/README b/README
index 0c3b4e8..9c33bab 100644 (file)
--- a/README
+++ b/README
@@ -1,24 +1,125 @@
 #
 #

-# $Id: README 4502 2009-12-15 11:10:33Z marta $
+# $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
 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.
 
 and headers written from scratch.
 Unless specified otherwise, all the code here is under a BSD license.
 

-Note:
-       - the linux version miss the "one_pass" feature
+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 ==========================
 
 
 =================== 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
 ***** Linux 2.6.x ******
 
        make KERNELPATH=/path/to/linux USRDIR=/path/to/usr


@@ -28,7 +129,11 @@ Note:
     KERNELPATH=/lib/modules/`uname -r`/build   --- XXX check ?
 
     NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
     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)"
 
     
        "(cd ${KERNELPATH}; make menuconfig)"
 


@@ -38,8 +143,8 @@ Note:
            Networking options  --->
               [*] Network packet filtering framework (Netfilter)
 
            Networking options  --->
               [*] Network packet filtering framework (Netfilter)
 

-       If you have not yet compiled your kernel source, you need to
-       prepare the build environment:
+    If you have not yet compiled your kernel source, you need to
+    prepare the build environment:

 
        (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
 
 
        (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
 


@@ -67,64 +172,80 @@ Note:
        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
 
        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
 
       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
     + 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
 
 
        - 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:

 
       - copy the code from this directory to the place used for the build:
 
 
       - copy the code from this directory to the place used for the build:
 

-               cp -Rp /path_to_ipfw_mod ../ipfw_mod; 
+               cp -Rp /path_to_ipfw3 ../ipfw3; 

 
        If you want, you can fetch a newer version from the web
 
        If you want, you can fetch a newer version from the web

-       (cd ..; rm -rf ipfw_mod;
-       wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz;\
-       tar xvzf ipfw_mod-latest.tgz)
+       (cd ..; rm -rf ipfw3; \
+       wget http://info.iet.unipi.it/~luigi/dummynet/ipfw3-latest.tgz;\
+       tar xvzf ipfw3-latest.tgz)

 
       - run the following commands:
 
       - run the following commands:

-       (mkdir package/ipfw2;
-       cp ../ipfw_mod/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 ipfw_mod, which contains the ipfw sources
+      - 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 -> kmod-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.
 
       - to modify the code, assuming you are in directory "kamikaze_8.09.1"
        
 
       - run "make" to build the package, "make V=99" for verbose build.
 
       - to modify the code, assuming you are in directory "kamikaze_8.09.1"
        

-       (cd ../ipfw_mod && vi ...the files you are interested in )
-       rm -rf build_dir/linux-brcm-2.4/kmod-ipfw2
-       make package/ipfw2/compile V=99
+       (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-ipfw2*,
+    The resulting package is located in bin/packages/mipsel/kmod-ipfw3*,

     upload the file and install on the target system, as follows:
 
     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 (within a slice) *****
     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 (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.
+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
 
 
     Follow the instructions below. You can just cut&paste
 


@@ -132,19 +253,20 @@ for nodes with dummynet emulation capabilities.
        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
        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
 
        # create and move to a work directory
        mkdir -p test
        # extract a planetlab distribution to directory XYZ

-       (cd test; svn co http://svn.planet-lab.org/svn/build/trunk XYZ)
-       # copy the planetlab/*mk files here, overriding existing ones
-       cp planetlab/*mk test/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)
        # download the specfiles and do some patching.
        # Results are into SPEC/ (takes 5 minutes)

-       (cd test/XYZ; make stage1=true PLDISTRO=planetlab )
+       (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
        # 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 ipfwroot)
+       (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.
 
     The kernel dependency phase is a bit time consuming, but does not
     need to be redone if we are changing the ipfw sources only.


@@ -153,117 +275,6 @@ for nodes with dummynet emulation capabilities.
     then after you have updated the repository again
        (cd test/XYZ; sudo make ipfwslice ipfwroot)
 
     then after you have updated the repository again
        (cd test/XYZ; sudo make ipfwslice ipfwroot)
 

---- other, instructions (to be verified) ---
-
-To build a kernel module for the PlanetLab distribution you need a build system.
-For an up-to-date and detailed information on how to build a local myplc installation,
-a local mirror, a PlanetLab test system see[1]
-
-To create a build system you need to do the following steps:
-
- 1. install CentOS 5, detailed information[2]
-
- 1.A download the image from the main site[3] for example:
-
-       wget http://mi.mirror.garr.it/mirrors/CentOS/5.4/isos/i386/CentOS-5.4-i386-netinstall.iso
-
- 1.B Add the repository
-
-       cat >> /etc/yum.repos.d/dhozac-vserver.repo <<EOF
-       [dhozac-vserver]
-name=Linux-VServer related packages for CentOS $releasever - $basearch
-baseurl=http://rpm.hozac.com/dhozac/centos/$releasever/vserver/$basearch
-gpgkey=http://rpm.hozac.com/conf/keys/RPM-DHOZAC-GPG-KEY
-EOF
-
- 1.C Update, install and config the system
-
-       yum update yum
-       yum install kernel
-       yum install util-vserver{,-core,-lib,-sysv,-build}
-       yum install vim
-       yum install subversion
-       /etc/init.d/vprocunhide start
-       chkconfig vservers-default on
-
- 2. create a vserver
-
- 2.A Checkout the planetlab build
-
-       cd
-       svn co http://svn.planet-lab.org/svn/build/trunk svn-build
-
- 2.B Search for a working RPM distribution in:
-
-       http://build.onelab.eu/onelab/
-       # good distribution ends in .ok, bad in .ko
-       # in this example we used the following:
-       http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/
-
- 2.C Creating a vserver
-
-       cd ~/svn-build
-       ./vtest-init-vserver.sh -f f8 -d onelab -p linux32 mybuild \
-         http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/ \
-         -- --interface eth0:138.96.255.221 --hostname vnode01.inria.fr &> mybuild.log&
-
- 3. create the build
-
- 3.A Enter on the vserver, and create the build
-
-       vserver mybuild enter
-       cd \
-       svn co http://svn.planet-lab.org/svn/build/trunk build
-
- 4. build
-
- 4.A build[4]
-       cd /build
-
-       # full cleanup
-       make distclean
-
-       # the compilation is composed by several steps,
-       # make help for more information
-       # the first for the onelab compilation will download
-       # the SPEC file from the repository specified in
-       # onelab-tags.mk
-       make stage1=true PLDISTRO=onelab
-
-       # to download and build a module, for example ipfw:
-       make ipfw
-
-       # to do local changes
-       cd /build/CODEBASE
-       rm -rf ipfw
-       # download the ipfw sources and extract it into ./ipfw
-       # by svn
-       svn+ssh://onelab2.iet.unipi.it/home/svn/ports-luigi/dummynet-branches/ipfw_mod ./ipfw
-       # from web
-        wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz
-        tar xvzf ipfw_mod-latest.tgz
-
-       # start the compilation
-       rm -rf SOURCES/ipfw*
-       rm -rf BUILD/ipfw-0.1/
-       rm -rf SRPMS/ipfw*
-       rm -rf RPMS/i386/ipfw*
-       make ipfw
-
- 5. download and install sources into a node
-
- 5.A Copy RPMS into the node and install it:
-       # exit from the root context
-       exit
-       scp  /vserver/mybuild/build/RPMS/i386/ipfw-* root@node.iet.unipi.it:
-       ssh root@node.iet.unipi.it
-       rpm -e ipfw
-       rpm -ivh ./ipfw-0-9...TAB
-       modprobe ipfw_mod
-
-       # the ipfw package should be installed
-       ipfw show
-

 --- References
 [1] https://svn.planet-lab.org/wiki/VserverCentos
 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
 --- References
 [1] https://svn.planet-lab.org/wiki/VserverCentos
 [2] http://wiki.linux-vserver.org/Installation_on_CentOS