org.savarese.vserv.ipq
Class IPQHandle

java.lang.Object
  org.savarese.vserv.ipq.IPQHandle

public class IPQHandle
extends java.lang.Object

IPQHandle encapsulates netfilter libipq operations that require a netfilter handle. First you must open the handle, then set the mode, before you can read and reinject packets. After you're done filtering packets, you must close the netfilter handle.

Only one IPQHandle instance may be open at a time. The Linux netfilter user space queuing allows only one user space packet reading handle to be open at a time.

Author:

Daniel F. Savarese

Field Summary

static int	MODE_COPY_META A mode constant for setMode(int, int) indicating only packet metadata should be copied.
static int	MODE_COPY_NONE A mode constant for setMode(int, int) indicating no packet data should be copied.
static int	MODE_COPY_PACKET A mode constant for setMode(int, int) indicating both packet metadata and packet payloads should be copied.
static int	PF_INET A protocol constant for open(int) indicating IPv4
static int	PF_INET6 A protocol constant for open(int) indicating IPv6
static int	VERDICT_ACCEPT A verdict constant for reinject(org.savarese.vserv.ipq.NetfilterPacket, int, int, byte[]) indicating the packet should be accepted.
static int	VERDICT_DROP A verdict constant for reinject(org.savarese.vserv.ipq.NetfilterPacket, int, int, byte[]) indicating the packet should be dropped.

Constructor Summary

IPQHandle()
Creates an unopened netfilter handle.

Method Summary

void	close() Closes the ipq handle.
void	getErrorMessage(java.lang.StringBuffer buffer) Writes a netfilter IPQ error message into a StringBuffer.
boolean	isOpen()
boolean	open(int protocol) Creates a reference to a netfilter ipq handle, thereby allowing packets to be read.
int	read(NetlinkMessage message) Same as read(message, 0);
int	read(NetlinkMessage message, int timeout) Reads a netlink message from the user space queue, containing packet metadata and possibly packet data payload depending on the mode requested with setMode(int, int).
int	reinject(NetfilterPacket packet, int verdict) Same as reinject(packet, verdict, 0, null);
int	reinject(NetfilterPacket packet, int verdict, int dataLength, byte[] payload) Reinjects a packet into the iptables chain.
int	setMode(int mode, int range) Sets the packet copying mode for calls to read(org.savarese.vserv.ipq.NetlinkMessage, int).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PF_INET

public static final int PF_INET

A protocol constant for open(int) indicating IPv4

See Also:

Constant Field Values

PF_INET6

public static final int PF_INET6

A protocol constant for open(int) indicating IPv6

See Also:

Constant Field Values

MODE_COPY_NONE

public static final int MODE_COPY_NONE

A mode constant for setMode(int, int) indicating no packet data should be copied.

See Also:

Constant Field Values

MODE_COPY_META

public static final int MODE_COPY_META

A mode constant for setMode(int, int) indicating only packet metadata should be copied.

See Also:

Constant Field Values

MODE_COPY_PACKET

public static final int MODE_COPY_PACKET

A mode constant for setMode(int, int) indicating both packet metadata and packet payloads should be copied.

See Also:

Constant Field Values

VERDICT_DROP

public static final int VERDICT_DROP

A verdict constant for reinject(org.savarese.vserv.ipq.NetfilterPacket, int, int, byte[]) indicating the packet should be dropped.

See Also:

Constant Field Values

VERDICT_ACCEPT

public static final int VERDICT_ACCEPT

A verdict constant for reinject(org.savarese.vserv.ipq.NetfilterPacket, int, int, byte[]) indicating the packet should be accepted.

See Also:

Constant Field Values

Constructor Detail

IPQHandle

public IPQHandle()

Creates an unopened netfilter handle.

Method Detail

isOpen

public boolean isOpen()

Returns:

True if the object references a valid netfilter ipq handle.

open

public boolean open(int protocol)
             throws java.lang.IllegalStateException

Creates a reference to a netfilter ipq handle, thereby allowing packets to be read.

Parameters:

protocol - The protocol type of packets to copy; one of either PF_INET or PF_INET6.

Returns:

True if the handle is opened successfully, false if not.

Throws:

java.lang.IllegalStateException - If the object instance is already open.

close

public void close()

Closes the ipq handle.

setMode

public int setMode(int mode,
                   int range)

Sets the packet copying mode for calls to read(org.savarese.vserv.ipq.NetlinkMessage, int).

Parameters:

mode - One of either MODE_COPY_META or MODE_COPY_PACKET. The first indicates only packet metadata should be copied to user space. The second indicates both the packet metadata and data payload should be cpied.

range - The number of bytes of the packet payload to copy. It does not include the bytes in the packet metadata.

Returns:

A positive value on success; -1 on failure.

read

public int read(NetlinkMessage message,
                int timeout)

Reads a netlink message from the user space queue, containing packet metadata and possibly packet data payload depending on the mode requested with setMode(int, int).

Parameters:

message - The message in which to store the message retrieved from the queue.

timeout - A timeout in microseconds specifying the maximum amount of time to wait for a message to become available for reading. If set to zero, the read will block indefinitely.

Returns:

-1 on failure and a positive value on success. A value of zero is returned if a timeout value is specified and no data message was available to be read.

read

public int read(NetlinkMessage message)

Same as read(message, 0);

reinject

public int reinject(NetfilterPacket packet,
                    int verdict,
                    int dataLength,
                    byte[] payload)

Reinjects a packet into the iptables chain. The data payload of the packet can be altered by passing a byte array as an argument. If the payload is not altered, the dataLength should be 0 and the payload should be null.

Parameters:

packet - The packet to reinject.

verdict - The verdict specifying what to do with the packet. A value of VERDICT_DROP indicates the packet should be dropped. A value of VERDICT_ACCEPT indicates the packet should be accepted.

dataLength - The number of bytes of the new payload, starting from offset 0, to copy into the reinjected packet. If the payload is not altered, this value should be set to zero.

payload - The new data payload. If the payload is not altered, this value should be set to null.

Returns:

-1 on failure and a positive value on success.

reinject

public int reinject(NetfilterPacket packet,
                    int verdict)

Same as reinject(packet, verdict, 0, null);

getErrorMessage

public void getErrorMessage(java.lang.StringBuffer buffer)

Writes a netfilter IPQ error message into a StringBuffer. If one of the IPQHandle methods fails, the cause of the error can be determined by calling this method. The message is appended to the supplied StringBuffer argument.

Parameters:

buffer - The buffer in which to store the error message.