afpacket

Documentation

Overview

Package afpacket provides Go bindings for MMap'd AF_PACKET socket reading.

Index

• Constants
• type FanoutType
• type OptBlockSize
• type OptBlockTimeout
• type OptFrameSize
• type OptInterface
• type OptNumBlocks
• type OptPollTimeout
• type OptSocketType
  • func (t OptSocketType) String() string
• type OptTPacketVersion
  • func (t OptTPacketVersion) String() string
• type Stats
• type TPacket
  • func NewTPacket(opts ...interface{}) (h *TPacket, err error)
  • func (h *TPacket) Close()
  • func (h *TPacket) ReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)
  • func (h *TPacket) ReadPacketDataTo(data []byte) (ci gopacket.CaptureInfo, err error)
  • func (h *TPacket) SetBPFFilter(expr string) (err error)
  • func (h *TPacket) SetFanout(t FanoutType, id uint16) error
  • func (h *TPacket) Stats() (Stats, error)
  • func (h *TPacket) WritePacketData(pkt []byte) error
  • func (h *TPacket) ZeroCopyReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)

Constants

const (
	// TPacketVersionHighestAvailable tells NewHandle to use the highest available version of tpacket the kernel has available.
	// This is the default, should a version number not be given in NewHandle's options.
	TPacketVersionHighestAvailable = OptTPacketVersion(-1)
	TPacketVersion1                = OptTPacketVersion(C.TPACKET_V1)
	TPacketVersion2                = OptTPacketVersion(C.TPACKET_V2)
	TPacketVersion3                = OptTPacketVersion(C.TPACKET_V3)

	// SocketRaw is the default socket type.  It returns packet data
	// including the link layer (ethernet headers, etc).
	SocketRaw = OptSocketType(C.SOCK_RAW)
	// SocketDgram strips off the link layer when reading packets, and adds
	// the link layer back automatically on packet writes (coming soon...)
	SocketDgram = OptSocketType(C.SOCK_DGRAM)
)

const (
	DefaultFrameSize    = 4096                   // Default value for OptFrameSize.
	DefaultBlockSize    = DefaultFrameSize * 128 // Default value for OptBlockSize.
	DefaultNumBlocks    = 128                    // Default value for OptNumBlocks.
	DefaultBlockTimeout = 64 * time.Millisecond  // Default value for OptBlockTimeout.
	DefaultPollTimeout  = BlockForever           // Default value for OptPollTimeout.
)

const BlockForever = -time.Millisecond

Types

type FanoutType

type FanoutType int

FanoutType determines the type of fanout to use with a TPacket SetFanout call.

const (
	FanoutHash FanoutType = 0
	// It appears that defrag only works with FanoutHash, see:
	// http://lxr.free-electrons.com/source/net/packet/af_packet.c#L1204
	FanoutHashWithDefrag FanoutType = 0x8000
	FanoutLoadBalance    FanoutType = 1
	FanoutCPU            FanoutType = 2
)

type OptBlockSize

type OptBlockSize int

OptBlockSize is TPacket's tp_block_size It can be passed into NewTPacket.

type OptBlockTimeout

type OptBlockTimeout time.Duration

OptBlockTimeout is TPacket v3's tp_retire_blk_tov. Note that it has only millisecond granularity, so must be >= 1 ms. It can be passed into NewTPacket.

type OptFrameSize

type OptFrameSize int

OptFrameSize is TPacket's tp_frame_size It can be passed into NewTPacket.

type OptInterface

type OptInterface string

OptInterface is the specific interface to bind to. It can be passed into NewTPacket.

type OptNumBlocks

type OptNumBlocks int

OptNumBlocks is TPacket's tp_block_nr It can be passed into NewTPacket.

type OptPollTimeout

type OptPollTimeout time.Duration

OptPollTimeout is the maximum amount of time to wait in the poll system call. Note that an empty packet will be returned in most cases when a timeout happens. Setting this to BlockForever disables the timeout.

type OptSocketType

type OptSocketType int

OptSockType is the socket type used to open the TPacket socket.

func (OptSocketType) String

func (t OptSocketType) String() string

type OptTPacketVersion

type OptTPacketVersion int

OptTPacketVersion is the version of TPacket to use. It can be passed into NewTPacket.

func (OptTPacketVersion) String

func (t OptTPacketVersion) String() string

String returns a string representation of the version, generally of the form V#.

type Stats

type Stats struct {
	// Packets is the total number of packets returned to the caller.
	Packets int64
	// Polls is the number of blocking syscalls made waiting for packets.
	// This should always be <= Packets, since with TPacket one syscall
	// can (and often does) return many results.
	Polls int64
}

Stats is a set of counters detailing the work TPacket has done so far.

type TPacket

type TPacket struct {
	// contains filtered or unexported fields
}

func NewTPacket

func NewTPacket(opts ...interface{}) (h *TPacket, err error)

NewTPacket returns a new TPacket object for reading packets off the wire. Its behavior may be modified by passing in any/all of afpacket.Opt* to this function. If this function succeeds, the user should be sure to Close the returned TPacket when finished with it.

func (*TPacket) Close

func (h *TPacket) Close()

Close cleans up the TPacket. It should not be used after the Close call.

func (*TPacket) ReadPacketData

func (h *TPacket) ReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)

ReadPacketData reads the next packet, copies it into a new buffer, and returns that buffer. Since the buffer is allocated by ReadPacketData, it is safe for long-term use. This implements gopacket.PacketDataSource.

func (*TPacket) ReadPacketDataTo

func (h *TPacket) ReadPacketDataTo(data []byte) (ci gopacket.CaptureInfo, err error)

ReadPacketDataTo reads packet data into a user-supplied buffer. This function reads up to the length of the passed-in slice. The number of bytes read into data will be returned in ci.CaptureLength, which is the minimum of the size of the passed-in buffer and the size of the captured packet.

func (*TPacket) SetBPFFilter

func (h *TPacket) SetBPFFilter(expr string) (err error)

SetBPFFilter compiles and sets a BPF filter for the TPacket handle.

func (*TPacket) SetFanout

func (h *TPacket) SetFanout(t FanoutType, id uint16) error

SetFanout activates TPacket's fanout ability. Use of Fanout requires creating multiple TPacket objects and the same id/type to a SetFanout call on each. Note that this can be done cross-process, so if two different processes both call SetFanout with the same type/id, they'll share packets between them. The same should work for multiple TPacket objects within the same process.

func (*TPacket) Stats

func (h *TPacket) Stats() (Stats, error)

Stats returns statistics on the packets the TPacket has seen so far.

func (*TPacket) WritePacketData

func (h *TPacket) WritePacketData(pkt []byte) error

WritePacketData transmits a raw packet.

func (*TPacket) ZeroCopyReadPacketData

func (h *TPacket) ZeroCopyReadPacketData() (data []byte, ci gopacket.CaptureInfo, err error)

ZeroCopyReadPacketData reads the next packet off the wire, and returns its data. The slice returned by ZeroCopyReadPacketData points to bytes owned by the TPacket. Each call to ZeroCopyReadPacketData invalidates any data previously returned by ZeroCopyReadPacketData. Care must be taken not to keep pointers to old bytes when using ZeroCopyReadPacketData... if you need to keep data past the next time you call ZeroCopyReadPacketData, use ReadPacketDataData, which copies the bytes into a new buffer for you.

tp, _ := NewTPacket(...)
data1, _, _ := tp.ZeroCopyReadPacketData()
// do everything you want with data1 here, copying bytes out of it if you'd like to keep them around.
data2, _, _ := tp.ZeroCopyReadPacketData()  // invalidates bytes in data1