path: root/libipq/libipq.3
diff options
Diffstat (limited to 'libipq/libipq.3')
1 files changed, 275 insertions, 0 deletions
diff --git a/libipq/libipq.3 b/libipq/libipq.3
new file mode 100644
index 0000000..e7ccc69
--- /dev/null
+++ b/libipq/libipq.3
@@ -0,0 +1,275 @@
+.TH LIBIPQ 3 "18 November 2000" "Linux iptables 1.1.3+" "Linux Programmer's Manual"
+.\" $Id: $
+.\" Copyright (c) 2000 Netfilter Core Team
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" GNU General Public License for more details.
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program; if not, write to the Free Software
+.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+libipq \- iptables userspace packet queuing library.
+.B #include <linux/netfilter.h>
+.B #include <libipq.h>
+libipq is a development library for iptables userspace packet queuing.
+.SS 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
+.I 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.
+.SS 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.
+.B Initialisation
+To initialise the library, call
+.BR 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.
+.B Setting the Queue Mode
+.BR 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
+.B Receiving Packets from the Queue
+.BR ipq_read (3)
+waits for queue messages to arrive from ip_queue and copies
+them into a supplied buffer.
+Queue messages may be
+.I packet messages
+.I error messages.
+The type of packet may be determined with
+.BR ipq_message_type (3).
+If it's a packet message, the metadata and optional payload may be retrieved with
+.BR ipq_get_packet (3).
+To retrieve the value of an error message, use
+.BR ipq_get_msgerr (3).
+.B Issuing Verdicts on Packets
+To issue a verdict on a packet, and optionally return a modified version
+of the packet to the kernel, call
+.BR ipq_set_verdict (3).
+.B Error Handling
+An error string corresponding to the current value of the internal error
+.B ipq_errno
+may be obtained with
+.BR ipq_errstr (3).
+For simple applications, calling
+.BR ipq_perror (3)
+will print the same message as
+.BR ipq_errstr (3),
+as well as the string corresponding to the global
+.B errno
+value (if set) to stderr.
+.B Cleaning Up
+To free up the Netlink socket and destroy resources associated with
+the context handle, call
+.BR ipq_destroy_handle (3).
+.TP 4
+.BR ipq_create_handle (3)
+Initialise library, return context handle.
+.BR ipq_set_mode (3)
+Set the queue mode, to copy either packet metadata, or payloads
+as well as metadata to userspace.
+.BR ipq_read (3)
+Wait for a queue message to arrive from ip_queue and read it into
+a buffer.
+.BR ipq_message_type (3)
+Determine message type in the buffer.
+.BR ipq_get_packet (3)
+Retrieve a packet message from the buffer.
+.BR ipq_get_msgerr (3)
+Retrieve an error message from the buffer.
+.BR ipq_set_verdict (3)
+Set a verdict on a packet, optionally replacing its contents.
+.BR ipq_errstr (3)
+Return an error message corresponding to the internal ipq_errno variable.
+.BR ipq_perror (3)
+Helper function to print error messages to stderr.
+.BR ipq_destroy_handle (3)
+Destroy context handle and associated resources.
+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);
+ 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)) {
+ 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,
+ 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.
+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.
+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.
+Implement a non-blocking interface.
+.B ipq_errno
+James Morris <>
+Copyright (c) 2000 Netfilter Core Team.
+Distributed under the GNU General Public License.
+.BR iptables (8),
+.BR ipq_create_handle (3),
+.BR ipq_destroy_handle (3),
+.BR ipq_errstr (3),
+.BR ipq_get_msgerr (3),
+.BR ipq_get_packet (3),
+.BR ipq_message_type (3),
+.BR ipq_perror (3),
+.BR ipq_read (3),
+.BR ipq_set_mode (3),
+.BR ipq_set_verdict (3).
+The Netfilter home page at
+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.