L7-filter Classifier README

Introduction

L7-filter is a packet classifier for Linux. Unlike most other classifiers, it doesn't just look at simple values such as port numbers. Instead, it does regular expression matching on the application layer data to determine what protocols are being used.

Since this classifier is much more processor and memory intensive than others, we recommend that you only use it if you have reason to believe that matching by port (or IP number, etc.) is insufficient for your purposes. L7-filter is right for you if you need:

• to match any protocol that uses unpredictable ports (e.g. P2P filesharing)
• to match traffic on non-standard ports (e.g. HTTP on port 1111)
• to distinguish between protocols which share a port (e.g. P2P filesharing that uses port 80)

History and Intent

Development of l7-filter began in 2003 in response to the realization that nearly all "packet shaping" applications (methods of controlling the amount of bandwidth used by specified protocols, also known as "bandwidth arbitration" and "quality of service") in use were proprietary, quite expensive and sometimes slow to adapt to changing protocols. We hoped to give open source solutions a fighting chance in this domain.

In May 2003, we released the first version of l7-filter, a patch adding a "filter" (classifier) to the Linux kernel's QoS system. By Oct 2003, we had realized that there was nothing good about trying to work within the QoS framework, so we released a version for Netfilter. This version reached 1.0 in Jan 2005. By Dec 2006, we had realized that working anywhere in kernel space was not the brightest idea, so we released a version that runs in user space and gets its data through Netfilter's QUEUE.

Because l7-filter is implemented using Netfilter, the results of its classification can be used for anything that Netfilter can do with the results of a match. So in addition to packet shaping, l7-filter can be used to drop packets. However, it is not designed with this in mind and for reasons detailed in the HOWTO we consider using it in this way to be a bad idea. Even worse, people occasionally try to use l7-filter to implement fine-grained control over the abilities of users on their networks (by, for instance, restricting what text can be sent in instant messages). This is not at all what l7-filter is intended for. If you are interested in implementing censorship, please do not ask us for help.

L7-filter Capabilities -or- "What L7-filter Is and Is Not"

L7-filter is not a complete packet shaping and/or firewall solution. It only does packet identification (and only one form of identification). Therefore, it is just one component of such a thing, which could include all of these and probably more:

• Packet identification methods:
  • Simple numerical packet identification, such as matching on port, IP number, bytes transfered, and so forth (e.g. standard iptables modules)
  • Regular expression based application layer packet identification (e.g. l7-filter)
  • Function based application layer packet identification (e.g. IPP2P)
• A database of the best way to identify each protocol (e.g. protocolinfo.org)
• Rate limiting of matched packets (e.g. Linux QoS)
• Dropping of matched packets (e.g. Netfilter)
• A front-end (so administrators don't have to understand all of the above!), in the form of a script, text based application, graphical application or web interface (we provide some rudimentary example scripts; see the list of front-ends on our home page for more)

Getting Started

There are currently two versions of l7-filter:

• Kernel version. This version is old and well tested, but it is complicated to install and seems to cause SMP systems to crash. It can only use fairly simple regular expressions. Please see HOWTO-kernel for directions on installing and using this version.
• Userspace version. This version is in the early stages of development, but it is relatively easy to install and cannot crash your system. It can use full grep-style GNU regular expressions. It will probably become the prefered version in the near future, but is not yet mature enough for use in critical systems. Please see HOWTO-userspace for directions on installing and using this version.

In either case, see the protocols page for a list of the protocols that l7-filter currently supports.