Man Pages

libipq(3) - phpMan libipq(3) - phpMan

Command: man perldoc info search(apropos)  


LIBIPQ(3)                  Linux Programmer's Manual                 LIBIPQ(3)



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  meta-
       data  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_han-
       dle(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 ker-
       nel 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 <jmorrisATintercode.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.




Linux iptables 1.2              16 October 2001                      LIBIPQ(3)