#
# $Id: README 4502 2009-12-15 11:10:33Z marta $
#

This directory contains a port of ipfw and dummynet to Linux and OpenWrt
(including PlanetLab).  A Windows version is in the works but not ready yet.
Building the code produces:

	a kernel module,	ipfw_mod.ko
	a userland program,	/sbin/ipfw

The source code here comes straight from FreeBSD (roughly the
version in RELENG_7 and HEAD as of December 2009), plus some glue code
and headers written from scratch.
Unless specified otherwise, all the code here is under a BSD license.

Note:
       - the linux version miss the "one_pass" feature

=================== BUILD INSTRUCTIONS ==========================

***** Linux 2.6.x ******

	make KERNELPATH=/path/to/linux USRDIR=/path/to/usr

    where the two variables are optional an point to the linux kernel
    sources and the /usr directory. Defaults are USRDIR=/usr and
    KERNELPATH=/lib/modules/`uname -r`/build 	--- XXX check ?

    NOTE: make sure CONFIG_NETFILTER is enabled in the kernel
    configuration file. You can enable it by doing
    
	"(cd ${KERNELPATH}; make menuconfig)"

    and enabling the option listed below:

        Networking --->
	    Networking options  --->
              [*] Network packet filtering framework (Netfilter)

	If you have not yet compiled your kernel source, you need to
	prepare the build environment:

	(cd $(KERNELPATH); make oldconfig; make prepare; make scripts)

***** Linux 2.4.x *****

    Almost as above, with an additional VER=2.4

	make VER=2.4 KERNELPATH=...

    For 2.4, if KERNELPATH is not specified then we use
    	KERNELPATH ?= /usr/src/`uname -r`/build

    You need to follow the same instruction for the 2.6 kernel, enabling
    netfilter in the kernel options:

    Networking options  --->
      [*] Network packet filtering (replaces ipchains)

***** Openwrt package *****

    (Tested with kamikaze_8.09.1 and Linux 2.4)

    + Download and extract the OpenWrt package, e.g.

	wget http://downloads.openwrt.org/kamikaze/8.09.1/kamikaze_8.09.1_source.tar.bz2
	tar xvjf kamikaze_8.09.1_source.tar.bz2

    + "cd" to the directory with the OpenWrt sources (the one that
      contains Config.in, rules.mk ...)

	cd kamikaze_8.09.1

    + Optional: to be sure that the tools are working, make a first
      compilation as follows:

	- run "make menuconfig" and set the correct target device,
	  drivers, and so on;
	- run "make" to do the build

    + Add ipfw2 to the openwrt package, as follows:

      - copy the code from this directory to the place used for the build:

		cp -Rp /path_to_ipfw_mod ../ipfw_mod; 

	If you want, you can fetch a newer version from the web
	(cd ..; rm -rf ipfw_mod;
	wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz;\
	tar xvzf ipfw_mod-latest.tgz)

      - run the following commands:
	(mkdir package/ipfw2;
	cp ../ipfw_mod/Makefile.openwrt package/ipfw2/Makefile)

	to create the package/ipfw2 directory in the OpenWrt source
	directory, and copy Makefile.openwrt to package/ipfw2/Makefile:

      - if necessary, edit package/ipfw2/Makefile and set IPFW_DIR to point to
	the directory ipfw_mod, which contains the ipfw sources

      - run "make menuconfig" and select ipfw2 as a module <M> in
	    Kernel Modules -> Other modules -> kmod-ipfw2 

      - run "make" to build the package, "make V=99" for verbose build.

      - to modify the code, assuming you are in directory "kamikaze_8.09.1"
	
	(cd ../ipfw_mod && vi ...the files you are interested in )
	rm -rf build_dir/linux-brcm-2.4/kmod-ipfw2
	make package/ipfw2/compile V=99

    The resulting package is located in bin/packages/mipsel/kmod-ipfw2*,
    upload the file and install on the target system, as follows:

    opkg install  kmod-ipfw2_2.4.35.4-brcm-2.4-1_mipsel.ipk #install
    ls -l ls -l /lib/modules/2.4.35.4/ipfw*     # check
    insmod /lib/modules/2.4.35.4/ipfw_mod.o     # load the module
    /lib/modules/2.4.35.4/ipfw show             # launch the userspace tool
    rmmod ipfw_mod.o                            # remove the module

