Package io.netty.handler.pcap

Class PcapWriteHandler

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.channel.ChannelInboundHandlerAdapter

io.netty.channel.ChannelDuplexHandler

io.netty.handler.pcap.PcapWriteHandler

All Implemented Interfaces:

ChannelHandler, ChannelInboundHandler, ChannelOutboundHandler, Closeable, AutoCloseable

public final class PcapWriteHandler
extends ChannelDuplexHandler
implements Closeable

PcapWriteHandler captures ByteBuf from SocketChannel / ServerChannel or DatagramPacket and writes it into Pcap OutputStream.

Things to keep in mind when using PcapWriteHandler with TCP:

• Whenever ChannelInboundHandlerAdapter.channelActive(ChannelHandlerContext) is called, a fake TCP 3-way handshake (SYN, SYN+ACK, ACK) is simulated as new connection in Pcap.
• Whenever ChannelHandlerAdapter.handlerRemoved(ChannelHandlerContext) is called, a fake TCP 3-way handshake (FIN+ACK, FIN+ACK, ACK) is simulated as connection shutdown in Pcap.
• Whenever ChannelInboundHandlerAdapter.exceptionCaught(ChannelHandlerContext, Throwable) is called, a fake TCP RST is sent to simulate connection Reset in Pcap.
• ACK is sent each time data is send / received.
• Zero Length Data Packets can cause TCP Double ACK error in Wireshark. To tackle this, set captureZeroByte to false.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	PcapWriteHandler.Builder	Builder for PcapWriteHandler
private static enum	PcapWriteHandler.ChannelType
private static final class	PcapWriteHandler.WildcardAddressHolder

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

ChannelHandler.Sharable

Field Summary

Fields

Modifier and Type	Field	Description
private final boolean	captureZeroByte	true if we want to capture packets with zero bytes else false.
private PcapWriteHandler.ChannelType	channelType	Type of the channel this handler is registered on
private InetSocketAddress	handlerAddr	Address of the receiver of the connection
private InetSocketAddress	initiatorAddr	Address of the initiator of the connection
private boolean	isServerPipeline	Set to true if this handler is registered on a server pipeline
private final InternalLogger	logger	Logger for logging events
private final OutputStream	outputStream	OutputStream where we'll write Pcap data.
private PcapWriter	pCapWriter	PcapWriter Instance
private long	receiveSegmentNumber	TCP Receiver Segment Number.
private long	sendSegmentNumber	TCP Sender Segment Number.
private final boolean	sharedOutputStream	true if we want to synchronize on the OutputStream while writing else false.
private final AtomicReference<State>	state	Current of this PcapWriteHandler
private final boolean	writePcapGlobalHeader	true if we want to write Pcap Global Header on initialization of PcapWriter else false.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	PcapWriteHandler(PcapWriteHandler.Builder builder, OutputStream outputStream)
	PcapWriteHandler(OutputStream outputStream)	Deprecated. Use PcapWriteHandler.Builder instead.
	PcapWriteHandler(OutputStream outputStream, boolean captureZeroByte, boolean writePcapGlobalHeader)	Deprecated. Use PcapWriteHandler.Builder instead.

Method Summary

