README

   1 #
   2 # $Id: README 4502 2009-12-15 11:10:33Z marta $
   3 #
   4
   5 This directory contains a port of ipfw and dummynet to Linux and OpenWrt
   6 (including PlanetLab).  A Windows version is in the works but not ready yet.
   7 Building the code produces:
   8
   9         a kernel module,        ipfw_mod.ko
  10         a userland program,     /sbin/ipfw
  11
  12 The source code here comes straight from FreeBSD (roughly the
  13 version in RELENG_7 and HEAD as of December 2009), plus some glue code
  14 and headers written from scratch.
  15 Unless specified otherwise, all the code here is under a BSD license.
  16
  17 Note:
  18        - the linux version miss the "one_pass" feature
  19
  20 =================== BUILD INSTRUCTIONS ==========================
  21
  22 ***** Linux 2.6.x ******
  23
  24         make KERNELPATH=/path/to/linux USRDIR=/path/to/usr
  25
  26     where the two variables are optional an point to the linux kernel
  27     sources and the /usr directory. Defaults are USRDIR=/usr and
  28     KERNELPATH=/lib/modules/`uname -r`/build    --- XXX check ?
  29
  30     NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
  31     configuration file. You can enable it by doing
  32
  33         "(cd ${KERNELPATH}; make menuconfig)"
  34
  35     and enabling the option listed below:
  36
  37         Networking --->
  38             Networking options  --->
  39               [*] Network packet filtering framework (Netfilter)
  40
  41         If you have not yet compiled your kernel source, you need to
  42         prepare the build environment:
  43
  44         (cd $(KERNELPATH); make oldconfig; make prepare; make scripts)
  45
  46 ***** Linux 2.4.x *****
  47
  48     Almost as above, with an additional VER=2.4
  49
  50         make VER=2.4 KERNELPATH=...
  51
  52     For 2.4, if KERNELPATH is not specified then we use
  53         KERNELPATH ?= /usr/src/`uname -r`/build
  54
  55     You need to follow the same instruction for the 2.6 kernel, enabling
  56     netfilter in the kernel options:
  57
  58     Networking options  --->
  59       [*] Network packet filtering (replaces ipchains)
  60
  61 ***** Openwrt package *****
  62
  63     (Tested with kamikaze_8.09.1 and Linux 2.4)
  64
  65     + Download and extract the OpenWrt package, e.g.
  66
  67         wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
  68         tar xvjf kamikaze_8.09.1_source.tar.bz2
  69
  70     + "cd" to the directory with the OpenWrt sources (the one that
  71       contains Config.in, rules.mk ...)
  72
  73         cd kamikaze_8.09.1
  74
  75     + Optional: to be sure that the tools are working, make a first
  76       compilation as follows:
  77
  78         - run "make menuconfig" and set the correct target device,
  79           drivers, and so on;
  80         - run "make" to do the build
  81
  82     + Add ipfw2 to the openwrt package, as follows:
  83
  84       - copy the code from this directory to the place used for the build:
  85
  86                 cp -Rp /path_to_ipfw_mod ../ipfw_mod;
  87
  88         If you want, you can fetch a newer version from the web
  89         (cd ..; rm -rf ipfw_mod;
  90         wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz;\
  91         tar xvzf ipfw_mod-latest.tgz)
  92
  93       - run the following commands:
  94         (mkdir package/ipfw2;
  95         cp ../ipfw_mod/Makefile.openwrt package/ipfw2/Makefile)
  96
  97         to create the package/ipfw2 directory in the OpenWrt source
  98         directory, and copy Makefile.openwrt to package/ipfw2/Makefile:
  99
 100       - if necessary, edit package/ipfw2/Makefile and set IPFW_DIR to point to
 101         the directory ipfw_mod, which contains the ipfw sources
 102
 103       - run "make menuconfig" and select ipfw2 as a module <M> in
 104             Kernel Modules -> Other modules -> kmod-ipfw2
 105
 106       - run "make" to build the package, "make V=99" for verbose build.
 107
 108       - to modify the code, assuming you are in directory "kamikaze_8.09.1"
 109
 110         (cd ../ipfw_mod && vi ...the files you are interested in )
 111         rm -rf build_dir/linux-brcm-2.4/kmod-ipfw2
 112         make package/ipfw2/compile V=99
 113
 114     The resulting package is located in bin/packages/mipsel/kmod-ipfw2*,
 115     upload the file and install on the target system, as follows:
 116
 117     opkg install  kmod-ipfw2_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
 118     ls -l ls -l /lib/modules/2.4.35.4/ipfw*     # check
 119     insmod /lib/modules/2.4.35.4/ipfw_mod.o     # load the module
 120     /lib/modules/2.4.35.4/ipfw show             # launch the userspace tool
 121     rmmod ipfw_mod.o                            # remove the module
 122
 123 ***** PLANETLAB BUILD (within a slice) *****
 124 These instruction can be used by PlanetLab developers to compile the dummynet module
 125 on a node. To install the module on the node users need root access in root context.
 126 PlanetLab users that want to use the dummynet package should ask to PlanetLab support
 127 for nodes with dummynet emulation capabilities.
 128
 129     Follow the instructions below. You can just cut&paste
 130
 131         # install the various tools if not available
 132         sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
 133         # new build installation requires the gnupg package
 134         sudo yum -y install gnupg
 135
 136         # create and move to a work directory
 137         mkdir -p test
 138         # extract a planetlab distribution to directory XYZ
 139         (cd test; svn co http://svn.planet-lab.org/svn/build/trunk XYZ)
 140         # copy the planetlab/*mk files here, overriding existing ones
 141         cp planetlab/*mk test/XYZ
 142         # download the specfiles and do some patching.
 143         # Results are into SPEC/ (takes 5 minutes)
 144         (cd test/XYZ; make stage1=true PLDISTRO=planetlab )
 145         # Building the slice code is fast, the root code takes longer
 146         # as it needs to rebuild the whole kernel
 147         (cd test/XYZ; sudo make ipfwslice ipfwroot)
 148
 149     The kernel dependency phase is a bit time consuming, but does not
 150     need to be redone if we are changing the ipfw sources only.
 151     To clean up the code do
 152         (cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
 153     then after you have updated the repository again
 154         (cd test/XYZ; sudo make ipfwslice ipfwroot)
 155
 156 --- other, instructions (to be verified) ---
 157
 158 To build a kernel module for the PlanetLab distribution you need a build system.
 159 For an up-to-date and detailed information on how to build a local myplc installation,
 160 a local mirror, a PlanetLab test system see[1]
 161
 162 To create a build system you need to do the following steps:
 163
 164  1. install CentOS 5, detailed information[2]
 165
 166  1.A download the image from the main site[3] for example:
 167
 168         wget http://mi.mirror.garr.it/mirrors/CentOS/5.4/isos/i386/CentOS-5.4-i386-netinstall.iso
 169
 170  1.B Add the repository
 171
 172         cat >> /etc/yum.repos.d/dhozac-vserver.repo <<EOF
 173         [dhozac-vserver]
 174 name=Linux-VServer related packages for CentOS $releasever - $basearch
 175 baseurl=http://rpm.hozac.com/dhozac/centos/$releasever/vserver/$basearch
 176 gpgkey=http://rpm.hozac.com/conf/keys/RPM-DHOZAC-GPG-KEY
 177 EOF
 178
 179  1.C Update, install and config the system
 180
 181         yum update yum
 182         yum install kernel
 183         yum install util-vserver{,-core,-lib,-sysv,-build}
 184         yum install vim
 185         yum install subversion
 186         /etc/init.d/vprocunhide start
 187         chkconfig vservers-default on
 188
 189  2. create a vserver
 190
 191  2.A Checkout the planetlab build
 192
 193         cd
 194         svn co http://svn.planet-lab.org/svn/build/trunk svn-build
 195
 196  2.B Search for a working RPM distribution in:
 197
 198         http://build.onelab.eu/onelab/
 199         # good distribution ends in .ok, bad in .ko
 200         # in this example we used the following:
 201         http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/
 202
 203  2.C Creating a vserver
 204
 205         cd ~/svn-build
 206         ./vtest-init-vserver.sh -f f8 -d onelab -p linux32 mybuild \
 207           http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/ \
 208           -- --interface eth0:138.96.255.221 --hostname vnode01.inria.fr &> mybuild.log&
 209
 210  3. create the build
 211
 212  3.A Enter on the vserver, and create the build
 213
 214         vserver mybuild enter
 215         cd \
 216         svn co http://svn.planet-lab.org/svn/build/trunk build
 217
 218  4. build
 219
 220  4.A build[4]
 221         cd /build
 222
 223         # full cleanup
 224         make distclean
 225
 226         # the compilation is composed by several steps,
 227         # make help for more information
 228         # the first for the onelab compilation will download
 229         # the SPEC file from the repository specified in
 230         # onelab-tags.mk
 231         make stage1=true PLDISTRO=onelab
 232
 233         # to download and build a module, for example ipfw:
 234         make ipfw
 235
 236         # to do local changes
 237         cd /build/CODEBASE
 238         rm -rf ipfw
 239         # download the ipfw sources and extract it into ./ipfw
 240         # by svn
 241         svn+ssh://onelab2.iet.unipi.it/home/svn/ports-luigi/dummynet-branches/ipfw_mod ./ipfw
 242         # from web
 243         wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz
 244         tar xvzf ipfw_mod-latest.tgz
 245
 246         # start the compilation
 247         rm -rf SOURCES/ipfw*
 248         rm -rf BUILD/ipfw-0.1/
 249         rm -rf SRPMS/ipfw*
 250         rm -rf RPMS/i386/ipfw*
 251         make ipfw
 252
 253  5. download and install sources into a node
 254
 255  5.A Copy RPMS into the node and install it:
 256         # exit from the root context
 257         exit
 258         scp  /vserver/mybuild/build/RPMS/i386/ipfw-* root@node.iet.unipi.it:
 259         ssh root@node.iet.unipi.it
 260         rpm -e ipfw
 261         rpm -ivh ./ipfw-0-9...TAB
 262         modprobe ipfw_mod
 263
 264         # the ipfw package should be installed
 265         ipfw show
 266
 267 --- References
 268 [1] https://svn.planet-lab.org/wiki/VserverCentos
 269 [2] http://wiki.linux-vserver.org/Installation_on_CentOS
 270 [3] http://mirror.centos.org/centos/5/isos/
 271 [4] More information are in /build/README* files