IPQueue(3pm)						User Contributed Perl Documentation					      IPQueue(3pm)

NAME

       IPTables::IPv4::IPQueue - Perl extension for libipq.

SYNOPSIS

	 use IPTables::IPv4::IPQueue qw(:constants);

	 $queue = new IPTables::IPv4::IPQueue();
	 $msg = $queue->get_message();
	 $queue->set_verdict($msg->packet_id(), NF_ACCEPT)

	 $queue->set_mode(IPQ_COPY_PACKET, 2048);

	 IPTables::IPv4::IPQueue->errstr;

	 undef $queue;

DESCRIPTION

       Perlipq (IPTables::IPv4::IPQueue) is a Perl extension for iptables userspace packet queuing via libipq.

       Packets may be selected from the stack via the iptables QUEUE target and passed to userspace.  Perlipq allows these packets to be
       manipulated in Perl and passed back to the stack.

       More information on userspace packet queueing may be found in libipq(3).

CONSTANTS

       Copy Mode
	     IPQ_COPY_META	 -    Copy only packet metadata to userspace.
	     IPQ_COPY_PACKET	 -    Copy metatdata and packet to userspace.

       Packet Verdicts
	     NF_DROP		 -    Ask kernel to drop packet.
	     NF_ACCEPT		 -    Ask kernel to accept packet and continue processing.

ATTRIBUTES

       None.

METHODS

       new( [param => value, ... ] )
	   Constructor.

	   Creates userspace queuing object and sets the queuing mode.

	   Parameters:
	     protocol
	     copy_mode
	     copy_range

	   The protocol parameter, if provided, must be one of PF_INET or PF_INET6, for IPv4 and IPv6 packet queuing respectively.  If no protocol
	   parameter is provided, the default is PF_INET.

	   The default copy mode is IPQ_COPY_META.

       set_mode(mode [, range])
	   Set the queuing mode.

	   The mode parameter must be one of:
	     IPQ_COPY_META
	     IPQ_COPY_PACKET

	   When specifying IPQ_COPY_PACKET mode, the range parameter specifies the number of bytes of payload data to copy to userspace.

	   If the range is not provided and the mode is IPQ_COPY_PACKET, the range will default to zero.  Typically, a range of 1500 will suffice.

	   This method is called by the constructor.

       get_message([timeout])
	   Receives a packet message from the kernel, returning a tainted IPTables::IPv4::IPQueue::Packet object.

	   The optional timeout parameter may be used to specify a timeout for the operation in microseconds.  This is implemented internally via
	   the select() syscall.  A value of zero or no value means to wait indefinitely.

	   The returned object is a helper object with the following read only attributes:

		   packet_id	     ID of queued packet.
		   mark 	     Netfilter mark value.
		   timestamp_sec     Packet arrival time (seconds).
		   timestamp_usec    Packet arrvial time (+useconds).
		   hook 	     Netfilter hook we rode in on.
		   indev_name	     Name of incoming interface.
		   outdev_name	     Name of outgoing interface.
		   hw_protocol	     Hardware protocol.
		   hw_type	     Hardware media type.
		   hw_addrlen	     Hardware address length.
		   hw_addr	     Hardware address.
		   data_len	     Length of payload data.
		   payload	     Payload data.

	   Payload data, if present, is a scalar byte string suitable for use with packages such as NetPacket.

	   If the operation timed out, undef will be returned and the errstr() message will be 'Timeout'.  See the sample dumper.pl script for a
	   simple example of how this may be handled.

       set_verdict(id, verdict [, data_len, buf ])
	   Sets verdict on packet with specified id, and optionally sends modified packet data back to the kernel.

	   The verdict must be one of:
	     NF_DROP
	     NF_ACCEPT

       close()
	   Destroys userpsace queue context and all associated resources.

	   This is called by the destructor, which means you can just do:

	     undef $queue;

	   instead.

       errstsr()
	   Class method, returns an error message based on the most recent library error condition and global errno value.

EXAMPLE

	       package example;
	       use strict;
	       $^W = 1;

	       use IPTables::IPv4::IPQueue qw(:constants);

	       my ($queue, $msg);

	       $queue = new IPTables::IPv4::IPQueue(copy_mode => IPQ_COPY_META)
		       or die IPTables::IPv4::IPQueue->errstr;

	       $msg = $queue->get_message()
		       or die IPTables::IPv4::IPQueue->errstr;

	       $queue->set_verdict($msg->packet_id(), NF_ACCEPT) > 0
		       or die IPTables::IPv4::IPQueue->errstr;

CHANGES

       o   Support for timeouts in get_message() was added in version 1.24.

BUGS

       None known.

COPYRIGHT

       Copyright (c) 2000-2002 James Morris <jmorris@intercode.com.au>

       This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by
       the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation,
       Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

AUTHOR

       James Morris <jmorris@intercode.com.au>

SEE ALSO

       iptables(8)

       libipq(3)

       NetPacket(3)

       The example scripts, passer.pl, passer6.pl and dumper.pl.

perl v5.14.2							    2011-11-15							      IPQueue(3pm)