README

   1 #
   2 # $Id: README 8977 2011-07-04 11:47:59Z luigi $
   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 (XPi, Windows7) ******
  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://msdn.microsoft.com/en-us/windows/hardware/gg487463.aspx
  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 (suggest: tortoiseSvn)
  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     Cross compilation of the userland side under FreeBSD is possible with
 105         gmake TCC=`pwd`/tcc-0.9.25-bsd/win32 CC=`pwd`/tcc-0.9.25-bsd/win32/bin/wintcc
 106     (wintcc is a custom version of tcc which produces Windows code)
 107
 108 ***** Windows crosscompilation for 64 bit using DDK ******
 109     Edit root directory's Makefile and set target
 110     operating system
 111     From the root directory, run 'make win64', this will:
 112     - create ipfw-64 and dummynet2-64 subdirs
 113     - patch ipfw makefile to support comunication
 114     with 64bit module and build it
 115     - replace dummynet makefile with proprietary
 116     WinDDK one, named 'sources', and build the module
 117     - create a binary64 directory containing
 118     module and .inf install files, program
 119     binary and relative cygwin dll
 120     - install the driver from this directory in the
 121     usual way.
 122
 123 ***** Linux 2.6.x ******
 124
 125         make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
 126
 127     where the two variables are optional an point to the linux kernel
 128     sources and the /usr directory. Defaults are USRDIR=/usr and
 129     KERNELPATH=/lib/modules/`uname -r`/build    --- XXX check ?
 130
 131     NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
 132     configuration file. You need the ncurses devel library,
 133     that can be installed according your distro with:
 134         apt-get install ncurses-dev     # for debian based distro
 135         yum -y install ncurses-dev      # for fedora based distro
 136     You can enable CONFIG_NETFILTER by doing:
 137
 138         "(cd ${KERNELPATH}; make menuconfig)"
 139
 140     and enabling the option listed below:
 141
 142         Networking --->
 143             Networking options  --->
 144               [*] Network packet filtering framework (Netfilter)
 145
 146     If you have not yet compiled your kernel source, you need to
 147     prepare the build environment:
 148
 149         (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
 150
 151 ***** Linux 2.4.x *****
 152
 153     Almost as above, with an additional VER=2.4
 154
 155         make VER=2.4 KERNELPATH=...
 156
 157     For 2.4, if KERNELPATH is not specified then we use
 158         KERNELPATH ?= /usr/src/`uname -r`/build
 159
 160     You need to follow the same instruction for the 2.6 kernel, enabling
 161     netfilter in the kernel options:
 162
 163     Networking options  --->
 164       [*] Network packet filtering (replaces ipchains)
 165
 166 ***** Openwrt package *****
 167
 168     (Tested with kamikaze_8.09.1 and Linux 2.4)
 169
 170     + Download and extract the OpenWrt package, e.g.
 171
 172         wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
 173         tar xvjf kamikaze_8.09.1_source.tar.bz2
 174
 175     + move to the directory with the OpenWrt sources (the one that
 176       contains Config.in, rules.mk ...)
 177
 178         cd kamikaze_8.09.1
 179
 180     + Optional: Add support for 1ms resolution.
 181
 182         By default OpenWRT kernel is compiled with HZ=100; this implies
 183         that all timeouts are rounded to 10ms, too coarse for dummynet.
 184         The file 020-mips-hz1000.patch contains a kernel patch to build
 185         a kernel with HZ=1000 (i.e. 1ms resolution) as in Linux/FreeBSD.
 186         To apply this patch, go in the kernel source directory and
 187         patch the kernel
 188
 189                 cd build_dir/linux-brcm-2.4/linux-2.4.35.4
 190                 cat $IPFW3_SOURCES/020-mips-hz1000.patch | patch -p0
 191
 192         where IPFW3_SOURCES contains the ipfw3 source code.
 193         Now, the next kernel recompilation will use the right HZ value
 194
 195     + Optional: to be sure that the tools are working, make a first
 196       build as follows:
 197
 198         - run "make menuconfig" and set the correct target device,
 199           drivers, and so on;
 200         - run "make" to do the build
 201
 202     + Add ipfw3 to the openwrt package, as follows:
 203
 204       - copy the code from this directory to the place used for the build:
 205
 206                 cp -Rp /path_to_ipfw3 ../ipfw3;
 207
 208         If you want, you can fetch a newer version from the web
 209         (cd ..; rm -rf ipfw3; \
 210         wget http://info.iet.unipi.it/~luigi/dummynet/ipfw3-latest.tgz;\
 211         tar xvzf ipfw3-latest.tgz)
 212
 213       - run the following commands:
 214         (mkdir package/ipfw3; \
 215         cp ../ipfw3/Makefile.openwrt package/ipfw3/Makefile)
 216
 217         to create the package/ipfw3 directory in the OpenWrt source
 218         directory, and copy Makefile.openwrt to package/ipfw3/Makefile ;
 219
 220       - if necessary, edit package/ipfw3/Makefile and set IPFW_DIR to point to
 221         the directory ipfw3, which contains the sources;
 222
 223       - run "make menuconfig" and select kmod-ipfw3 as a module <M> in
 224             Kernel Modules -> Other modules -> kmod-ipfw3
 225
 226       - run "make" to build the package, "make V=99" for verbose build.
 227
 228       - to modify the code, assuming you are in directory "kamikaze_8.09.1"
 229
 230         (cd ../ipfw3 && vi ...the files you are interested in )
 231         rm -rf build_dir/linux-brcm-2.4/kmod-ipfw3
 232         make package/ipfw3/compile V=99
 233
 234     The resulting package is located in bin/packages/mipsel/kmod-ipfw3*,
 235     upload the file and install on the target system, as follows:
 236
 237     opkg install  kmod-ipfw3_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
 238     ls -l ls -l /lib/modules/2.4.35.4/ipfw*     # check
 239     insmod /lib/modules/2.4.35.4/ipfw_mod.o     # load the module
 240     /lib/modules/2.4.35.4/ipfw show             # launch the userspace tool
 241     rmmod ipfw_mod.o                            # remove the module
 242
 243 ***** PLANETLAB BUILD (within a slice) *****
 244 These instruction can be used by PlanetLab developers to compile
 245 the dummynet module on a node. To install the module on the node
 246 users need root access in root context.  PlanetLab users that want
 247 to use the dummynet package should ask to PlanetLab support for
 248 nodes with dummynet emulation capabilities.
 249
 250     Follow the instructions below. You can just cut&paste
 251
 252         # install the various tools if not available
 253         sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
 254         # new build installation requires the gnupg package
 255         sudo yum -y install gnupg
 256         # the linux kernel and the ipfw source can be fetched by git
 257         sudo yum -y install git
 258
 259         # create and move to a work directory
 260         mkdir -p test
 261         # extract a planetlab distribution to directory XYZ
 262         (cd test; git clone git://git.onelab.eu/build ./XYZ)
 263         # download the specfiles and do some patching.
 264         # Results are into SPEC/ (takes 5 minutes)
 265         (cd test/XYZ; make stage1=true PLDISTRO=onelab)
 266         # Building the slice code is fast, the root code takes longer
 267         # as it needs to rebuild the whole kernel
 268         (cd test/XYZ; sudo make ipfwslice PLDISTRO=onelab)
 269         (cd test/XYZ; sudo make ipfwroot PLDISTRO=onelab)
 270
 271     The kernel dependency phase is a bit time consuming, but does not
 272     need to be redone if we are changing the ipfw sources only.
 273     To clean up the code do
 274         (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
 275     then after you have updated the repository again
 276         (cd test/XYZ; sudo make ipfwslice ipfwroot)
 277
 278 --- References
 279 [1] https://svn.planet-lab.org/wiki/VserverCentos
 280 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
 281 [3] http://mirror.centos.org/centos/5/isos/
 282 [4] More information are in /build/README* files