Modifier and Type	Method	Description
static PcapWriteHandler.Builder	builder()
void	channelActive(ChannelHandlerContext ctx)	Calls ChannelHandlerContext.fireChannelActive() to forward to the next ChannelInboundHandler in the ChannelPipeline.
void	channelRead(ChannelHandlerContext ctx, Object msg)	Calls ChannelHandlerContext.fireChannelRead(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline.
void	close()	Close PcapWriter and OutputStream.
private void	completeTCPWrite(InetSocketAddress srcAddr, InetSocketAddress dstAddr, ByteBuf tcpBuf, ByteBufAllocator byteBufAllocator, ChannelHandlerContext ctx)	Write TCP/IP L3 and L2 here.
private void	completeUDPWrite(InetSocketAddress srcAddr, InetSocketAddress dstAddr, ByteBuf udpBuf, ByteBufAllocator byteBufAllocator, ChannelHandlerContext ctx)	Write UDP/IP L3 and L2 here.
void	exceptionCaught(ChannelHandlerContext ctx, Throwable cause)	Calls ChannelHandlerContext.fireExceptionCaught(Throwable) to forward to the next ChannelHandler in the ChannelPipeline.
private static InetSocketAddress	getLocalAddress(Channel ch, InetSocketAddress remote)	Get the local address of a channel.
void	handlerRemoved(ChannelHandlerContext ctx)	Do nothing by default, sub-classes may override this method.
private void	handleTCP(ChannelHandlerContext ctx, Object msg, boolean isWriteOperation)	Handle TCP L4
private void	handleTcpPacket(ChannelHandlerContext ctx, ByteBuf packet, boolean isWriteOperation, ByteBufAllocator byteBufAllocator)
private void	handleUDP(ChannelHandlerContext ctx, Object msg, boolean isWriteOperation)	Handle UDP l4
private static long	incrementUintSegmentNumber(long sequenceNumber, int value)
private void	initializeIfNecessary(ChannelHandlerContext ctx)
boolean	isWriting()	Returns true if the PcapWriteHandler is currently writing packets to the OutputStream else returns false.
private void	logDiscard()
private void	logTCP(boolean isWriteOperation, int bytes, long sendSegmentNumber, long receiveSegmentNumber, InetSocketAddress srcAddr, InetSocketAddress dstAddr, boolean ackOnly)	Logger for TCP
(package private) void	markClosed()
(package private) OutputStream	outputStream()
void	pause()	Pause the PcapWriteHandler from writing packets to the OutputStream.
(package private) PcapWriter	pCapWriter()
void	resume()	Resume the PcapWriteHandler to writing packets to the OutputStream.
(package private) boolean	sharedOutputStream()
(package private) State	state()
String	toString()
void	write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise)	Calls ChannelOutboundInvoker.write(Object, ChannelPromise) to forward to the next ChannelOutboundHandler in the ChannelPipeline.
static void	writeGlobalHeader(OutputStream outputStream)	Writes the Pcap Global Header to the provided OutputStream
(package private) boolean	writePcapGlobalHeader()

Methods inherited from class io.netty.channel.ChannelDuplexHandler

bind, close, connect, deregister, disconnect, flush, read

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

channelInactive, channelReadComplete, channelRegistered, channelUnregistered, channelWritabilityChanged, userEventTriggered

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

ensureNotSharable, handlerAdded, isSharable

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.netty.channel.ChannelHandler

handlerAdded

Field Details

logger

private final InternalLogger logger

Logger for logging events

pCapWriter

private PcapWriter pCapWriter

PcapWriter Instance

outputStream

private final OutputStream outputStream

OutputStream where we'll write Pcap data.

captureZeroByte

private final boolean captureZeroByte

true if we want to capture packets with zero bytes else false.

writePcapGlobalHeader

private final boolean writePcapGlobalHeader

true if we want to write Pcap Global Header on initialization of PcapWriter else false.

sharedOutputStream

private final boolean sharedOutputStream

true if we want to synchronize on the OutputStream while writing else false.

sendSegmentNumber

private long sendSegmentNumber

TCP Sender Segment Number. It'll start with 1 and keep incrementing with number of bytes read/sent and wrap at the uint32 max.

receiveSegmentNumber

private long receiveSegmentNumber

TCP Receiver Segment Number. It'll start with 1 and keep incrementing with number of bytes read/sent and wrap at the uint32 max

channelType

private PcapWriteHandler.ChannelType channelType

Type of the channel this handler is registered on

initiatorAddr

private InetSocketAddress initiatorAddr

Address of the initiator of the connection

handlerAddr

private InetSocketAddress handlerAddr

Address of the receiver of the connection

