Provided by: iptables-dev_1.4.12-1ubuntu4_amd64 bug

NAME

       libipq — iptables userspace packet queuing library.

SYNOPSIS

       #include <linux/netfilter.h>
       #include <libipq.h>

DESCRIPTION

       libipq is a development library for iptables userspace packet queuing.

   Userspace Packet Queuing
       Netfilter  provides  a  mechanism  for  passing  packets  out of the stack for queueing to
       userspace, then receiving these packets back into the kernel  with  a  verdict  specifying
       what  to do with the packets (such as ACCEPT or DROP).  These packets may also be modified
       in userspace prior to reinjection back into the kernel.

       For each supported protocol, a kernel module called a  queue  handler  may  register  with
       Netfilter to perform the mechanics of passing packets to and from userspace.

       The standard queue handler for IPv4 is ip_queue.  It is provided as an experimental module
       with 2.4 kernels, and uses a Netlink socket for kernel/userspace communication.

       Once ip_queue is loaded, IP packets may be selected with iptables and queued for userspace
       processing via the QUEUE target.  For example, running the following commands:

            # modprobe iptable_filter
            # modprobe ip_queue
            # iptables -A OUTPUT -p icmp -j QUEUE

       will  cause  any  locally  generated  ICMP  packets  (e.g.  ping output) to be sent to the
       ip_queue  module,  which  will  then  attempt  to  deliver  the  packets  to  a  userspace
       application.  If no userspace application is waiting, the packets will be dropped

       An application may receive and process these packets via libipq.

   Libipq Overview
       Libipq  provides  an API for communicating with ip_queue.  The following is an overview of
       API usage, refer to individual man pages for more details on each function.

       Initialisation
       To initialise the library, call ipq_create_handle(3).  This will attempt to  bind  to  the
       Netlink socket used by ip_queue and return an opaque context handle for subsequent library
       calls.

       Setting the Queue Mode
       ipq_set_mode(3) allows the application to  specify  whether  packet  metadata,  or  packet
       payloads as well as metadata are copied to userspace.  It is also used to initially notify
       ip_queue that an application is ready to receive queue messages.

       Receiving Packets from the Queue
       ipq_read(3) waits for queue messages to arrive  from  ip_queue  and  copies  them  into  a
       supplied buffer.  Queue messages may be packet messages or error messages.

       The type of packet may be determined with ipq_message_type(3).

       If  it's  a  packet  message,  the  metadata  and  optional  payload may be retrieved with
       ipq_get_packet(3).

       To retrieve the value of an error message, use ipq_get_msgerr(3).

       Issuing Verdicts on Packets
       To issue a verdict on a packet, and optionally return a modified version of the packet  to
       the kernel, call ipq_set_verdict(3).

       Error Handling
       An  error  string  corresponding  to  the  current  value  of  the internal error variable
       ipq_errno may be obtained with ipq_errstr(3).

       For  simple  applications,  calling  ipq_perror(3)  will  print  the   same   message   as
       ipq_errstr(3),  as  well as the string corresponding to the global errno value (if set) to
       stderr.

       Cleaning Up
       To free up the Netlink socket and destroy resources associated with  the  context  handle,
       call ipq_destroy_handle(3).

SUMMARY

       ipq_create_handle(3)
           Initialise library, return context handle.

       ipq_set_mode(3)
           Set the queue mode, to copy either packet metadata, or payloads as well as metadata to
           userspace.

       ipq_read(3)
           Wait for a queue message to arrive from ip_queue and read it into a buffer.

       ipq_message_type(3)
           Determine message type in the buffer.

       ipq_get_packet(3)
           Retrieve a packet message from the buffer.

       ipq_get_msgerr(3)
           Retrieve an error message from the buffer.

       ipq_set_verdict(3)
           Set a verdict on a packet, optionally replacing its contents.

       ipq_errstr(3)
           Return an error message corresponding to the internal ipq_errno variable.

       ipq_perror(3)
           Helper function to print error messages to stderr.

       ipq_destroy_handle(3)
           Destroy context handle and associated resources.

EXAMPLE

       The following is an example of a simple application  which  receives  packets  and  issues
       NF_ACCEPT verdicts on each packet.
              /*
               * This code is GPL.
               */
              #include <linux/netfilter.h>
              #include <libipq.h>
              #include <stdio.h>

              #define BUFSIZE 2048

              static void die(struct ipq_handle *h)
              {
                   ipq_perror("passer");
                   ipq_destroy_handle(h);
                   exit(1);
              }

              int main(int argc, char **argv)
              {
                   int status;
                   unsigned char buf[BUFSIZE];
                   struct ipq_handle *h;

                   h = ipq_create_handle(0, NFPROTO_IPV4);
                   if (!h)
                        die(h);

                   status = ipq_set_mode(h, IPQ_COPY_PACKET, BUFSIZE);
                   if (status < 0)
                        die(h);

                   do{
                        status = ipq_read(h, buf, BUFSIZE, 0);
                        if (status < 0)
                             die(h);

                        switch (ipq_message_type(buf)) {
                             case NLMSG_ERROR:
                                  fprintf(stderr, "Received error message %d\n",
                                          ipq_get_msgerr(buf));
                                  break;

                             case IPQM_PACKET: {
                                  ipq_packet_msg_t *m = ipq_get_packet(buf);

                                  status = ipq_set_verdict(h, m->packet_id,
                                                           NF_ACCEPT, 0, NULL);
                                  if (status < 0)
                                       die(h);
                                  break;
                             }

                             default:
                                  fprintf(stderr, "Unknown message type!\n");
                                  break;
                        }
                   } while (1);

                   ipq_destroy_handle(h);
                   return 0;
              }

       Pointers to more libipq application examples may be found in The Netfilter FAQ.

DIAGNOSTICS

       For  information  about  monitoring  and  tuning  ip_queue,  refer to the Linux 2.4 Packet
       Filtering HOWTO.

       If an application modifies a packet, it needs to also update any checksums for the packet.
       Typically, the kernel will silently discard modified packets with invalid checksums.

SECURITY

       Processes  require  CAP_NET_ADMIN  capabilty  to  access the kernel ip_queue module.  Such
       processes can potentially  access  and  modify  any  IP  packets  received,  generated  or
       forwarded by the kernel.

TODO

       Per-handle ipq_errno values.

BUGS

       Probably.

AUTHOR

       James Morris <jmorris@intercode.com.au>

COPYRIGHT

       Copyright (c) 2000-2001 Netfilter Core Team.

       Distributed under the GNU General Public License.

CREDITS

       Joost Remijn implemented the ipq_read timeout feature, which appeared in the 1.2.4 release
       of iptables.

       Fernando Anton added support for IPv6.

SEE ALSO

       iptables(8),       ipq_create_handle(3),       ipq_destroy_handle(3),       ipq_errstr(3),
       ipq_get_msgerr(3),  ipq_get_packet(3),  ipq_message_type(3),  ipq_perror(3),  ipq_read(3),
       ipq_set_mode(3), ipq_set_verdict(3).

       The Netfilter home page at http://netfilter.samba.org/ which has links to  The  Networking
       Concepts  HOWTO,  The  Linux  2.4  Packet  Filtering  HOWTO,  The Linux 2.4 NAT HOWTO, The
       Netfilter Hacking HOWTO, The Netfilter FAQ and many other useful resources.