README

   1 #
   2 # $Id: README 11691 2012-08-12 21:32:37Z luigi $
   3 #
   4
   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.
  11
  12 Specific build instructions are below, and in general produce
  13
  14         a kernel module,        ipfw_mod.ko (ipfw.sys on windows)
  15         a userland program,     /sbin/ipfw (ipfw.exe on windows)
  16
  17 which you need to install on your system.
  18
  19 CREDITS:
  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)
  28
  29 ------ INSTALL/REMOVE INSTRUCTIONS ------
  30
  31 Linux
  32     INSTALL:
  33         # Do the following as root
  34         insmod ./dummynet2/ipfw_mod.ko
  35         cp ipfw/ipfw /usr/local/sbin
  36     REMOVE:
  37         rmmod ipfw_mod.ko
  38
  39 OpenWRT
  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
  45     REMOVE:
  46         rmmod ipfw_mod.o                            # remove the module
  47
  48 Windows:
  49     A pre-built version is in binary/ and binary64/ directories.
  50
  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)
  60
  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
  65         runs various tests.
  66         REMEMBER: you need to run ipfw as administrator.
  67
  68     REMOVE:
  69         - select a network card as above.
  70         - click on Properties
  71         - select 'ipfw+dummynet'
  72         - click on 'Remove'
  73
  74
  75 ------ BUILD INSTRUCTIONS ------
  76
  77 + Windows 32 bit and 64 bit (XP, Windows7)
  78
  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
  83
  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.
  88
  89         - optionally, DbgView if you want to see diagnostics coming from
  90           the kernel module. You can find it at
  91
  92             http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
  93
  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
 100     following files:
 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)
 104
 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)
 108
 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.
 115
 116 ***** Linux 2.6 and above ******
 117
 118         make [KSRC=/path/to/linux USRDIR=/path/to/usr]
 119
 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 ?
 123
 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:
 130
 131         "(cd ${KSRC}; make menuconfig)"
 132
 133     and enabling the option listed below:
 134
 135         Networking --->
 136             Networking options  --->
 137               [*] Network packet filtering framework (Netfilter)
 138
 139     If you have not yet compiled your kernel source, you need to
 140     prepare the build environment:
 141
 142         (cd $(KSRC); make oldconfig; make prepare; make scripts)
 143
 144 ***** Linux 2.4.x *****
 145
 146     Almost as above, with an additional VER=2.4
 147
 148         make VER=2.4 KSRC=...
 149
 150     For 2.4, if KSRC is not specified then we use
 151         KSRC ?= /usr/src/`uname -r`/build
 152
 153     You need to follow the same instruction for the 2.6 kernel, enabling
 154     netfilter in the kernel options:
 155
 156     Networking options  --->
 157       [*] Network packet filtering (replaces ipchains)
 158
 159 ***** Openwrt package *****
 160
 161     (Tested with kamikaze_8.09.1 and Linux 2.4)
 162
 163     + Download and extract the OpenWrt package, e.g.
 164
 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
 167
 168     + move to the directory with the OpenWrt sources (the one that
 169       contains Config.in, rules.mk ...)
 170
 171         cd kamikaze_8.09.1
 172
 173     + Optional: Add support for 1ms resolution.
 174
 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
 180         patch the kernel
 181
 182                 cd build_dir/linux-brcm-2.4/linux-2.4.35.4
 183                 cat $IPFW3_SOURCES/020-mips-hz1000.patch | patch -p0
 184
 185         where IPFW3_SOURCES contains the ipfw3 source code.
 186         Now, the next kernel recompilation will use the right HZ value
 187
 188     + Optional: to be sure that the tools are working, make a first
 189       build as follows:
 190
 191         - run "make menuconfig" and set the correct target device,
 192           drivers, and so on;
 193         - run "make" to do the build
 194
 195     + Add ipfw3 to the openwrt package, as follows:
 196
 197       - copy the code from this directory to the place used for the build:
 198
 199                 cp -Rp /path_to_ipfw3 ../ipfw3;
 200
 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)
 205
 206       - run the following commands:
 207         (mkdir package/ipfw3; \
 208         cp ../ipfw3/Makefile.openwrt package/ipfw3/Makefile)
 209
 210         to create the package/ipfw3 directory in the OpenWrt source
 211         directory, and copy Makefile.openwrt to package/ipfw3/Makefile ;
 212
 213       - if necessary, edit package/ipfw3/Makefile and set IPFW_DIR to point to
 214         the directory ipfw3, which contains the sources;
 215
 216       - run "make menuconfig" and select kmod-ipfw3 as a module <M> in
 217             Kernel Modules -> Other modules -> kmod-ipfw3
 218
 219       - run "make" to build the package, "make V=99" for verbose build.
 220
 221       - to modify the code, assuming you are in directory "kamikaze_8.09.1"
 222
 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
 226
 227     The resulting package is located in bin/packages/mipsel/kmod-ipfw3*,
 228     upload the file and install on the target system, as follows:
 229
 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
 235
 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.
 242
 243     Follow the instructions below. You can just cut&paste
 244
 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
 251
 252         # create and move to a work directory
 253         mkdir -p test
 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)
 263
 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)
 270
 271 --- References
 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