libipq man page on Scientific

Man page or keyword search:  
man Server   26626 pages
apropos Keyword Search (all sections)
Output format
Scientific logo
[printable version]

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  ker‐
       nel  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	 meta‐
       data,  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  ver‐
       sion 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 mes‐
       sage  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 Net‐
       filter 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 check‐
       sums for the packet.  Typically, the kernel will silently discard modi‐
       fied 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	 pack‐
       ets 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_mes‐
       sage_type(3), ipq_perror(3), ipq_read(3), ipq_set_mode(3), ipq_set_ver‐
       dict(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)
[top]

List of man pages available for Scientific

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net