1 .TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
3 .\" $Id: libipq.3 1056 2001-11-24 15:09:19Z jamesm $
5 .\" Copyright (c) 2000-2001 Netfilter Core Team
7 .\" This program is free software; you can redistribute it and/or modify
8 .\" it under the terms of the GNU General Public License as published by
9 .\" the Free Software Foundation; either version 2 of the License, or
10 .\" (at your option) any later version.
12 .\" This program is distributed in the hope that it will be useful,
13 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
14 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 .\" GNU General Public License for more details.
17 .\" You should have received a copy of the GNU General Public License
18 .\" along with this program; if not, write to the Free Software
19 .\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23 libipq \- iptables userspace packet queuing library.
25 .B #include <linux/netfilter.h>
27 .B #include <libipq.h>
29 libipq is a development library for iptables userspace packet queuing.
30 .SS Userspace Packet Queuing
31 Netfilter provides a mechanism for passing packets out of the stack for
32 queueing to userspace, then receiving these packets back into the kernel
33 with a verdict specifying what to do with the packets (such as ACCEPT
34 or DROP). These packets may also be modified in userspace prior to
35 reinjection back into the kernel.
37 For each supported protocol, a kernel module called a
39 may register with Netfilter to perform the mechanics of passing
40 packets to and from userspace.
42 The standard queue handler for IPv4 is ip_queue. It is provided as an
43 experimental module with 2.4 kernels, and uses a Netlink socket for
44 kernel/userspace communication.
46 Once ip_queue is loaded, IP packets may be selected with iptables
47 and queued for userspace processing via the QUEUE target. For example,
48 running the following commands:
50 # modprobe iptable_filter
54 # iptables -A OUTPUT -p icmp -j QUEUE
56 will cause any locally generated ICMP packets (e.g. ping output) to
57 be sent to the ip_queue module, which will then attempt to deliver the
58 packets to a userspace application. If no userspace application is waiting,
59 the packets will be dropped
61 An application may receive and process these packets via libipq.
65 Libipq provides an API for communicating with ip_queue. The following is
66 an overview of API usage, refer to individual man pages for more details
71 To initialise the library, call
72 .BR ipq_create_handle (3).
73 This will attempt to bind to the Netlink socket used by ip_queue and
74 return an opaque context handle for subsequent library calls.
76 .B Setting the Queue Mode
79 allows the application to specify whether packet metadata, or packet
80 payloads as well as metadata are copied to userspace. It is also used to
81 initially notify ip_queue that an application is ready to receive queue
84 .B Receiving Packets from the Queue
87 waits for queue messages to arrive from ip_queue and copies
88 them into a supplied buffer.
94 The type of packet may be determined with
95 .BR ipq_message_type (3).
97 If it's a packet message, the metadata and optional payload may be retrieved with
98 .BR ipq_get_packet (3).
100 To retrieve the value of an error message, use
101 .BR ipq_get_msgerr (3).
103 .B Issuing Verdicts on Packets
105 To issue a verdict on a packet, and optionally return a modified version
106 of the packet to the kernel, call
107 .BR ipq_set_verdict (3).
111 An error string corresponding to the current value of the internal error
117 For simple applications, calling
119 will print the same message as
121 as well as the string corresponding to the global
123 value (if set) to stderr.
127 To free up the Netlink socket and destroy resources associated with
128 the context handle, call
129 .BR ipq_destroy_handle (3).
132 .BR ipq_create_handle (3)
133 Initialise library, return context handle.
136 Set the queue mode, to copy either packet metadata, or payloads
137 as well as metadata to userspace.
140 Wait for a queue message to arrive from ip_queue and read it into
143 .BR ipq_message_type (3)
144 Determine message type in the buffer.
146 .BR ipq_get_packet (3)
147 Retrieve a packet message from the buffer.
149 .BR ipq_get_msgerr (3)
150 Retrieve an error message from the buffer.
152 .BR ipq_set_verdict (3)
153 Set a verdict on a packet, optionally replacing its contents.
156 Return an error message corresponding to the internal ipq_errno variable.
159 Helper function to print error messages to stderr.
161 .BR ipq_destroy_handle (3)
162 Destroy context handle and associated resources.
164 The following is an example of a simple application which receives
165 packets and issues NF_ACCEPT verdicts on each packet.
171 #include <linux/netfilter.h>
177 static void die(struct ipq_handle *h)
179 ipq_perror("passer");
180 ipq_destroy_handle(h);
184 int main(int argc, char **argv)
187 unsigned char buf[BUFSIZE];
188 struct ipq_handle *h;
190 h = ipq_create_handle(0, PF_INET);
194 status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE);
199 status = ipq_read(h, buf, BUFSIZE, 0);
203 switch (ipq_message_type(buf)) {
205 fprintf(stderr, "Received error message %d\\n",
206 ipq_get_msgerr(buf));
210 ipq_packet_msg_t *m = ipq_get_packet(buf);
212 status = ipq_set_verdict(h, m->packet_id,
220 fprintf(stderr, "Unknown message type!\\n");
225 ipq_destroy_handle(h);
231 Pointers to more libipq application examples may be found in The
234 For information about monitoring and tuning ip_queue, refer to the
235 Linux 2.4 Packet Filtering HOWTO.
237 If an application modifies a packet, it needs to also update any
238 checksums for the packet. Typically, the kernel will silently discard
239 modified packets with invalid checksums.
241 Processes require CAP_NET_ADMIN capabilty to access the kernel ip_queue
242 module. Such processes can potentially access and modify any IP packets
243 received, generated or forwarded by the kernel.
251 James Morris <jmorris@intercode.com.au>
253 Copyright (c) 2000-2001 Netfilter Core Team.
255 Distributed under the GNU General Public License.
257 Joost Remijn implemented the
259 timeout feature, which appeared in the 1.2.4 release of iptables.
261 Fernando Anton added support for IPv6.
264 .BR ipq_create_handle (3),
265 .BR ipq_destroy_handle (3),
267 .BR ipq_get_msgerr (3),
268 .BR ipq_get_packet (3),
269 .BR ipq_message_type (3),
272 .BR ipq_set_mode (3),
273 .BR ipq_set_verdict (3).
275 The Netfilter home page at http://netfilter.samba.org/
276 which has links to The Networking Concepts HOWTO, The Linux 2.4 Packet
277 Filtering HOWTO, The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO,
278 The Netfilter FAQ and many other useful resources.