Development of l7-filter has moved to the Clear Foundation. These pages are out of date, but will remain as a historical record.

Back to l7-filter main page

L7-filter Kernel Version HOWTO

Last update 23 Aug 2008

If you have not already, please read the README.

Table of Contents

Important links on this page:

What You Need To Get

Kernel Patch

Short version for experts: Apply our kernel patch. Enable the new match option in Netfilter.

Check our kernel compatibility list to see if the Linux version you want to use has been tested.

Use the appropriate kernel patch from the "Layer 7 patches" package to patch[1] the kernel (read the README in the package to determine which patch to use). Set up your kernel as you would otherwise. Now enable the following options (these are correct for Linux, but they tend to move around a lot, so you may have to go hunting if you have a different kernel version):

Warning: Some users have reported kernel crashes when they using SMP with l7-filter. (Some have also reported that their SMP systems run fine.) If you have a multi-CPU machine, test carefully before putting it into production with l7-filter.

Compile and install the kernel as usual. (Our code may generate warnings about "initialization from incompatible pointer type", ignore them.) Reboot.

1How to patch a source tree

Suppose you have a patch called happy.patch. To apply it, go into the root directory of the source tree you want to patch and run "patch -p1 < happy.patch"

Iptables Setup

First read the README in the package "Layer 7 patches". Depending on your version of iptables, the instructions are different.

iptables 1.4.0 and older

Use the appropriate iptables patch to to patch[1] iptables. Compile iptables, pointing it at your patched kernel source:

iptables 1.4.1

Don't use this version. There's no reason to and it's difficult to compile.

iptables and newer

Copy libxt_layer7.c and (from the subdirectory of the "Layer 7 patches" package that the README points you to) to the extensions/ directory of your iptables source. Then:

Protocol Definitions (Pattern Files)

These files tell iptables and the kernel how protocol names correspond to regular expressions, e.g. "ftp" means "^220[\x09-\x0d -~]*ftp".

Uncompress the "Protocol Definitions" package and make the resulting directory /etc/l7-protocols.[2]

You should now be ready to actually do stuff.

2Notes for non-conformists

You can also install the patterns in a custom location. If you do this, you need to specify --l7dir before --l7proto when you use l7-filter:

iptables [...] -m layer7 --l7dir /home/bob/patterns --l7proto http [...]

Actually doing stuff

There are three things you may be interested in doing: (1) blocking certain protocols (2) controlling bandwidth use (3) accounting. We cover each of these cases below.

First, a reminder: Just because you're using l7-filter, you don't need to do all of your packet classification using it. It's likely that what you want to accomplish can be at least partially done with less demanding classifiers, such as port matching. For instance, you can probably assume that traffic on TCP port 80 that isn't matched by any P2P patterns is HTTP; you don't need to actually use the HTTP pattern.

l7-filter uses the standard iptables extension syntax. (If you are not familiar with this, it's time to read the documentation at or at least "man iptables".)

iptables [specify table & chain] -m layer7 --l7proto [protocol name] -j [action]

(Or, if you're just interested in accounting, omit "-j [action]".)

For a list of valid protocol names, see the protocols page. You can also add your own protocols.

The only trick is that, in order to do its classification, l7-filter must be able to see all of the relevant traffic. It only sees packets if they go through an l7-filter rule. One way of ensuring this is to use the POSTROUTING chain of the mangle table:

iptables -t mangle -A POSTROUTING -m layer7 --l7proto [etc.]

See this packet flow diagram for details. In some cases, l7-filter can sucessfully match even if it can only see one side of the connection, but in general, this won't work.

If you are using a version of l7-filter earlier than 2.7, you must manually load the ip_conntrack module kernel for l7-filter to work. Newer versions do this automatically.

1. Blocking

Don't. Here's why:

Instead of dropping packets you don't like, we recommend using Linux QoS to restrict their bandwidth usage. If you insist on using l7-filter to drop packets, make sure you have investigated other options first, such as the features of your HTTP proxy (useful for worms).

2. Bandwidth Restriction

To control the bandwidth that a protocol uses, you can use Netfilter to "mark" the packets and QoS to filter on that mark. To mark:

iptables -t mangle -A POSTROUTING -m layer7 --l7proto imap -j MARK --set-mark 3

The number "3" is arbitrary. It can be any integer. Then use tc to filter on that mark (tc is "traffic control", the userspace tool for Linux QoS, part of the iproute2 package):

tc filter add dev eth0 protocol ip parent 1:0 prio 1 handle 3 fw flowid 1:3

Did you understand that last command? You can try reading The Linux Advanced Routing and Traffic Control HOWTO for enlightenment. You should do this so that you have some idea what you're doing, but unfortunately, tc is incredibly obtuse and you're likely to wish you just had a canned script. Well, we can help:

These may need to be modified if your setup is significantly different than mine, but it should provide a much better starting point than most other things you are likely to find.

Be prudent when choosing the amount of bandwidth you allow each protocol. Restricting a protocol to an unusably low bandwidth can have similar consequences to blocking it.

3. Accouting

If you just want to keep track of what's in use on your network, simply use the above command without any -j option. For example:

iptables -t mangle -A POSTROUTING -m layer7 --l7proto imap

You can then get statistics by using iptables -L. (See "man iptables" for details.)

More Information

Dealing with FTP, IRC, etc.

Some protocols open child connections to transfer data. FTP is the most familiar example. If you have loaded the ip_conntrack_ftp or nf_conntrack_ftp kernel module, l7-filter will classify FTP and all its child connections as FTP. The same goes for IRC/IRC-DCC, etc.

If you wish to classify the children differently, use the standard iptables "helper" match. You can use "-m --helper ftp" to match ftp child connections. Of course, once you've done this, it's silly to involve l7-filter, at least for the children.

The "unset" and "unknown" matches

l7-filter marks unmatched connections that it is still trying to match as "unset". The first few packets of all TCP connections as well as those of some UDP connections will match this. Similarly, l7-filter marks connections that it has given up trying to match as "unknown". These are matched just like normal protocols:

iptables -A FORWARD -m layer7 --l7proto unset
iptables -A FORWARD -m layer7 --l7proto unknown

The "unset" match is only supported by l7-filter 2.9 and up.

Upgrading the protocol definitions

The protocol definitions are simple text files with a format described in the Pattern-HOWTO. They can be updated as a package or individually.

If you update the protocol definitions, you need to clear the relevant iptables rules and re-enter them. This is because the pattern files are only read by iptables, not directly by the kernel.

Other things to know

Please see the FAQ for more information.