libnetfilter_queue is a userspace library providing an API to packets that have been queued by the kernel packet filter. It is is part of a system that deprecates the old ip_queue / libipq mechanism.

libnetfilter_queue homepage is: http://netfilter.org/projects/libnetfilter_queue/

Dependencies

libnetfilter_queue requires libnfnetlink and a kernel that includes the nfnetlink_queue subsystem (i.e. 2.6.14 or later).

Features

receiving queued packets from the kernel nfnetlink_queue subsystem
issuing verdicts and/or reinjecting altered packets to the kernel nfnetlink_queue subsystem

The cinematic is the following: When an iptables rules with target NFQUEUE matches, the kernel en-queued the packet in a chained list. It then format a nfnetlink message and sends the information (packet data , packet id and metadata) via a socket to the software connected to the queue. The software can then read the message.

To remove the packet from the queue, the userspace software must issue a verdict asking kernel to accept or drop the packet. Userspace can also alter the packet. Verdict can be done in asynchronous manner, as the only needed information is the packet id.

When a queue is full, packets that should have been en-queued are dropped by kernel instead of being en-queued.

Tree

The current development version of libnetfilter_queue can be accessed at https://git.netfilter.org/cgi-bin/gitweb.cgi?p=libnetfilter_queue.git;a=summary.

Privileges

You need the CAP_NET_ADMIN capability in order to allow your application to receive from and to send packets to kernel-space.

libnetfilter_queue

To write your own program using libnetfilter_queue, you should start by reading the doxygen documentation (start by LibrarySetup page) and nf-queue.c source file.

Another source of information on libnetfilter_queue usage is the following article: https://home.regit.org/netfilter-en/using-nfqueue-and-libnetfilter_queue/

ENOBUFS errors in recv()

recv() may return -1 and errno is set to ENOBUFS in case that your application is not fast enough to retrieve the packets from the kernel. In that case, you can increase the socket buffer size by means of nfnl_rcvbufsiz(). Although this delays the appearance of ENOBUFS errors, you may hit it again sooner or later. The next section provides some hints on how to obtain the best performance for your application.

Performance

To improve your libnetfilter_queue application in terms of performance, you may consider the following tweaks:

increase the default socket buffer size by means of nfnl_rcvbufsiz().
set nice value of your process to -20 (maximum priority).
set the CPU affinity of your process to a spare core that is not used to handle NIC interruptions.
set NETLINK_NO_ENOBUFS socket option to avoid receiving ENOBUFS errors (requires Linux kernel >= 2.6.30).
see –queue-balance option in NFQUEUE target for multi-threaded apps (it requires Linux kernel >= 2.6.31).
consider using fail-open option see nfq_set_queue_flags() (it requires Linux kernel >= 3.6)
increase queue max length with nfq_set_queue_maxlen() to resist to packets burst