libipq/libipq.3

   1 .TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .\"
   3 .\" $Id: libipq.3,v 1.4 2001/10/16 16:58:25 jamesm Exp $
   4 .\"
   5 .\"     Copyright (c) 2000-2001 Netfilter Core Team
   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
 190         h = ipq_create_handle(0, PF_INET);
 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
 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
 253 Copyright (c) 2000-2001 Netfilter Core Team.
 254 .PP
 255 Distributed under the GNU General Public License.
 256 .SH CREDITS
 257 Joost Remijn implemented the
 258 .B ipq_read
 259 timeout feature, which appeared in the 1.2.4 release of iptables.
 260 .PP
 261 Fernando Anton added support for IPv6.
 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
 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.
 279