original/man3/libipq.3

   1 .TH LIBIPQ 3 "16 October 2001" "Linux iptables 1.2" "Linux Programmer's Manual"
   2 .\"
   3 .\"     Copyright (c) 2000-2001 Netfilter Core Team
   4 .\"
   5 .\"     This program is free software; you can redistribute it and/or modify
   6 .\"     it under the terms of the GNU General Public License as published by
   7 .\"     the Free Software Foundation; either version 2 of the License, or
   8 .\"     (at your option) any later version.
   9 .\"
  10 .\"     This program is distributed in the hope that it will be useful,
  11 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 .\"     GNU General Public License for more details.
  14 .\"
  15 .\"     You should have received a copy of the GNU General Public License
  16 .\"     along with this program; if not, write to the Free Software
  17 .\"     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18 .\"
  19 .\"
  20 .SH NAME
  21 libipq \(em iptables userspace packet queuing library.
  22 .SH SYNOPSIS
  23 .B #include <linux/netfilter.h>
  24 .br
  25 .B #include <libipq.h>
  26 .SH DESCRIPTION
  27 libipq is a development library for iptables userspace packet queuing.
  28 .SS Userspace Packet Queuing
  29 Netfilter provides a mechanism for passing packets out of the stack for
  30 queueing to userspace, then receiving these packets back into the kernel
  31 with a verdict specifying what to do with the packets (such as ACCEPT
  32 or DROP).  These packets may also be modified in userspace prior to
  33 reinjection back into the kernel.
  34 .PP
  35 For each supported protocol, a kernel module called a
  36 .I queue handler
  37 may register with Netfilter to perform the mechanics of passing
  38 packets to and from userspace.
  39 .PP
  40 The standard queue handler for IPv4 is ip_queue.  It is provided as an
  41 experimental module with 2.4 kernels, and uses a Netlink socket for
  42 kernel/userspace communication.
  43 .PP
  44 Once ip_queue is loaded, IP packets may be selected with iptables
  45 and queued for userspace processing via the QUEUE target.  For example,
  46 running the following commands:
  47 .PP
  48         # modprobe iptable_filter
  49 .br
  50         # modprobe ip_queue
  51 .br
  52         # iptables \-A OUTPUT \-p icmp \-j QUEUE
  53 .PP
  54 will cause any locally generated ICMP packets (e.g. ping output) to
  55 be sent to the ip_queue module, which will then attempt to deliver the
  56 packets to a userspace application.  If no userspace application is waiting,
  57 the packets will be dropped
  58 .PP
  59 An application may receive and process these packets via libipq.
  60 .PP
  61 .PP
  62 .SS Libipq Overview
  63 Libipq provides an API for communicating with ip_queue.  The following is
  64 an overview of API usage, refer to individual man pages for more details
  65 on each function.
  66 .PP
  67 .B Initialisation
  68 .br
  69 To initialise the library, call
  70 .BR ipq_create_handle (3).
  71 This will attempt to bind to the Netlink socket used by ip_queue and
  72 return an opaque context handle for subsequent library calls.
  73 .PP
  74 .B Setting the Queue Mode
  75 .br
  76 .BR ipq_set_mode (3)
  77 allows the application to specify whether packet metadata, or packet
  78 payloads as well as metadata are copied to userspace.  It is also used to
  79 initially notify ip_queue that an application is ready to receive queue
  80 messages.
  81 .PP
  82 .B Receiving Packets from the Queue
  83 .br
  84 .BR ipq_read (3)
  85 waits for queue messages to arrive from ip_queue and copies
  86 them into a supplied buffer.
  87 Queue messages may be
  88 .I packet messages
  89 or
  90 .I error messages.
  91 .PP
  92 The type of packet may be determined with
  93 .BR ipq_message_type (3).
  94 .PP
  95 If it's a packet message, the metadata and optional payload may be retrieved with
  96 .BR ipq_get_packet (3).
  97 .PP
  98 To retrieve the value of an error message, use
  99 .BR ipq_get_msgerr (3).
 100 .PP
 101 .B Issuing Verdicts on Packets
 102 .br
 103 To issue a verdict on a packet, and optionally return a modified version
 104 of the packet to the kernel, call
 105 .BR ipq_set_verdict (3).
 106 .PP
 107 .B Error Handling
 108 .br
 109 An error string corresponding to the current value of the internal error
 110 variable
 111 .B ipq_errno
 112 may be obtained with
 113 .BR ipq_errstr (3).
 114 .PP
 115 For simple applications, calling
 116 .BR ipq_perror (3)
 117 will print the same message as
 118 .BR ipq_errstr (3),
 119 as well as the string corresponding to the global
 120 .B errno
 121 value (if set) to stderr.
 122 .PP
 123 .B Cleaning Up
 124 .br
 125 To free up the Netlink socket and destroy resources associated with
 126 the context handle, call
 127 .BR ipq_destroy_handle (3).
 128 .SH SUMMARY
 129 .TP 4
 130 .BR ipq_create_handle (3)
 131 Initialise library, return context handle.
 132 .TP
 133 .BR ipq_set_mode (3)
 134 Set the queue mode, to copy either packet metadata, or payloads
 135 as well as metadata to userspace.
 136 .TP
 137 .BR ipq_read (3)
 138 Wait for a queue message to arrive from ip_queue and read it into
 139 a buffer.
 140 .TP
 141 .BR ipq_message_type (3)
 142 Determine message type in the buffer.
 143 .TP
 144 .BR ipq_get_packet (3)
 145 Retrieve a packet message from the buffer.
 146 .TP
 147 .BR ipq_get_msgerr (3)
 148 Retrieve an error message from the buffer.
 149 .TP
 150 .BR ipq_set_verdict (3)
 151 Set a verdict on a packet, optionally replacing its contents.
 152 .TP
 153 .BR ipq_errstr (3)
 154 Return an error message corresponding to the internal ipq_errno variable.
 155 .TP
 156 .BR ipq_perror (3)
 157 Helper function to print error messages to stderr.
 158 .TP
 159 .BR ipq_destroy_handle (3)
 160 Destroy context handle and associated resources.
 161 .SH EXAMPLE
 162 The following is an example of a simple application which receives
 163 packets and issues NF_ACCEPT verdicts on each packet.
 164 .RS
 165 .nf
 166 /*
 167  * This code is GPL.
 168  */
 169 #include <linux/netfilter.h>
 170 #include <libipq.h>
 171 #include <stdio.h>
 172
 173 #define BUFSIZE 2048
 174
 175 static void die(struct ipq_handle *h)
 176 {
 177         ipq_perror("passer");
 178         ipq_destroy_handle(h);
 179         exit(1);
 180 }
 181
 182 int main(int argc, char **argv)
 183 {
 184         int status;
 185         unsigned char buf[BUFSIZE];
 186         struct ipq_handle *h;
 187
 188         h = ipq_create_handle(0, NFPROTO_IPV4);
 189         if (!h)
 190                 die(h);
 191
 192         status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE);
 193         if (status < 0)
 194                 die(h);
 195
 196         do{
 197                 status = ipq_read(h, buf, BUFSIZE, 0);
 198                 if (status < 0)
 199                         die(h);
 200
 201                 switch (ipq_message_type(buf)) {
 202                         case NLMSG_ERROR:
 203                                 fprintf(stderr, "Received error message %d\\n",
 204                                         ipq_get_msgerr(buf));
 205                                 break;
 206
 207                         case IPQM_PACKET: {
 208                                 ipq_packet_msg_t *m = ipq_get_packet(buf);
 209
 210                                 status = ipq_set_verdict(h, m->packet_id,
 211                                                          NF_ACCEPT, 0, NULL);
 212                                 if (status < 0)
 213                                         die(h);
 214                                 break;
 215                         }
 216
 217                         default:
 218                                 fprintf(stderr, "Unknown message type!\\n");
 219                                 break;
 220                 }
 221         } while (1);
 222
 223         ipq_destroy_handle(h);
 224         return 0;
 225 }
 226 .RE
 227 .fi
 228 .PP
 229 Pointers to more libipq application examples may be found in The
 230 Netfilter FAQ.
 231 .SH DIAGNOSTICS
 232 For information about monitoring and tuning ip_queue, refer to the
 233 Linux 2.4 Packet Filtering HOWTO.
 234 .PP
 235 If an application modifies a packet, it needs to also update any
 236 checksums for the packet.  Typically, the kernel will silently discard
 237 modified packets with invalid checksums.
 238 .SH SECURITY
 239 Processes require CAP_NET_ADMIN capabilty to access the kernel ip_queue
 240 module.  Such processes can potentially access and modify any IP packets
 241 received, generated or forwarded by the kernel.
 242 .SH TODO
 243 Per-handle
 244 .B ipq_errno
 245 values.
 246 .SH BUGS
 247 Probably.
 248 .SH AUTHOR
 249 James Morris <jmorris@intercode.com.au>
 250 .SH COPYRIGHT
 251 Copyright (c) 2000-2001 Netfilter Core Team.
 252 .PP
 253 Distributed under the GNU General Public License.
 254 .SH CREDITS
 255 Joost Remijn implemented the
 256 .B ipq_read
 257 timeout feature, which appeared in the 1.2.4 release of iptables.
 258 .PP
 259 Fernando Anton added support for IPv6.
 260 .SH SEE ALSO
 261 .BR iptables (8),
 262 .BR ipq_create_handle (3),
 263 .BR ipq_destroy_handle (3),
 264 .BR ipq_errstr (3),
 265 .BR ipq_get_msgerr (3),
 266 .BR ipq_get_packet (3),
 267 .BR ipq_message_type (3),
 268 .BR ipq_perror (3),
 269 .BR ipq_read (3),
 270 .BR ipq_set_mode (3),
 271 .BR ipq_set_verdict (3).
 272 .PP
 273 The Netfilter home page at http://netfilter.samba.org/
 274 which has links to The Networking Concepts HOWTO, The Linux 2.4 Packet
 275 Filtering HOWTO, The Linux 2.4 NAT HOWTO, The Netfilter Hacking HOWTO,
 276 The Netfilter FAQ and many other useful resources.
 277