isServerPipeline

private boolean isServerPipeline

Set to true if this handler is registered on a server pipeline

state

private final AtomicReference<State> state

Current of this PcapWriteHandler

Constructor Details

PcapWriteHandler

@Deprecated
public PcapWriteHandler(OutputStream outputStream)

Deprecated.

Use PcapWriteHandler.Builder instead.

Create new PcapWriteHandler Instance. captureZeroByte is set to false and writePcapGlobalHeader is set to true.

Parameters:

outputStream - OutputStream where Pcap data will be written. Call close() to close this OutputStream.

Throws:

NullPointerException - If OutputStream is null then we'll throw an NullPointerException

PcapWriteHandler

@Deprecated
public PcapWriteHandler(OutputStream outputStream,
 boolean captureZeroByte,
 boolean writePcapGlobalHeader)

Deprecated.

Use PcapWriteHandler.Builder instead.

Create new PcapWriteHandler Instance

Parameters:

outputStream - OutputStream where Pcap data will be written. Call close() to close this OutputStream.

captureZeroByte - Set to true to enable capturing packets with empty (0 bytes) payload. Otherwise, if set to false, empty packets will be filtered out.

writePcapGlobalHeader - Set to true to write Pcap Global Header on initialization. Otherwise, if set to false, Pcap Global Header will not be written on initialization. This could when writing Pcap data on a existing file where Pcap Global Header is already present.

Throws:

NullPointerException - If OutputStream is null then we'll throw an NullPointerException

PcapWriteHandler

private PcapWriteHandler(PcapWriteHandler.Builder builder,
 OutputStream outputStream)

Method Details

writeGlobalHeader

public static void writeGlobalHeader(OutputStream outputStream)
                              throws IOException

Writes the Pcap Global Header to the provided OutputStream

Parameters:

outputStream - OutputStream where Pcap data will be written.

Throws:

IOException - if there is an error writing to the OutputStream

initializeIfNecessary

private void initializeIfNecessary(ChannelHandlerContext ctx)
                            throws Exception

Throws:

Exception

channelActive

public void channelActive(ChannelHandlerContext ctx)
                   throws Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireChannelActive() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

channelActive in interface ChannelInboundHandler

Overrides:

channelActive in class ChannelInboundHandlerAdapter

Throws:

Exception

channelRead

