James Morris | 460c747 | 2001-10-16 14:41:02 +0000 | [diff] [blame] | 1 | .TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual" |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 2 | .\" |
James Morris | ffe96c5 | 2001-11-24 15:09:19 +0000 | [diff] [blame] | 3 | .\" $Id: libipq.3,v 1.4 2001/10/16 16:58:25 jamesm Exp $ |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 4 | .\" |
James Morris | 460c747 | 2001-10-16 14:41:02 +0000 | [diff] [blame] | 5 | .\" Copyright (c) 2000-2001 Netfilter Core Team |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 6 | .\" |
| 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. |
| 11 | .\" |
| 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. |
| 16 | .\" |
| 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. |
| 20 | .\" |
| 21 | .\" |
| 22 | .SH NAME |
| 23 | libipq \- iptables userspace packet queuing library. |
| 24 | .SH SYNOPSIS |
| 25 | .B #include <linux/netfilter.h> |
| 26 | .br |
| 27 | .B #include <libipq.h> |
| 28 | .SH DESCRIPTION |
| 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. |
| 36 | .PP |
| 37 | For each supported protocol, a kernel module called a |
| 38 | .I queue handler |
| 39 | may register with Netfilter to perform the mechanics of passing |
| 40 | packets to and from userspace. |
| 41 | .PP |
| 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. |
| 45 | .PP |
| 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: |
| 49 | .PP |
| 50 | # modprobe iptable_filter |
| 51 | .br |
| 52 | # modprobe ip_queue |
| 53 | .br |
| 54 | # iptables -A OUTPUT -p icmp -j QUEUE |
| 55 | .PP |
| 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 |
| 60 | .PP |
| 61 | An application may receive and process these packets via libipq. |
| 62 | .PP |
| 63 | .PP |
| 64 | .SS Libipq Overview |
| 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 |
| 67 | on each function. |
| 68 | .PP |
| 69 | .B Initialisation |
| 70 | .br |
| 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. |
| 75 | .PP |
| 76 | .B Setting the Queue Mode |
| 77 | .br |
| 78 | .BR ipq_set_mode (3) |
| 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 |
| 82 | messages. |
| 83 | .PP |
| 84 | .B Receiving Packets from the Queue |
| 85 | .br |
| 86 | .BR ipq_read (3) |
| 87 | waits for queue messages to arrive from ip_queue and copies |
| 88 | them into a supplied buffer. |
| 89 | Queue messages may be |
| 90 | .I packet messages |
| 91 | or |
| 92 | .I error messages. |
| 93 | .PP |
| 94 | The type of packet may be determined with |
| 95 | .BR ipq_message_type (3). |
| 96 | .PP |
| 97 | If it's a packet message, the metadata and optional payload may be retrieved with |
| 98 | .BR ipq_get_packet (3). |
| 99 | .PP |
| 100 | To retrieve the value of an error message, use |
| 101 | .BR ipq_get_msgerr (3). |
| 102 | .PP |
| 103 | .B Issuing Verdicts on Packets |
| 104 | .br |
| 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). |
| 108 | .PP |
| 109 | .B Error Handling |
| 110 | .br |
| 111 | An error string corresponding to the current value of the internal error |
| 112 | variable |
| 113 | .B ipq_errno |
| 114 | may be obtained with |
| 115 | .BR ipq_errstr (3). |
| 116 | .PP |
| 117 | For simple applications, calling |
| 118 | .BR ipq_perror (3) |
| 119 | will print the same message as |
| 120 | .BR ipq_errstr (3), |
| 121 | as well as the string corresponding to the global |
| 122 | .B errno |
| 123 | value (if set) to stderr. |
| 124 | .PP |
| 125 | .B Cleaning Up |
| 126 | .br |
| 127 | To free up the Netlink socket and destroy resources associated with |
| 128 | the context handle, call |
| 129 | .BR ipq_destroy_handle (3). |
| 130 | .SH SUMMARY |
| 131 | .TP 4 |
| 132 | .BR ipq_create_handle (3) |
| 133 | Initialise library, return context handle. |
| 134 | .TP |
| 135 | .BR ipq_set_mode (3) |
| 136 | Set the queue mode, to copy either packet metadata, or payloads |
| 137 | as well as metadata to userspace. |
| 138 | .TP |
| 139 | .BR ipq_read (3) |
| 140 | Wait for a queue message to arrive from ip_queue and read it into |
| 141 | a buffer. |
| 142 | .TP |
| 143 | .BR ipq_message_type (3) |
| 144 | Determine message type in the buffer. |
| 145 | .TP |
| 146 | .BR ipq_get_packet (3) |
| 147 | Retrieve a packet message from the buffer. |
| 148 | .TP |
| 149 | .BR ipq_get_msgerr (3) |
| 150 | Retrieve an error message from the buffer. |
| 151 | .TP |
| 152 | .BR ipq_set_verdict (3) |
| 153 | Set a verdict on a packet, optionally replacing its contents. |
| 154 | .TP |
| 155 | .BR ipq_errstr (3) |
| 156 | Return an error message corresponding to the internal ipq_errno variable. |
| 157 | .TP |
| 158 | .BR ipq_perror (3) |
| 159 | Helper function to print error messages to stderr. |
| 160 | .TP |
| 161 | .BR ipq_destroy_handle (3) |
| 162 | Destroy context handle and associated resources. |
| 163 | .SH EXAMPLE |
| 164 | The following is an example of a simple application which receives |
| 165 | packets and issues NF_ACCEPT verdicts on each packet. |
| 166 | .RS |
| 167 | .nf |
| 168 | /* |
| 169 | * This code is GPL. |
| 170 | */ |
| 171 | #include <linux/netfilter.h> |
| 172 | #include <libipq.h> |
| 173 | #include <stdio.h> |
| 174 | |
| 175 | #define BUFSIZE 2048 |
| 176 | |
| 177 | static void die(struct ipq_handle *h) |
| 178 | { |
| 179 | ipq_perror("passer"); |
| 180 | ipq_destroy_handle(h); |
| 181 | exit(1); |
| 182 | } |
| 183 | |
| 184 | int main(int argc, char **argv) |
| 185 | { |
| 186 | int status; |
| 187 | unsigned char buf[BUFSIZE]; |
| 188 | struct ipq_handle *h; |
| 189 | |
James Morris | ffe96c5 | 2001-11-24 15:09:19 +0000 | [diff] [blame] | 190 | h = ipq_create_handle(0, PF_INET); |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 191 | if (!h) |
| 192 | die(h); |
| 193 | |
| 194 | status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE); |
| 195 | if (status < 0) |
| 196 | die(h); |
| 197 | |
| 198 | do{ |
| 199 | status = ipq_read(h, buf, BUFSIZE, 0); |
| 200 | if (status < 0) |
| 201 | die(h); |
| 202 | |
| 203 | switch (ipq_message_type(buf)) { |
| 204 | case NLMSG_ERROR: |
| 205 | fprintf(stderr, "Received error message %d\\n", |
| 206 | ipq_get_msgerr(buf)); |
| 207 | break; |
| 208 | |
| 209 | case IPQM_PACKET: { |
| 210 | ipq_packet_msg_t *m = ipq_get_packet(buf); |
| 211 | |
| 212 | status = ipq_set_verdict(h, m->packet_id, |
| 213 | NF_ACCEPT, 0, NULL); |
| 214 | if (status < 0) |
| 215 | die(h); |
| 216 | break; |
| 217 | } |
| 218 | |
| 219 | default: |
| 220 | fprintf(stderr, "Unknown message type!\\n"); |
| 221 | break; |
| 222 | } |
| 223 | } while (1); |
| 224 | |
| 225 | ipq_destroy_handle(h); |
| 226 | return 0; |
| 227 | } |
| 228 | .RE |
| 229 | .fi |
| 230 | .PP |
| 231 | Pointers to more libipq application examples may be found in The |
| 232 | Netfilter FAQ. |
| 233 | .SH DIAGNOSTICS |
| 234 | For information about monitoring and tuning ip_queue, refer to the |
| 235 | Linux 2.4 Packet Filtering HOWTO. |
| 236 | .PP |
| 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. |
| 240 | .SH SECURITY |
| 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. |
| 244 | .SH TODO |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 245 | Per-handle |
| 246 | .B ipq_errno |
| 247 | values. |
| 248 | .SH BUGS |
| 249 | Probably. |
| 250 | .SH AUTHOR |
| 251 | James Morris <jmorris@intercode.com.au> |
| 252 | .SH COPYRIGHT |
James Morris | 460c747 | 2001-10-16 14:41:02 +0000 | [diff] [blame] | 253 | Copyright (c) 2000-2001 Netfilter Core Team. |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 254 | .PP |
| 255 | Distributed under the GNU General Public License. |
James Morris | 460c747 | 2001-10-16 14:41:02 +0000 | [diff] [blame] | 256 | .SH CREDITS |
James Morris | 67b63ae | 2001-10-16 16:58:25 +0000 | [diff] [blame] | 257 | Joost Remijn implemented the |
James Morris | 460c747 | 2001-10-16 14:41:02 +0000 | [diff] [blame] | 258 | .B ipq_read |
| 259 | timeout feature, which appeared in the 1.2.4 release of iptables. |
James Morris | ffe96c5 | 2001-11-24 15:09:19 +0000 | [diff] [blame] | 260 | .PP |
| 261 | Fernando Anton added support for IPv6. |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 262 | .SH SEE ALSO |
| 263 | .BR iptables (8), |
| 264 | .BR ipq_create_handle (3), |
| 265 | .BR ipq_destroy_handle (3), |
| 266 | .BR ipq_errstr (3), |
| 267 | .BR ipq_get_msgerr (3), |
| 268 | .BR ipq_get_packet (3), |
| 269 | .BR ipq_message_type (3), |
| 270 | .BR ipq_perror (3), |
| 271 | .BR ipq_read (3), |
| 272 | .BR ipq_set_mode (3), |
| 273 | .BR ipq_set_verdict (3). |
| 274 | .PP |
James Morris | 460c747 | 2001-10-16 14:41:02 +0000 | [diff] [blame] | 275 | The Netfilter home page at http://netfilter.samba.org/ |
James Morris | 949810c | 2000-11-20 14:13:31 +0000 | [diff] [blame] | 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. |
| 279 | |