NetfilterQueue

A callback is any one-argument callable invoked with a Packet object.

Key Lifecycle Rules:

1. Payload Persistence: If you need to access the packet payload after the callback function has returned, you must call Packet.retain() within the callback. Otherwise, get_payload() will raise an exception.
2. Queue Management: You can hold onto Packet objects and resolve them later, but they continue to count against the max_len limit of the queue until a verdict (accept(), drop(), or repeat()) is issued.
3. Performance: The kernel stores enqueued packets in a linked list. Keeping a large number of packets outstanding can adversely impact system performance.

When using python-netfilterqueue, be aware of the following technical limitations:

Missing Packet Metadata:

• Network interface names (input/output).
• Checksum offload flags.
• UID/GID and security context data.
• Additional link-layer header data (e.g., VLAN tags).
• Connection-tracking state.
• Original incoming packet length (if truncated during queueing).

Feature Limitations:

• Queue Flags: The library does not expose the interface for changing queue flags (e.g., you cannot configure the queue to accept packets instead of dropping them when the queue is full).
• Buffer Size: Fixed at 4096 bytes unless manually rebuilt via Cython.

Netfilter queue state is isolated per Linux network namespace. To monitor a different namespace from your current process:

1. In the target namespace, run a process that calls socket(AF_NETLINK, SOCK_RAW, 12) (where 12 is NETLINK_NETFILTER).
2. Pass the resulting file descriptor to your monitoring process (e.g., via a Unix domain socket using socket.send_fds()).
3. In your monitoring process, instantiate NetfilterQueue using the special constructor: NetfilterQueue(sockfd=N), where N is the received file descriptor.

Because the socket was created in the target namespace, the kernel treats it as part of that namespace, allowing you to access its traffic.

To send specific network traffic to your Python script, you must configure an iptables rule to divert packets to a Netfilter queue. The --queue-num in your iptables command must match the queue_num provided to NetfilterQueue.bind().

Example: To send packets destined for the 192.168.0.0/24 subnet to queue number 1:

iptables -I INPUT -d 192.168.0.0/24 -j NFQUEUE --queue-num 1

NetfilterQueue is a C extension module that links against libnetfilter_queue.

Prerequisites

Before installing, ensure you have:

1. A C compiler
2. Python development files
3. libnetfilter_queue development files and associated dependencies

On Debian or Ubuntu, install dependencies using:

apt-get install build-essential python3-dev libnetfilter-queue-dev

Installation Methods

From PyPI

pip install NetfilterQueue

From source

pip install cython
git clone https://github.com/oremanj/python-netfilterqueue
cd python-netfilterqueue
pip install .

To intercept network traffic and send it to your Python application, you must use iptables to redirect packets to an NFQUEUE target. You can apply this to any table or chain with any match specification. The critical part is specifying the --queue-num to match the queue ID your Python script is listening on.

Valid queue numbers are integers from 0 to 65,535 inclusive.

# Syntax:
# iptables -I <table or chain> <match specification> -j NFQUEUE --queue-num <queue number>

# Example: Redirect all traffic from the 192.168.0.0/24 subnet in the INPUT chain to queue 1
iptables -I INPUT -d 192.168.0.0/24 -j NFQUEUE --queue-num 1

The library uses a fixed-size 4096-byte buffer for packets. This can cause packet truncation, particularly on loopback interfaces or Ethernet networks using jumbo packets.

Solutions if truncation occurs:

1. Lower the MTU on your loopback interface.
2. Disable jumbo packets on your network.
3. Rebuild with a larger buffer: If you have Cython installed, you can modify DEF BufferSize = 4096 in netfilterqueue.pyx and rebuild the package to increase the buffer size.

You can integrate NetfilterQueue with async event loops by using its file descriptor or by providing your own socket.

Option 1: Using the file descriptor Use nfqueue.get_fd() to get the socket file descriptor. You can poll this FD for readability and call nfqueue.run(block=False) whenever data is available.

Option 2: Using a custom socket (e.g., for gevent) You can create a socket from the file descriptor and pass it to run_socket().

from netfilterqueue import NetfilterQueue
import socket

def print_and_accept(pkt):
    print(pkt)
    pkt.accept()

nfqueue = NetfilterQueue()
nfqueue.bind(1, print_and_accept)
s = socket.fromfd(nfqueue.get_fd(), socket.AF_UNIX, socket.SOCK_STREAM)
try:
    nfqueue.run_socket(s)
except KeyboardInterrupt:
    print('')

s.close()
nfqueue.unbind()

To use NetfilterQueue, create a NetfilterQueue object, bind it to a specific queue number with a callback function, and then call run() to start processing packets.

from netfilterqueue import NetfilterQueue

def print_and_accept(pkt):
    print(pkt)
    pkt.accept()

nfqueue = NetfilterQueue()
nfqueue.bind(1, print_and_accept)
try:
    nfqueue.run()
except KeyboardInterrupt:
    print('')

nfqueue.unbind()

You can inspect the status of the underlying libnetfilter_queue by reading /proc/net/netfilter/nfnetlink_queue. This is useful for debugging packet drops or monitoring queue load.

Field Mapping for /proc/net/netfilter/nfnetlink_queue:

1. Queue ID
2. Bound process ID
3. Number of currently queued packets
4. Copy mode
5. Copy size
6. Number of packets dropped due to reaching max queue size
7. Number of packets dropped due to netlink socket failure
8. Total number of packets sent to queue
9. Internal libnetfilter_queue data

cat /proc/net/netfilter/nfnetlink_queue