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