public void channelRead(ChannelHandlerContext ctx,
 Object msg)
                 throws Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireChannelRead(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

channelRead in interface ChannelInboundHandler

Overrides:

channelRead in class ChannelInboundHandlerAdapter

Throws:

Exception

write

public void write(ChannelHandlerContext ctx,
 Object msg,
 ChannelPromise promise)
           throws Exception

Description copied from class: ChannelDuplexHandler

Calls ChannelOutboundInvoker.write(Object, ChannelPromise) to forward to the next ChannelOutboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

write in interface ChannelOutboundHandler

Overrides:

write in class ChannelDuplexHandler

Parameters:

ctx - the ChannelHandlerContext for which the write operation is made

msg - the message to write

promise - the ChannelPromise to notify once the operation completes

Throws:

Exception - thrown if an error occurs

handleTCP

private void handleTCP(ChannelHandlerContext ctx,
 Object msg,
 boolean isWriteOperation)

Handle TCP L4

Parameters:

ctx - ChannelHandlerContext for ByteBuf allocation and fireExceptionCaught

msg - Object must be ByteBuf else it'll be discarded

isWriteOperation - Set true if we have to process packet when packets are being sent out else set false

handleTcpPacket

private void handleTcpPacket(ChannelHandlerContext ctx,
 ByteBuf packet,
 boolean isWriteOperation,
 ByteBufAllocator byteBufAllocator)

completeTCPWrite

private void completeTCPWrite(InetSocketAddress srcAddr,
 InetSocketAddress dstAddr,
 ByteBuf tcpBuf,
 ByteBufAllocator byteBufAllocator,
 ChannelHandlerContext ctx)

Write TCP/IP L3 and L2 here.

Parameters:

srcAddr - InetSocketAddress Source Address of this Packet

dstAddr - InetSocketAddress Destination Address of this Packet

tcpBuf - ByteBuf containing TCP L4 Data

byteBufAllocator - ByteBufAllocator for allocating bytes for TCP/IP L3 and L2 data.

ctx - ChannelHandlerContext for fireExceptionCaught

incrementUintSegmentNumber

private static long incrementUintSegmentNumber(long sequenceNumber,
 int value)

handleUDP

private void handleUDP(ChannelHandlerContext ctx,
 Object msg,
 boolean isWriteOperation)

Handle UDP l4

Parameters:

ctx - ChannelHandlerContext for localAddress / remoteAddress, ByteBuf allocation and fireExceptionCaught

msg - DatagramPacket or ByteBuf

completeUDPWrite

private void completeUDPWrite(InetSocketAddress srcAddr,
 InetSocketAddress dstAddr,
 ByteBuf udpBuf,
 ByteBufAllocator byteBufAllocator,
 ChannelHandlerContext ctx)

Write UDP/IP L3 and L2 here.

Parameters:

srcAddr - InetSocketAddress Source Address of this Packet

dstAddr - InetSocketAddress Destination Address of this Packet

udpBuf - ByteBuf containing UDP L4 Data

byteBufAllocator - ByteBufAllocator for allocating bytes for UDP/IP L3 and L2 data.

ctx - ChannelHandlerContext for fireExceptionCaught

getLocalAddress

private static InetSocketAddress getLocalAddress(Channel ch,
 InetSocketAddress remote)

Get the local address of a channel. If the address is a wildcard address (0.0.0.0 or ::), and the address family does not match that of the remote, return the wildcard address of the remote's family instead.

Parameters:

ch - The channel to get the local address from

remote - The remote address

Returns:

The fixed local address

handlerRemoved

public void handlerRemoved(ChannelHandlerContext ctx)
                    throws Exception

Description copied from class: ChannelHandlerAdapter

Do nothing by default, sub-classes may override this method.

Specified by:

handlerRemoved in interface ChannelHandler

Overrides:

handlerRemoved in class ChannelHandlerAdapter

Throws:

Exception

exceptionCaught

public void exceptionCaught(ChannelHandlerContext ctx,
 Throwable cause)
                     throws Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireExceptionCaught(Throwable) to forward to the next ChannelHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

exceptionCaught in interface ChannelHandler

Specified by:

exceptionCaught in interface ChannelInboundHandler

Overrides:

exceptionCaught in class ChannelInboundHandlerAdapter

Throws:

Exception

logTCP

private void logTCP(boolean isWriteOperation,
 int bytes,
 long sendSegmentNumber,
 long receiveSegmentNumber,
 InetSocketAddress srcAddr,
 InetSocketAddress dstAddr,
 boolean ackOnly)

Logger for TCP

outputStream

OutputStream outputStream()

sharedOutputStream

boolean sharedOutputStream()

writePcapGlobalHeader

boolean writePcapGlobalHeader()

isWriting

public boolean isWriting()

Returns true if the PcapWriteHandler is currently writing packets to the OutputStream else returns false.

state

State state()

pause

public void pause()

Pause the PcapWriteHandler from writing packets to the OutputStream.

resume

public void resume()

Resume the PcapWriteHandler to writing packets to the OutputStream.

markClosed

void markClosed()

pCapWriter

PcapWriter pCapWriter()

logDiscard

private void logDiscard()

toString

public String toString()

Overrides:

toString in class Object

close

public void close()
           throws IOException

Close PcapWriter and OutputStream.

Note: Calling this method does not close PcapWriteHandler. Only Pcap Writes are closed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - If OutputStream.close() throws an exception

builder

public static PcapWriteHandler.Builder builder()