LIBIPQ(3)

NAME

libipq -- iptables userspace packet queuing library.

SYNOPSIS

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

DESCRIPTION

libipq is a development library for iptables userspace packet queuing.
Userspace Packet Queuing: Netfilter 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.; 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 is provided as an experimental module with 2.4 kernels, and uses a Netlink socket for kernel/userspace communication.; 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; 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.; 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 is also used to initially notify ip_queue that an application is ready to receive queue messages.; 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).; 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).

SUMMARY

ipq_create_handle(3): Initialise library, return context handle.
ipq_set_mode(3): Set the queue mode, to copy either packet metadata, or payloads as well as metadata to userspace.
ipq_read(3): Wait for a queue message to arrive from ip_queue and read it into a buffer.
ipq_message_type(3): Determine message type in the buffer.
ipq_get_packet(3): Retrieve a packet message from the buffer.
ipq_get_msgerr(3): Retrieve an error message from the buffer.
ipq_set_verdict(3): Set a verdict on a packet, optionally replacing its contents.
ipq_errstr(3): Return an error message corresponding to the internal ipq_errno variable.
ipq_perror(3): Helper function to print error messages to stderr.
ipq_destroy_handle(3): Destroy context handle and associated resources.

EXAMPLE

The following is an example of a simple application which receives packets and issues NF_ACCEPT verdicts on each packet.: /*
* 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.

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.

SECURITY

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

TODO

Per-handle ipq_errno values.

BUGS

Probably.

AUTHOR

James Morris <jmorris@intercode.com.au>

COPYRIGHT

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.

docs.sk

comprehensive documentation repository

See also