pdump

README

ndn-dpdk/app/pdump

This package implements a packer dumper. It collects NDN packets matching certain name prefixes as they enter or leave NDN-DPDK, and writes to a pcapng file.

Writer

Writer type represents a packet dump writer thread that runs in an LCore of "PDUMP" role. It receives packets from packet dump sources via a ring buffer, and writes them to a PCAP Next Generation (pcapng) file.

Three pcapng block types may appear in the output file:

• Section Header Block (SHB)
• Interface Description Block (IDB)
• Enhanced Packet Block (EPB)

SHB and IDB are prepared in Go code using GoPacket library, and then passed to C code via the ring buffer. EPB is crafted directly in C code.

Capturing from Face

FaceSource type defines a packet dump source attached to a face, on either incoming or outgoing direction. It is referenced by FaceImpl in RCU protected pointers. If assigned, every packet received or sent by a face is processed through PdumpFace_Process function.

The configuration contains one or more name prefixes under which the packet should be captured, and the probability of capturing a packet that matches the prefix. It is possible to capture every packet by setting a / prefix with probability 1.0. Otherwise, the packet is parsed to extract its name, which is then compared to the list of prefixes. If a packet is chosen to be captured, it is copied into a new mbuf, and sent to the PdumpWriter.

The packet parser for extracting name is greatly simplified compared to the regular parser. It understands both NDNLPv2 and NDN 0.3 packet format, but does not perform NDNLPv2 reassembly. The parser can extract a portion of name that appears in the first fragment, but cannot process subsequent fragments. The only way to capture non-first fragments is setting a / prefix as the only name filter entry, which disables the parser.

In the output file, each NDN-DPDK face appears as a separate network interface. Packets are written as Linux cooked-mode capture (SLL) link type. SLL is chosen instead of Ethernet because:

• By the time faceID is determined, the Ethernet header is already removed.
• In addition to Ethernet-based faces, NDN-DPDK also supports socket faces where no Ethernet headers exist.

Capturing from Ethernet Port

EthPortSource type defines a packet dump source attached to an Ethernet port, at a specific grab opportunity. Currently, the only supported grab opportunity is RxUnmatched: it captures incoming packets on an Ethernet port that does not match any face. It is referenced by EthRxTable table type in an RCU protected pointer. Hence, this feature is only supported on Ethernet ports that use RxTable receive path.

In the output file, each Ethernet port appears as a network interface. Packets are written as Ethernet link type, with the original Ethernet headers.

Documentation

Overview

Package pdump implements a packet dumper.

Index

• Constants
• Variables
• type Direction
• type EthGrab
• type EthPortConfig
• type EthPortSource
  • func NewEthPortSource(cfg EthPortConfig) (s *EthPortSource, e error)
  • func (s *EthPortSource) Close() error
• type FaceConfig
• type FaceSource
  • func NewFaceSource(cfg FaceConfig) (s *FaceSource, e error)
  • func (s *FaceSource) Close() error
• type NameFilterEntry
• type Writer
  • func NewWriter(cfg WriterConfig) (w *Writer, e error)
  • func (w *Writer) Close() error
  • func (*Writer) ThreadRole() string
• type WriterConfig

Constants

const (
	// MaxNames is the maximum number of name filters.
	MaxNames = 4

	// WriterBurstSize is the burst size in the writer.
	WriterBurstSize = 64

	// NgTypeSHB is PCAPNG section header block type.
	NgTypeSHB = 0x0A0D0D0A

	// NgTypeIDB is PCAPNG interface description block type.
	NgTypeIDB = 0x00000001

	// NgTypeIDB is PCAPNG enhanced packet block type.
	NgTypeEPB = 0x00000006

	// MbufTypeRaw indicates mbuf should be written unchanged.
	MbufTypeRaw = 0xF0010000

	// MbufTypeSLL indicates mbuf should be written with SLL header.
	MbufTypeSLL = 0xF0020000
)

const (
	MinFileSize     = 1 << 16
	DefaultFileSize = 1 << 24
)

Limits and defaults.

const Role = "PDUMP"

Role is writer thread role name.

Variables

var (
	GqlDirectionEnum        *graphql.Enum
	GqlEthGrabEnum          *graphql.Enum
	GqlNameFilterEntryInput *graphql.InputObject
	GqlNameFilterEntryType  *graphql.Object
	GqlWriterType           *gqlserver.NodeType[*Writer]
	GqlFaceSourceType       *gqlserver.NodeType[*FaceSource]
	GqlEthPortSourceType    *gqlserver.NodeType[*EthPortSource]
	GqlSourceType           *graphql.Union
)

GraphQL types.

var (
	// GqlLCore is the LCore used for writer created via GraphQL.
	GqlLCore eal.LCore
)

Types

type Direction

type Direction string

Direction indicates traffic direction.

const (
	DirIncoming Direction = "RX"
	DirOutgoing Direction = "TX"
)

Direction values.

type EthGrab

type EthGrab string

EthGrab indicates an opportunity to grab packets from Ethernet port.

const (
	EthGrabRxUnmatched EthGrab = "RxUnmatched"
)

EthGrab values.

type EthPortConfig

type EthPortConfig struct {
	Writer *Writer
	Port   *ethport.Port
	Grab   EthGrab
	// contains filtered or unexported fields
}

EthPortConfig contains EthPortSource configuration.

type EthPortSource

type EthPortSource struct {
	EthPortConfig
	// contains filtered or unexported fields
}

EthPortSource is a packet dump source attached to an Ethernet port on a grab opportunity.

func NewEthPortSource

func NewEthPortSource(cfg EthPortConfig) (s *EthPortSource, e error)

NewEthPortSource creates a EthPortSource.

func (*EthPortSource) Close

func (s *EthPortSource) Close() error

Close detaches the dump source.

type FaceConfig

type FaceConfig struct {
	Writer *Writer
	Face   iface.Face
	Dir    Direction
	Names  []NameFilterEntry
}

FaceConfig contains FaceSource configuration.

type FaceSource

type FaceSource struct {
	FaceConfig
	// contains filtered or unexported fields
}

FaceSource is a packet dump source attached to a face on a single direction.

func NewFaceSource

func NewFaceSource(cfg FaceConfig) (s *FaceSource, e error)

NewFaceSource creates a FaceSource.

func (*FaceSource) Close

func (s *FaceSource) Close() error

Close detaches the dump source.

type NameFilterEntry

type NameFilterEntry struct {
	Name              ndn.Name `json:"name" gqldesc:"NDN name prefix."`
	SampleProbability float64  `json:"sampleProbability" gqldesc:"Sample probability between 0.0 and 1.0." gqldflt:"1.0"`
}

NameFilterEntry matches a name prefix and specifies its sample rate. An empty name matches all packets.

type Writer

type Writer struct {
	ealthread.ThreadWithCtrl
	// contains filtered or unexported fields
}

Writer is a packet dump writer thread.

func NewWriter

func NewWriter(cfg WriterConfig) (w *Writer, e error)

NewWriter creates a pdump writer thread.

func (*Writer) Close

func (w *Writer) Close() error

Close releases resources.

func (*Writer) ThreadRole

func (*Writer) ThreadRole() string

ThreadRole implements ealthread.ThreadWithRole interface.

type WriterConfig

type WriterConfig struct {
	Filename     string
	MaxSize      int
	RingCapacity int
	Socket       eal.NumaSocket
}

WriterConfig contains writer configuration.