afpacket

package
v1.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 22, 2023 License: BSD-3-Clause Imports: 14 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
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(unix.TPACKET_V1)
	TPacketVersion2                = OptTPacketVersion(unix.TPACKET_V2)
	TPacketVersion3                = OptTPacketVersion(unix.TPACKET_V3)

	// SocketRaw is the default socket type.  It returns packet data
	// including the link layer (ethernet headers, etc).
	SocketRaw = OptSocketType(unix.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(unix.SOCK_DGRAM)
)

TPacket version numbers for use with NewHandle.

View Source 
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  = -1 * time.Millisecond  // Default value for OptPollTimeout. This blocks forever.
)

Default constants used by options.

Variables

View Source 
var ErrPoll = errors.New("packet poll failed")

ErrPoll returned by poll

View Source 
var ErrTimeout = errors.New("packet poll timeout expired")

ErrTimeout returned on poll timeout

Functions

This section is empty.

Types

type AncillaryVLAN 

type AncillaryVLAN struct {
	// The VLAN VID provided by the kernel.
	VLAN int
}

AncillaryVLAN structures are used to pass the captured VLAN as ancillary data via CaptureInfo.

type FanoutType 

type FanoutType int

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

const (
	FanoutHash FanoutType = unix.PACKET_FANOUT_HASH
	// It appears that defrag only works with FanoutHash, see:
	// http://lxr.free-electrons.com/source/net/packet/af_packet.c#L1204
	FanoutHashWithDefrag FanoutType = unix.PACKET_FANOUT_FLAG_DEFRAG
	FanoutLoadBalance    FanoutType = unix.PACKET_FANOUT_LB
	FanoutCPU            FanoutType = unix.PACKET_FANOUT_CPU
	FanoutRollover       FanoutType = unix.PACKET_FANOUT_ROLLOVER
	FanoutRandom         FanoutType = unix.PACKET_FANOUT_RND
	FanoutQueueMapping   FanoutType = unix.PACKET_FANOUT_QM
	FanoutCBPF           FanoutType = unix.PACKET_FANOUT_CBPF
	FanoutEBPF           FanoutType = unix.PACKET_FANOUT_EBPF
)

FanoutType values.

type OptAddVLANHeader 

type OptAddVLANHeader bool

OptAddVLANHeader modifies the packet data that comes back from the kernel by adding in the VLAN header that the NIC stripped. AF_PACKET by default uses VLAN offloading, in which the NIC strips the VLAN header off of the packet before handing it to the kernel. This means that, even if a packet has an 802.1q header on the wire, it'll show up without one by the time it goes through AF_PACKET. If this option is true, the VLAN header is added back in before the packet is returned. Note that this potentially has a large performance hit, especially in otherwise zero-copy operation.

Note that if you do not need to have a "real" VLAN layer, it may be preferable to use the VLAN ID provided by the AncillaryVLAN struct in CaptureInfo.AncillaryData, which is populated out-of-band and has negligible performance impact. Such ancillary data will automatically be provided if available.

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 number of milliseconds that poll() should block waiting for a file descriptor to become ready. Specifying a negative value in time‐out means an infinite timeout.

type OptSocketType 

type OptSocketType int

OptSocketType 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 SocketStats 

type SocketStats C.struct_tpacket_stats

SocketStats is a struct where socket stats are stored

func (*SocketStats) Drops 

func (s *SocketStats) Drops() uint

Drops returns the number of packets dropped on this socket.

func (*SocketStats) Packets 

func (s *SocketStats) Packets() uint

Packets returns the number of packets seen by this socket.

type SocketStatsV3 

type SocketStatsV3 C.struct_tpacket_stats_v3

SocketStatsV3 is a struct where socket stats for TPacketV3 are stored

func (*SocketStatsV3) Drops 

func (s *SocketStatsV3) Drops() uint

Drops returns the number of packets dropped on this socket.

func (*SocketStatsV3) Packets 

func (s *SocketStatsV3) Packets() uint

Packets returns the number of packets seen by this socket.

func (*SocketStatsV3) QueueFreezes 

func (s *SocketStatsV3) QueueFreezes() uint

QueueFreezes returns the number of queue freezes on this socket.

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
}

TPacket implements packet receiving for Linux AF_PACKET versions 1, 2, and 3.

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) InitSocketStats 

func (h *TPacket) InitSocketStats() error

InitSocketStats clears socket counters and return empty stats.

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) SetBPF 

func (h *TPacket) SetBPF(filter []bpf.RawInstruction) error

SetBPF attaches a BPF filter to the underlying socket

func (*TPacket) SetEBPF 

func (h *TPacket) SetEBPF(progFd int32) error

attach ebpf filter to af-packet

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) SocketStats 

func (h *TPacket) SocketStats() (SocketStats, SocketStatsV3, error)

SocketStats saves stats from the socket to the TPacket instance.

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 ReadPacketData, 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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.