LIBIPQ(3)

📦 version 1.8.13, in alpine 3.22, alpine 3.23, alpine 3.24, nixpkgs unstable, opensuse-leap 16.0

💅 libipq(3) — the iptables userspace packet queuing library, but make it make sense

okay so real talk bestie, this is a page from the Linux Programmer's Manual — it's libipq(3), and it's literally the library that lets iptables hand packets to you (userspace) and then take them back. it's giving backstage pass to the kernel. let's get into it 🎀

✨ SYNOPSIS ✨

#include <linux/netfilter.h>
#include <libipq.h>

that's it. two includes and you're in. no cap. 🦋

🌸 DESCRIPTION 🌸

libipq is a development library for iptables userspace packet queuing. periodt.

🧚 Userspace Packet Queuing

so Netfilter (the icon) provides a mechanism for passing packets out of the stack for queueing to userspace, then receiving these packets back into the kernel with a verdict specifying what to do with the packets (such as ACCEPT or DROP). these packets may also be modified in userspace prior to reinjection back into the kernel. obsessed tbh 💖

for each supported protocol, a kernel module called a queue handler may register with Netfilter to perform the mechanics of passing packets to and from userspace.

the standard queue handler for IPv4 is ip_queue. it's provided as an experimental module with 2.4 kernels, and uses a Netlink socket for kernel/userspace communication. (experimental! 2.4-era! we stan a vintage queen 💅)

once ip_queue is loaded, IP packets may be selected with iptables and queued for userspace processing via the QUEUE target. for example, running the following commands:

# modprobe iptable_filter
# modprobe ip_queue
# iptables -A OUTPUT -p icmp -j QUEUE

will cause any locally generated ICMP packets (e.g. ping output) to be sent to the ip_queue module, which will then attempt to deliver the packets to a userspace application. if no userspace application is waiting, the packets will be dropped. 😭 like, literally ghosted at the kernel level.

an application may receive and process these packets via libipq.

🌈 Libipq Overview

libipq provides an API for communicating with ip_queue. the following is an overview of API usage — refer to individual man pages for more details on each function. (yes, each one has its own page. we're thorough here 👑)

⭐ Initialisation

to initialise the library, call ipq_create_handle(3). this will attempt to bind to the Netlink socket used by ip_queue and return an opaque context handle for subsequent library calls.

⭐ Setting the Queue Mode

ipq_set_mode(3) allows the application to specify whether packet metadata, or packet payloads as well as metadata are copied to userspace. it's also used to initially notify ip_queue that an application is ready to receive queue messages. (basically the "hi i'm here and i'm ready" text 💌)

⭐ Receiving Packets from the Queue

ipq_read(3) waits for queue messages to arrive from ip_queue and copies them into a supplied buffer. queue messages may be packet messages or error messages.

the type of packet may be determined with ipq_message_type(3).

if it's a packet message, the metadata and optional payload may be retrieved with ipq_get_packet(3).

to retrieve the value of an error message, use ipq_get_msgerr(3).

⭐ Issuing Verdicts on Packets

to issue a verdict on a packet, and optionally return a modified version of the packet to the kernel, call ipq_set_verdict(3). this is your moment to be the judge, jury, and main character 🫶

⭐ Error Handling

an error string corresponding to the current value of the internal error variable ipq_errno may be obtained with ipq_errstr(3).

for simple applications, calling ipq_perror(3) will print the same message as ipq_errstr(3), as well as the string corresponding to the global errno value (if set) to stderr.

⭐ Cleaning Up

to free up the Netlink socket and destroy resources associated with the context handle, call ipq_destroy_handle(3). be a good guest and clean up after yourself bestie 🧹✨

🎀 SUMMARY 🎀

🔥 EXAMPLE 🔥

the following is an example of a simple application which receives packets and issues NF_ACCEPT verdicts on each packet. it ate, no crumbs 💀✨

/*
 * This code is GPL.
 */
#include <linux/netfilter.h>
#include <libipq.h>
#include <stdio.h>

#define BUFSIZE 2048

static void die(struct ipq_handle *h)
{
     ipq_perror("passer");
     ipq_destroy_handle(h);
     exit(1);
}

int main(int argc, char **argv)
{
     int status;
     unsigned char buf[BUFSIZE];
     struct ipq_handle *h;

     h = ipq_create_handle(0, NFPROTO_IPV4);
     if (!h)
          die(h);

     status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE);
     if (status < 0)
          die(h);

     do{
          status = ipq_read(h, buf, BUFSIZE, 0);
          if (status < 0)
               die(h);

          switch (ipq_message_type(buf)) {
               case NLMSG_ERROR:
                    fprintf(stderr, "Received error message %d\n",
                            ipq_get_msgerr(buf));
                    break;

               case IPQM_PACKET: {
                    ipq_packet_msg_t *m = ipq_get_packet(buf);

                    status = ipq_set_verdict(h, m->packet_id,
                                             NF_ACCEPT, 0, NULL);
                    if (status < 0)
                         die(h);
                    break;
               }

               default:
                    fprintf(stderr, "Unknown message type!\n");
                    break;
          }
     } while (1);

     ipq_destroy_handle(h);
     return 0;
}

pointers to more libipq application examples may be found in The Netfilter FAQ. 🦋

💜 DIAGNOSTICS 💜

for information about monitoring and tuning ip_queue, refer to the Linux 2.4 Packet Filtering HOWTO.

⚠️ okay important one, listen up: if an application modifies a packet, it needs to also update any checksums for the packet. typically, the kernel will silently discard modified packets with invalid checksums. silent. discard. 😭 no error, no warning, just vibes and gone packets. update your checksums fr fr.

🔒 SECURITY 🔒

processes require CAP_NET_ADMIN capability to access the kernel ip_queue module. such processes can potentially access and modify any IP packets received, generated or forwarded by the kernel.

🚨 like, any packets. that's not a small amount of power bestie. treat that capability like the crown jewels 👑

🌸 TODO 🌸

  • per-handle ipq_errno values.

💀 BUGS 💀

Probably.

(that's it. that's the whole section. iconic honestly. the confidence. the brevity. she said "probably" and logged off 😭)

👑 AUTHOR 👑

James Morris <jmorris@intercode.com.au>

Copyright (c) 2000-2001 Netfilter Core Team.

Distributed under the GNU General Public License.

🌟 CREDITS 🌟

  • Joost Remijn implemented the ipq_read timeout feature, which appeared in the 1.2.4 release of iptables.
  • Fernando Anton added support for IPv6.

shoutout to the legends 🫶✨

🦋 SEE ALSO 🦋

iptables(8), ipq_create_handle(3), ipq_destroy_handle(3), ipq_errstr(3), ipq_get_msgerr(3), ipq_get_packet(3), ipq_message_type(3), ipq_perror(3), ipq_read(3), ipq_set_mode(3), ipq_set_verdict(3).

the Netfilter home page at http://netfilter.samba.org/ which has links to The Networking Concepts HOWTO, The Linux 2.4 Packet Filtering HOWTO, The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO, The Netfilter FAQ and many other useful resources.

and that's the whole page babes 💅 this one's from Linux iptables 1.2, dated 16 October 2001 — a genuine Y2K-era icon, still out here explaining packet queues to us. mwah. 💖🌸✨

📦 where this page comes from