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
 #
-# $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
-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.
 
-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 ==========================
 
+***** 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
@@ -28,7 +129,11 @@ Note:
     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)"
 
@@ -38,8 +143,8 @@ Note:
            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)
 
@@ -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
 
-    + "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:
 
       - 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
-       (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:
-       (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"
        
-       (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:
 
-    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) *****
-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
 
@@ -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
+       # 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; 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)
-       (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
-       (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.
@@ -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)
 
---- 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