Back to l7-filter main page
Last update 23 Aug 2008
If you have not already, please read the README.
Important links on this page:
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 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 126.96.36.199, 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.
First read the README in the package "Layer 7 patches". Depending on your version of iptables, the instructions are different.
Use the appropriate iptables patch to to patch iptables. Compile iptables, pointing it at your patched kernel source:
chmod +x extensions/.layer7-test" (information about file permissions can't be contained in the patch)
make KERNEL_DIR=/path/to/patched/kernel_source" (you must have configured your kernel source before this step)
make install KERNEL_DIR=/path/to/patched/kernel_source"
Don't use this version. There's no reason to and it's difficult to compile.
(from the subdirectory of the "Layer 7 patches" package that the README
points you to) to the
extensions/ directory of your
iptables source. Then:
./configure --with-ksource=/path/to/patched/kernel_source" (use the full path)
These files tell iptables and the kernel how protocol names
correspond to regular expressions, e.g. "ftp" means
Uncompress the "Protocol Definitions" package and make the resulting
You should now be ready to actually do 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 netfilter.org or at least "man iptables".)
iptables [specify table & chain]
-m layer7 --l7proto [protocol name]
(Or, if you're just interested in accounting, omit "
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
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.
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).
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
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.
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.)
Some protocols open child connections to transfer data. FTP is the
most familiar example. If you have loaded the
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.
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.
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.
/proc/net/layer7_numpackets. (i.e. "
echo 16 > /proc/net/layer7_numpackets".)
modprobe xt_layer7 maxdatalen=N" (
ipt_layer7in old versions), where
Nis in bytes. This should be used cautiously, since performance may decrease drastically with larger data sizes. To prevent you from accidentally bringing down your network, there is an artificial limit of 65536 imposed. If you're sure you know what you're doing, you can remove this limit by editing ipt_layer7.c or xt_layer7.c in the kernel source.
tcgenerates. A useful command is "
tail -f /var/log/messages".
Please see the FAQ for more information.