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¶
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.
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.