README

   1 #
   2 # $Id: README 6070 2010-04-15 11:58:21Z marta $
   3 #
   4
   5 This directory contains a port of ipfw and dummynet to Linux/OpenWrt
   6 (including PlanetLab) and Windows. This version of ipfw and dummynet
   7 is called "ipfw3" as it is the third major rewrite of the code.
   8 The source code here comes straight from FreeBSD (roughly the
   9 version in HEAD as of February 2010), plus some glue code
  10 and headers written from scratch.
  11 Unless specified otherwise, all the code here is under a BSD license.
  12
  13 Specific build instructions are below, and in general produce
  14
  15         a kernel module,        ipfw_mod.ko (ipfw.sys on windows)
  16         a userland program,     /sbin/ipfw (ipfw.exe on windows)
  17
  18 which you need to install on your system.
  19
  20 CREDITS:
  21     Luigi Rizzo (main design and development)
  22     Marta Carbone (Linux and Planetlab ports)
  23     Riccardo Panicucci (modular scheduler support)
  24     Francesco Magno (Windows port)
  25     Fabio Checconi (the QFQ scheduler)
  26     Funding from Universita` di Pisa (NETOS project),
  27         European Commission (ONELAB2 project)
  28
  29 =========== INSTALL/REMOVE INSTRUCTIONS ========================
  30
  31 FreeBSD, OSX:
  32     INSTALL:
  33         kldload ipfw.ko ; kldload dummynet.ko
  34     REMOVE:
  35         kldunload dummynet.ko; kldunload ipfw.ko
  36
  37 Linux
  38     INSTALL:
  39         # Do the following as root
  40         insmod ./dummynet2/ipfw_mod.ko
  41         cp ipfw/ipfw /usr/local/sbin
  42     REMOVE:
  43         rmmod ipfw_mod.ko
  44
  45 OpenWRT
  46     INSTALL:    # use the correct name for your system
  47         opkg install  kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
  48         ls -l ls -l /lib/modules/2.4.35.4/ipfw*     # check
  49         insmod /lib/modules/2.4.35.4/ipfw_mod.o     # load the module
  50         /lib/modules/2.4.35.4/ipfw show             # launch the userspace tool
  51     REMOVE:
  52         rmmod ipfw_mod.o                            # remove the module
  53
  54 Windows:
  55     INSTALL THE NDIS DRIVER
  56
  57         - open the configuration panel for the network card in use
  58           (right click on the icon on the SYSTRAY, or go to
  59           Control Panel -> Network and select one card)
  60
  61         - click on Properties->Install->Service->Add
  62         - click on 'Driver Disk' and select 'netipfw.inf' in this folder
  63         - select 'ipfw+dummynet' which is the only service you should see
  64         - click accept on the warnings for the installation of an unknown
  65           driver (roughly twice per existing network card)
  66
  67         Now you are ready to use the emulator. To configure it, open a 'cmd'
  68         window and you can use the ipfw command from the command line.
  69         Otherwise click on the 'TESTME.bat' which is a batch program that
  70         runs various tests.
  71
  72     REMOVE:
  73         - select a network card as above.
  74         - click on Properties
  75         - select 'ipfw+dummynet'
  76         - click on 'Remove'
  77
  78
  79 =================== BUILD INSTRUCTIONS ==========================
  80
  81 ***** Windows XP ******
  82     You can find a pre-built version in the binary/ subdirectory.
  83     To build your own version of the package you need:
  84         - MSVC DDK available from ...
  85             http://www.microsoft.com/whdc/DevTools/WDK/WDKpkg.mspx
  86
  87         - optionally, DbgView if you want to see diagnostic
  88             http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
  89
  90         - cygwin, http://www.cygwin.com/
  91           with base packages, make, c compiler, possibly an editor
  92           and subversion.
  93
  94     Edit Makefile in the root directory, and set configuration
  95     variables to match your current system (hard drive
  96     and path where DDK is installed)
  97     Open a shell from cygwin, move to this directory, and simply
  98     run "make". The output of the build will be in this
  99     directory, made of 4 files:
 100         ipfw.exe (you also need cygwin.dll)
 101         ipfw.sys (an NDIS intermediate filter driver)
 102         dummynet.inf and dummynet_m.inf (installer files)
 103
 104 ***** Windows crosscompilation for 64 bit using DDK ******
 105     Edit root directory's Makefile and set target
 106     operating system
 107     From the root directory, run 'make win64', this will:
 108     - create ipfw-64 and dummynet2-64 subdirs
 109     - patch ipfw makefile to support comunication
 110     with 64bit module and build it
 111     - replace dummynet makefile with proprietary
 112     WinDDK one, named 'sources', and build the module
 113     - create a binary64 directory containing
 114     module and .inf install files, program
 115     binary and relative cygwin dll
 116     - install the driver from this directory in the
 117     usual way.
 118
 119 ***** Linux 2.6.x ******
 120
 121         make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
 122
 123     where the two variables are optional an point to the linux kernel
 124     sources and the /usr directory. Defaults are USRDIR=/usr and
 125     KERNELPATH=/lib/modules/`uname -r`/build    --- XXX check ?
 126
 127     NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
 128     configuration file. You need the ncurses devel library,
 129     that can be installed according your distro with:
 130         apt-get install ncurses-dev     # for debian based distro
 131         yum -y install ncurses-dev      # for fedora based distro
 132     You can enable CONFIG_NETFILTER by doing:
 133
 134         "(cd ${KERNELPATH}; make menuconfig)"
 135
 136     and enabling the option listed below:
 137
 138         Networking --->
 139             Networking options  --->
 140               [*] Network packet filtering framework (Netfilter)
 141
 142     If you have not yet compiled your kernel source, you need to
 143     prepare the build environment:
 144
 145         (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
 146
 147 ***** Linux 2.4.x *****
 148
 149     Almost as above, with an additional VER=2.4
 150
 151         make VER=2.4 KERNELPATH=...
 152
 153     For 2.4, if KERNELPATH is not specified then we use
 154         KERNELPATH ?= /usr/src/`uname -r`/build
 155
 156     You need to follow the same instruction for the 2.6 kernel, enabling
 157     netfilter in the kernel options:
 158
 159     Networking options  --->
 160       [*] Network packet filtering (replaces ipchains)
 161
 162 ***** Openwrt package *****
 163
 164     (Tested with kamikaze_8.09.1 and Linux 2.4)
 165
 166     + Download and extract the OpenWrt package, e.g.
 167
 168         wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
 169         tar xvjf kamikaze_8.09.1_source.tar.bz2
 170
 171     + move to the directory with the OpenWrt sources (the one that
 172       contains Config.in, rules.mk ...)
 173
 174         cd kamikaze_8.09.1
 175
 176     + Optional: Add support for 1ms resolution.
 177
 178         By default OpenWRT kernel is compiled with HZ=100; this implies
 179         that all timeouts are rounded to 10ms, too coarse for dummynet.
 180         The file 020-mips-hz1000.patch contains a kernel patch to build
 181         a kernel with HZ=1000 (i.e. 1ms resolution) as in Linux/FreeBSD.
 182         To apply this patch, go in the kernel source directory and
 183         patch the kernel
 184
 185                 cd build_dir/linux-brcm-2.4/linux-2.4.35.4
 186                 cat $IPFW3_SOURCES/020-mips-hz1000.patch | patch -p0
 187
 188         where IPFW3_SOURCES contains the ipfw3 source code.
 189         Now, the next kernel recompilation will use the right HZ value
 190
 191     + Optional: to be sure that the tools are working, make a first
 192       build as follows:
 193
 194         - run "make menuconfig" and set the correct target device,
 195           drivers, and so on;
 196         - run "make" to do the build
 197
 198     + Add ipfw3 to the openwrt package, as follows:
 199
 200       - copy the code from this directory to the place used for the build:
 201
 202                 cp -Rp /path_to_ipfw3 ../ipfw3;
 203
 204         If you want, you can fetch a newer version from the web
 205         (cd ..; rm -rf ipfw3; \
 206         wget http://info.iet.unipi.it/~luigi/dummynet/ipfw3-latest.tgz;\
 207         tar xvzf ipfw3-latest.tgz)
 208
 209       - run the following commands:
 210         (mkdir package/ipfw3; \
 211         cp ../ipfw3/Makefile.openwrt package/ipfw3/Makefile)
 212
 213         to create the package/ipfw3 directory in the OpenWrt source
 214         directory, and copy Makefile.openwrt to package/ipfw3/Makefile ;
 215
 216       - if necessary, edit package/ipfw3/Makefile and set IPFW_DIR to point to
 217         the directory ipfw3, which contains the sources;
 218
 219       - run "make menuconfig" and select kmod-ipfw3 as a module <M> in
 220             Kernel Modules -> Other modules -> kmod-ipfw3
 221
 222       - run "make" to build the package, "make V=99" for verbose build.
 223
 224       - to modify the code, assuming you are in directory "kamikaze_8.09.1"
 225
 226         (cd ../ipfw3 && vi ...the files you are interested in )
 227         rm -rf build_dir/linux-brcm-2.4/kmod-ipfw3
 228         make package/ipfw3/compile V=99
 229
 230     The resulting package is located in bin/packages/mipsel/kmod-ipfw3*,
 231     upload the file and install on the target system, as follows:
 232
 233     opkg install  kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
 234     ls -l ls -l /lib/modules/2.4.35.4/ipfw*     # check
 235     insmod /lib/modules/2.4.35.4/ipfw_mod.o     # load the module
 236     /lib/modules/2.4.35.4/ipfw show             # launch the userspace tool
 237     rmmod ipfw_mod.o                            # remove the module
 238
 239 ***** PLANETLAB BUILD (within a slice) *****
 240 These instruction can be used by PlanetLab developers to compile
 241 the dummynet module on a node. To install the module on the node
 242 users need root access in root context.  PlanetLab users that want
 243 to use the dummynet package should ask to PlanetLab support for
 244 nodes with dummynet emulation capabilities.
 245
 246     Follow the instructions below. You can just cut&paste
 247
 248         # install the various tools if not available
 249         sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
 250         # new build installation requires the gnupg package
 251         sudo yum -y install gnupg
 252
 253         # create and move to a work directory
 254         mkdir -p test
 255         # extract a planetlab distribution to directory XYZ
 256         (cd test; svn co http://svn.planet-lab.org/svn/build/trunk XYZ)
 257         # copy the planetlab/*mk files here, overriding existing ones
 258         cp planetlab/*mk test/XYZ
 259         # download the specfiles and do some patching.
 260         # Results are into SPEC/ (takes 5 minutes)
 261         (cd test/XYZ; make stage1=true PLDISTRO=planetlab )
 262         # Building the slice code is fast, the root code takes longer
 263         # as it needs to rebuild the whole kernel
 264         (cd test/XYZ; sudo make ipfwslice ipfwroot)
 265
 266     The kernel dependency phase is a bit time consuming, but does not
 267     need to be redone if we are changing the ipfw sources only.
 268     To clean up the code do
 269         (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
 270     then after you have updated the repository again
 271         (cd test/XYZ; sudo make ipfwslice ipfwroot)
 272
 273 --- References
 274 [1] https://svn.planet-lab.org/wiki/VserverCentos
 275 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
 276 [3] http://mirror.centos.org/centos/5/isos/
 277 [4] More information are in /build/README* files