***** PLANETLAB BUILD (within a slice) *****
These instruction can be used by PlanetLab developers to compile the dummynet module
on a node. To install the module on the node users need root access in root context.
PlanetLab users that want to use the dummynet package should ask to PlanetLab support
for nodes with dummynet emulation capabilities.

    Follow the instructions below. You can just cut&paste

	# install the various tools if not available
	sudo yum -y install subversion rpm-build rpm-devel m4 redhat-rpm-config make gcc
	# new build installation requires the gnupg package
	sudo yum -y install gnupg

	# create and move to a work directory
	mkdir -p test
	# extract a planetlab distribution to directory XYZ
	(cd test; svn co http://svn.planet-lab.org/svn/build/trunk XYZ)
	# copy the planetlab/*mk files here, overriding existing ones
	cp planetlab/*mk test/XYZ
	# download the specfiles and do some patching.
	# Results are into SPEC/ (takes 5 minutes)
	(cd test/XYZ; make stage1=true PLDISTRO=planetlab )
	# Building the slice code is fast, the root code takes longer
	# as it needs to rebuild the whole kernel
	(cd test/XYZ; sudo make ipfwslice ipfwroot)

    The kernel dependency phase is a bit time consuming, but does not
    need to be redone if we are changing the ipfw sources only.
    To clean up the code do
	(cd test/XYZ; sudo make ipfwroot-clean ipfwslice-clean)
    then after you have updated the repository again
	(cd test/XYZ; sudo make ipfwslice ipfwroot)

--- other, instructions (to be verified) ---

To build a kernel module for the PlanetLab distribution you need a build system.
For an up-to-date and detailed information on how to build a local myplc installation,
a local mirror, a PlanetLab test system see[1]

To create a build system you need to do the following steps:

 1. install CentOS 5, detailed information[2]

 1.A download the image from the main site[3] for example:

	wget http://mi.mirror.garr.it/mirrors/CentOS/5.4/isos/i386/CentOS-5.4-i386-netinstall.iso

 1.B Add the repository

	cat >> /etc/yum.repos.d/dhozac-vserver.repo <<EOF
	[dhozac-vserver]
name=Linux-VServer related packages for CentOS $releasever - $basearch
baseurl=http://rpm.hozac.com/dhozac/centos/$releasever/vserver/$basearch
gpgkey=http://rpm.hozac.com/conf/keys/RPM-DHOZAC-GPG-KEY
EOF

 1.C Update, install and config the system

	yum update yum
	yum install kernel
	yum install util-vserver{,-core,-lib,-sysv,-build}
	yum install vim
	yum install subversion
	/etc/init.d/vprocunhide start
	chkconfig vservers-default on

 2. create a vserver

 2.A Checkout the planetlab build

	cd
	svn co http://svn.planet-lab.org/svn/build/trunk svn-build

 2.B Search for a working RPM distribution in:

	http://build.onelab.eu/onelab/
	# good distribution ends in .ok, bad in .ko
	# in this example we used the following:
	http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/

 2.C Creating a vserver

	cd ~/svn-build
	./vtest-init-vserver.sh -f f8 -d onelab -p linux32 mybuild \
	  http://build.onelab.eu/onelab/2008.03.02--onelab-f8-linux32/RPMS/ \
	  -- --interface eth0:138.96.255.221 --hostname vnode01.inria.fr &> mybuild.log&

 3. create the build

 3.A Enter on the vserver, and create the build

	vserver mybuild enter
	cd \
	svn co http://svn.planet-lab.org/svn/build/trunk build

 4. build

 4.A build[4]
	cd /build

	# full cleanup
	make distclean

	# the compilation is composed by several steps,
	# make help for more information
	# the first for the onelab compilation will download
	# the SPEC file from the repository specified in
	# onelab-tags.mk
	make stage1=true PLDISTRO=onelab

	# to download and build a module, for example ipfw:
	make ipfw

	# to do local changes
	cd /build/CODEBASE
	rm -rf ipfw
	# download the ipfw sources and extract it into ./ipfw
	# by svn
	svn+ssh://onelab2.iet.unipi.it/home/svn/ports-luigi/dummynet-branches/ipfw_mod ./ipfw
	# from web
        wget http://info.iet.unipi.it/~luigi/dummynet/ipfw_mod-latest.tgz
        tar xvzf ipfw_mod-latest.tgz

	# start the compilation
	rm -rf SOURCES/ipfw*
	rm -rf BUILD/ipfw-0.1/
	rm -rf SRPMS/ipfw*
	rm -rf RPMS/i386/ipfw*
	make ipfw

 5. download and install sources into a node

 5.A Copy RPMS into the node and install it:
	# exit from the root context
	exit
	scp  /vserver/mybuild/build/RPMS/i386/ipfw-* root@node.iet.unipi.it:
	ssh root@node.iet.unipi.it
	rpm -e ipfw
	rpm -ivh ./ipfw-0-9...TAB
	modprobe ipfw_mod

	# the ipfw package should be installed
	ipfw show

--- References
[1] https://svn.planet-lab.org/wiki/VserverCentos
[2] http://wiki.linux-vserver.org/Installation_on_CentOS
[3] http://mirror.centos.org/centos/5/isos/
[4] More information are in /build/README* files