libipq(3)

1LIBIPQ(3)                  Linux Programmer's Manual                 LIBIPQ(3)
2
3
4

NAME

6       libipq - iptables userspace packet queuing library.
7

SYNOPSIS

9       #include <linux/netfilter.h>
10       #include <libipq.h>
11

DESCRIPTION

13       libipq is a development library for iptables userspace packet queuing.
14
15   Userspace Packet Queuing
16       Netfilter provides a mechanism for passing packets out of the stack for
17       queueing to userspace, then receiving these packets back into the  ker‐
18       nel  with  a  verdict  specifying  what to do with the packets (such as
19       ACCEPT or DROP).  These packets may also be modified in userspace prior
20       to reinjection back into the kernel.
21
22       For each supported protocol, a kernel module called a queue handler may
23       register with Netfilter to perform the mechanics of passing packets  to
24       and from userspace.
25
26       The  standard queue handler for IPv4 is ip_queue.  It is provided as an
27       experimental module with 2.4 kernels, and uses  a  Netlink  socket  for
28       kernel/userspace communication.
29
30       Once  ip_queue  is loaded, IP packets may be selected with iptables and
31       queued for userspace processing via the  QUEUE  target.   For  example,
32       running the following commands:
33
34            # modprobe iptable_filter
35            # modprobe ip_queue
36            # iptables -A OUTPUT -p icmp -j QUEUE
37
38       will  cause any locally generated ICMP packets (e.g. ping output) to be
39       sent to the ip_queue module, which will then  attempt  to  deliver  the
40       packets  to  a  userspace  application.  If no userspace application is
41       waiting, the packets will be dropped
42
43       An application may receive and process these packets via libipq.
44
45   Libipq Overview
46       Libipq provides an API for communicating with ip_queue.  The  following
47       is  an  overview  of  API usage, refer to individual man pages for more
48       details on each function.
49
50       Initialisation
51       To  initialise  the  library,  call  ipq_create_handle(3).   This  will
52       attempt  to  bind  to the Netlink socket used by ip_queue and return an
53       opaque context handle for subsequent library calls.
54
55       Setting the Queue Mode
56       ipq_set_mode(3) allows the application to specify whether packet  meta‐
57       data,  or  packet payloads as well as metadata are copied to userspace.
58       It is also used to initially notify ip_queue  that  an  application  is
59       ready to receive queue messages.
60
61       Receiving Packets from the Queue
62       ipq_read(3) waits for queue messages to arrive from ip_queue and copies
63       them into a supplied buffer.  Queue messages may be packet messages  or
64       error messages.
65
66       The type of packet may be determined with ipq_message_type(3).
67
68       If  it's  a  packet  message,  the metadata and optional payload may be
69       retrieved with ipq_get_packet(3).
70
71       To retrieve the value of an error message, use ipq_get_msgerr(3).
72
73       Issuing Verdicts on Packets
74       To issue a verdict on a packet, and optionally return a  modified  ver‐
75       sion of the packet to the kernel, call ipq_set_verdict(3).
76
77       Error Handling
78       An  error  string  corresponding  to  the current value of the internal
79       error variable ipq_errno may be obtained with ipq_errstr(3).
80
81       For simple applications, calling ipq_perror(3) will print the same mes‐
82       sage  as  ipq_errstr(3),  as  well  as  the string corresponding to the
83       global errno value (if set) to stderr.
84
85       Cleaning Up
86       To free up the Netlink socket and destroy resources associated with the
87       context handle, call ipq_destroy_handle(3).
88

SUMMARY

90       ipq_create_handle(3)
91           Initialise library, return context handle.
92
93       ipq_set_mode(3)
94           Set  the queue mode, to copy either packet metadata, or payloads as
95           well as metadata to userspace.
96
97       ipq_read(3)
98           Wait for a queue message to arrive from ip_queue and read it into a
99           buffer.
100
101       ipq_message_type(3)
102           Determine message type in the buffer.
103
104       ipq_get_packet(3)
105           Retrieve a packet message from the buffer.
106
107       ipq_get_msgerr(3)
108           Retrieve an error message from the buffer.
109
110       ipq_set_verdict(3)
111           Set a verdict on a packet, optionally replacing its contents.
112
113       ipq_errstr(3)
114           Return  an  error  message  corresponding to the internal ipq_errno
115           variable.
116
117       ipq_perror(3)
118           Helper function to print error messages to stderr.
119
120       ipq_destroy_handle(3)
121           Destroy context handle and associated resources.
122

EXAMPLE

124       The following is an example of  a  simple  application  which  receives
125       packets and issues NF_ACCEPT verdicts on each packet.
126              /*
127               * This code is GPL.
128               */
129              #include <linux/netfilter.h>
130              #include <libipq.h>
131              #include <stdio.h>
132
133              #define BUFSIZE 2048
134
135              static void die(struct ipq_handle *h)
136              {
137                   ipq_perror("passer");
138                   ipq_destroy_handle(h);
139                   exit(1);
140              }
141
142              int main(int argc, char **argv)
143              {
144                   int status;
145                   unsigned char buf[BUFSIZE];
146                   struct ipq_handle *h;
147
148                   h = ipq_create_handle(0, PF_INET);
149                   if (!h)
150                        die(h);
151
152                   status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE);
153                   if (status < 0)
154                        die(h);
155
156                   do{
157                        status = ipq_read(h, buf, BUFSIZE, 0);
158                        if (status < 0)
159                             die(h);
160
161                        switch (ipq_message_type(buf)) {
162                             case NLMSG_ERROR:
163                                  fprintf(stderr, "Received error message %d\n",
164                                          ipq_get_msgerr(buf));
165                                  break;
166
167                             case IPQM_PACKET: {
168                                  ipq_packet_msg_t *m = ipq_get_packet(buf);
169
170                                  status = ipq_set_verdict(h, m->packet_id,
171                                                           NF_ACCEPT, 0, NULL);
172                                  if (status < 0)
173                                       die(h);
174                                  break;
175                             }
176
177                             default:
178                                  fprintf(stderr, "Unknown message type!\n");
179                                  break;
180                        }
181                   } while (1);
182
183                   ipq_destroy_handle(h);
184                   return 0;
185              }
186
187       Pointers  to  more libipq application examples may be found in The Net‐
188       filter FAQ.
189

DIAGNOSTICS

191       For information about monitoring and  tuning  ip_queue,  refer  to  the
192       Linux 2.4 Packet Filtering HOWTO.
193
194       If an application modifies a packet, it needs to also update any check‐
195       sums for the packet.  Typically, the kernel will silently discard modi‐
196       fied packets with invalid checksums.
197

SECURITY

199       Processes require CAP_NET_ADMIN capabilty to access the kernel ip_queue
200       module.  Such processes can potentially access and modify any IP  pack‐
201       ets received, generated or forwarded by the kernel.
202

TODO

204       Per-handle ipq_errno values.
205

BUGS

207       Probably.
208

AUTHOR

210       James Morris <jmorris@intercode.com.au>
211

COPYRIGHT

213       Copyright (c) 2000-2001 Netfilter Core Team.
214
215       Distributed under the GNU General Public License.
216

CREDITS

218       Joost  Remijn  implemented the ipq_read timeout feature, which appeared
219       in the 1.2.4 release of iptables.
220
221       Fernando Anton added support for IPv6.
222