/iptables-module/README.compile

= Howto Compile =

This is a quick howto, on getting the iptables module compiled.
Including howto install an newer/compatible iptables version.

I'm using GNU tool 'stow' to handle my out-of-distro installed
software.  To follow these compile instructions, you should have stow
installed on your machine.


== Iptables dependency ==

This iptables module requires minimum iptables 1.4.3.


== Developement tree ==

Get the development git development tree here:
(FIXME: Move this to the new domain iptv-analyzer.org)

 git clone git://people.netfilter.org/hawk/iptv-analyzer.git


=== Compiling the userspace iptables module ===

The default make command tries to compile both the iptables userspace
library and kernel module.  If you only want to compile the iptables
userspace library call:

  make lib

Every iptables extension/module is based upon a dynamically loadable
library file (suffix .so).  These libraries/modules are installed in
e.g. /usr/local/libexec/xtables/ and are loaded by iptables when
needed.

Thus, the makefile trick is "simply" to create an iptables dynamically
loadable library "out-of-tree".

All the details can be found in the excellent document titled:
"Writing Netfilter modules" by Jan Engelhardt:

  http://jengelh.medozas.de/documents/Netfilter_Modules.pdf


=== Trick: Fake stow install ===

TODO: Currently the Makefile does not contain an install target for
the userspace iptables library.  Below is the manual procedure.

Make a fake stow software package for the development version of the
source.

Create directory:

  mkdir /usr/local/stow/mpeg2ts_development_fake/

And create the directories libexec/xtables/ within.

  mkdir -p /usr/local/stow/mpeg2ts_development_fake/libexec/xtables/
  cd       /usr/local/stow/mpeg2ts_development_fake/libexec/xtables/

Create a symlink from this directory to your development edition of
the file 'libxt_mpeg2ts.so'

  ln -s ~/git/iptv-analyzer/iptables-module/libxt_mpeg2ts.so .

Activate the stow software package 'mpeg2ts_development_fake'.

  cd /usr/local/stow
  stow mpeg2ts_development_fake


== Compiling the kernel module ==

No patching of the Linux kernel is required, but the kernel source is
required.  The module takes advantage of the kernel build/make system.

Minimum kernel version required is 2.6.28 (due to some RCU changes).

If you only want to compile the kernel module call:

  make modules

The Makefile tries to detect the kernel source via the symlink in:

  /lib/modules/2.6.xx/build

The kernel version is extracted by calling 'uname -r' in the makefile.

But its also possibly to compile against another kernel than the
current running version, by calling:

  make KERNEL_DIR=~/git/kernel/davem/net-next-2.6/

If you have a fresh kernel source you might need to call:

  make oldconfig
  make prepare
  make modules_prepare

TODO/Issue?: Is it possible to link against a fresh source? As the
module needs to know the C "extern" adresses.

=== Loading the kernel module manually ===

Its possibly to load the kernel module via insmod, without installing
the module into /lib/modules/2.6.xx/ (see below howto perform the
install).

* But be warned that the systems does not automatically load
  dependencies.

First of all you need to make sure that the iptables module have been
loaded (e.g x_tables, ip_tables, iptable_mangle, iptable_filter etc.).
The easiest way to get these modules loaded is simple to invoke the
'iptables -L' command line tool.

The kernel module compile, actually produced two kernel modules:

* xt_mpeg2ts.ko
* compat_xtables.ko

If you kernel version <= 2.6.34, then you also need to load the kernel
module "compat_xtables.ko"

  insmod ./compat_xtables.ko

Next, you need to load the real kernel module:

  insmod ./xt_mpeg2ts.ko

If the loading failed with (e.g. "Unknown symbol in module") use
'dmesg' to see the real error message.


=== Reloading kernel module ===

When making modifications to the kernel module remember to manually
rmmod and insmod the kernel module again.

  rmmod xt_mpeg2ts
  insmod ./xt_mpeg2ts.ko


=== Installing the kernel module ===

When the kernel module has been compiled successfully, its possibly to
install the kernel module, as root, via:

  make modules_install

This will install the kernel module into /lib/modules/2.6.xx/extra/
(via a call to the kernel build system, this might call depmod for
you).

After the install you should call (as root):

  depmod -a

If its another kernel than the running kernel you need to add the
kernel-version as an argument to depmod

A small test to see if the kernel module got installed and depmod
correctly call:

 modinfo -k $KERNEL_VER xt_mpeg2ts