Man Linux: Main Page and Category List

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.