man IPTables::IPv4::IPQueue (3): 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

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

BUGS

None known.

COPYRIGHT

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 <[email protected]>