How to Configure, Install and Use libnefilter_queue on Linux

According to libnetfilter_queue home page, libnetfilter_queue is a userspace library that allows one to retrieve and manipulate the packets that have been queued by kernel packet filter. It is supposed to replace the old ip_queue/libipq mechanism.
0. Dependencies
libnetfilter_queue requires a kernel that includes nfnetlink_queue subsystem. If you Linux kernel is 2.6.14 or later, the subsystem is normally enabled.

You can confirm this by looking into your kernel configuration file. The configuration file is normally located at your system /boot/ directory, with the name like config-. Open the file, and look for CONFIG_NETFILTER_NETLINK_QUEUE and CONFIG_NETFILTER_ADVANCED.  Make sure the two lines are not commented out.

In addition, libnetfilter_queue library depends on libnfnetlink. A lower-level library for netfitler related kernel/userspace communication. And since this library depends on nfnetlink kernel subsystem, you’ll need to ensure CONFIG_NETFITLER_NETLINK is not commented out in your kernel configuration file.

In summary, you’ll need to check CONFIG_NETFILTER_ADVANCED, CONFIG_NETFITLER_NETLINK and CONFIG_NETFILTER_NETLINK_QUEUE in you kernel configuration file, and install libnfnetlink and libnetfilter_queue user space libraries.

2. InstallationThis is simple. First, you need to install libnfnetlink library. Download the tar file here.
Then go the directory where the file is downloaded, follow the commands below,

tar -xvf libnfnetlink-1.0.0.tar.bz2
cd libnfnetlink-1.0.0/
./configure
make
sudo make install

Next, you need to install libnetfilter_queue library. Download the tar file here.  Then follow the same procedure above. Build and install the library.

After installation, issue sudo ldconfig command to create necessary links and cache to the newly installed libraries.
3. Understand the Sample CodeThere’re not many tutorials and examples around, but libnetfilter_queue has provided a simple example and some documentation. You can find the sample code at the utiles/ nfqnl_test.c of the libnetfilter_queue folder you downloaded.

The basic idea of the code is to set up libnetfiter_queue library, and bind the program to a queue. You can refer to documentation here and here to help you understand the code.
To compile the sample code, use the command below,

gcc -Wall -o test nfqnl_test.c -lnfnetlink -lnetfilter_queue

To run the code, use the command below,

sudo ./test

Note that you’ll need to set up a queue in kernel packet filter table in order to see how the program working. Suppose we want to queue all TCP packets sending out from our local machine, you’ll need to enter the command below,

sudo iptables -A OUTPUT -p tcp -j NFQUEUE –queue-num 0

Now you can see the test program is outputing some information about the packet,

…..
hw_protocol=0×0000 hook=3 id=422 outdev=2 payload_len=52
entering callback
pkt received
hw_protocol=0×0000 hook=3 id=423 outdev=2 payload_len=52
entering callback

To stopping running the program, kill test and then issue the command

iptables –flush

4. Additional Notes
libnetfilter_queue can be quite powerful combined with iptables rules. It doesn’t only allow you to receive the packet, but also provide the ability to modify the packet and inject the modified packet back to kernel. With these APIs, you can implement user space NATing, packet sniffing/capturing programs etc.

References:1. libnetfilter_queue home page: http://www.netfilter.org/projects/libnetfilter_queue/