config

package
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package config holds Wireblast's single, central configuration model.

One Config is shared by the CLI, the TUI wizard, validation and the runtime engine: Cobra flags populate it, the wizard edits it, Validate checks it, and the dataplane consumes it. Nothing downstream reinterprets a user's input.

Index

Constants

View Source 
const (
	// MinPacketSize is the smallest legal Ethernet frame: 60 bytes of
	// header+payload plus the 4-byte FCS the NIC appends.
	MinPacketSize = 64
	// MaxPacketSize is a generous jumbo ceiling. The real limit is the
	// interface MTU and the AF_XDP frame capacity, both checked at preflight
	// where those numbers are known.
	MaxPacketSize = 9018
	// FCSLen is the Ethernet frame check sequence the NIC appends for us. It
	// is part of PacketSize but never written into a UMEM frame.
	FCSLen = 4
	// VLANTagLen is the size of an 802.1Q tag.
	VLANTagLen = 4
	// WireOverhead is the per-frame on-the-wire framing not present in the
	// frame itself: 7-byte preamble + 1-byte start-frame delimiter + 12-byte
	// interframe gap. Wire bytes = PacketSize + WireOverhead.
	WireOverhead = 20
)

Frame-size limits, in total Ethernet frame bytes including the 4-byte FCS. See the package docs on PacketSize for exactly what that means.

View Source 
const DefaultPPS = 100_000

DefaultPPS is the rate the wizard and the CLI start from when the user does not ask for one. Deliberately conservative: an accidental run should not saturate a link. Unlimited is available but must be requested.

Variables

View Source 
var Modes = []Mode{ModeUDP, ModeTCPSYN, ModeIMIX, ModeRaw, ModePCAP, ModeReceive}

Modes lists every traffic pattern, in menu order.

View Source 
var RxModes = []RxMode{RxNone, RxGeneratedFlow, RxUDPPort, RxTCPPort, RxCIDR, RxKeepManagement, RxAll}

RxModes lists every receive mode, in menu order.

Functions

func FormatBPS 

func FormatBPS(bps uint64) string

FormatBPS renders a bit rate the way a human would say it.

func FormatPPS 

func FormatPPS(pps uint64) string

FormatPPS renders a packet rate the way a human would say it.

func FormatSize added in v0.4.0 

func FormatSize(n uint64) string

FormatSize renders a byte count in the binary units ParseSize accepts.

func FrameBytes 

func FrameBytes(packetSize int) int

FrameBytes is the number of bytes Wireblast writes into a UMEM frame for a given total frame size, i.e. everything except the FCS the NIC appends.

func ParseBPS 

func ParseBPS(s string) (uint64, error)

ParseBPS parses a bit-rate. It accepts a plain number of bits per second and the decimal SI suffixes k/K, m/M, g/G and t/T, optionally followed by any of "bps", "bit", "bits", "b/s" or "bit/s". The same words as ParsePPS mean unlimited. 

ParseBPS("1000000000") == 1e9
ParseBPS("1G")         == 1e9
ParseBPS("2.5Gbps")    == 2.5e9
ParseBPS("100Mbit/s")  == 1e8

The rate is measured in on-the-wire bits: each frame costs (PacketSize + 20) * 8 bits, so "10G" really does mean 10G line rate.

func ParseDst 

func ParseDst(s string) (netip.Prefix, error)

ParseDst parses a destination given as either a bare IPv4 address or an IPv4 CIDR, and returns it as a prefix. A bare address becomes a /32.

func ParseHostIP added in v0.2.0 

func ParseHostIP(s string) (netip.Addr, error)

ParseHostIP parses a bare IPv4 or IPv6 address.

func ParseMAC 

func ParseMAC(s string) (net.HardwareAddr, error)

ParseMAC parses a 6-byte Ethernet hardware address.

func ParsePPS 

func ParsePPS(s string) (uint64, error)

ParsePPS parses a packets-per-second rate. It accepts a plain number and the decimal SI suffixes k/K, m/M and g/G (1e3, 1e6, 1e9 — not powers of two, because packet rates are quoted in decimal), optionally followed by "pps". "0", "unlimited", "line-rate", "none", "max" and "off" all mean no limit, returned as 0. 

ParsePPS("1000000") == 1000000
ParsePPS("1M")      == 1000000
ParsePPS("14.88M")  == 14880000
ParsePPS("unlimited") == 0

func ParsePorts 

func ParsePorts(s string) ([]uint16, error)

ParsePorts parses a comma-separated port list, e.g. "53,5353".

func ParseSize added in v0.4.0 

func ParseSize(s string) (uint64, error)

ParseSize parses a memory size in bytes. It accepts a plain number and the suffixes k/K, m/M, g/G and t/T, optionally followed by "B" or "iB". Unlike ParsePPS and ParseBPS the multipliers are binary (1k = 1024), because memory is quoted in powers of two: the default capture budget is 1<<30, and a decimal "1G" would silently be smaller than that default. 

ParseSize("1073741824") == 1 << 30
ParseSize("512M")       == 512 << 20
ParseSize("4G")         == 4 << 30
ParseSize("4GiB")       == 4 << 30
ParseSize("1.5G")       == 3 << 29

There is no "unlimited": a size of zero or the unlimited words are errors, because an unbounded load is exactly what a memory budget exists to prevent.

func WireBits 

func WireBits(packetSize int) uint64

WireBits is the number of bits a frame of the given total size occupies on the wire, including preamble, start-frame delimiter and interframe gap. This is the unit --bps is measured in.

Types

type Config 

type Config struct {
	// Interface is the NIC to transmit from. AF_XDP binds to the physical
	// device, so this is the parent NIC (e.g. eth0), not a VLAN sub-interface;
	// use VLAN to emit tagged frames.
	Interface string

	Mode Mode

	// Addressing. DstIP accepts a single address or a CIDR.
	SrcIP  string
	DstIP  string
	SrcMAC string
	DstMAC string

	// Ports and flows.
	SrcPort     uint16
	DstPort     uint16
	VaryDstPort bool
	Flows       int
	FlowOrder   FlowOrder

	// PacketSize is the total Ethernet frame size in bytes INCLUDING the
	// 4-byte FCS — the number packet-generator people mean by "64-byte
	// packets". Wireblast writes PacketSize-FCSLen bytes into each frame and
	// the NIC appends the FCS. Ignored in pcap mode, and overridden per packet
	// in imix mode.
	PacketSize int

	// VLAN is an 802.1Q VLAN ID (1-4094), or 0 for untagged. A tag adds 4
	// bytes of header inside PacketSize.
	VLAN int

	// Raw-mode fields.
	EtherType   int // EtherType for ModeRaw
	PayloadByte int // repeating payload byte for ModeRaw

	// Run control.
	Duration time.Duration // 0 means run until stopped
	PPS      uint64        // packets/sec, 0 means unlimited
	BPS      uint64        // on-the-wire bits/sec, 0 means unlimited
	Queues   int           // 0 means all available queues

	// QueuesPerWorker is how many transmit queues one worker drives,
	// round-robin. Zero means let the backend decide: one for AF_XDP, whose
	// per-queue work happens in a soft interrupt on that queue's own core, and
	// several for mlx5, whose send queues have no interrupt and cap well below
	// a core.
	QueuesPerWorker int

	// IO names the packet-I/O backend: "auto" (the default), "afxdp", or
	// "mlx5" for Direct Verbs on ConnectX cards, which needs a binary built
	// with -tags mlx5. Auto picks mlx5 for a transmit-only run on a ConnectX
	// card and AF_XDP everywhere else; the run prints which it chose.
	IO string

	// Receive behaviour.
	RxMode  RxMode
	RxPorts []uint16
	RxCIDR  string

	// PCAP replay.
	PCAPFile   string
	PCAPTiming PcapTiming
	PCAPLoop   bool
	// PCAPMemory is the memory budget in bytes for loading the capture (frame
	// bytes plus index). 0 means the 1 GiB default; the whole capture is held
	// in RAM, so a raised budget has to fit in it.
	PCAPMemory uint64

	// Front-end and confirmation.
	NoTUI bool
	// SkipWizard starts the run immediately and goes straight to the live
	// dashboard, using whatever the flags and remembered settings supply. The
	// wizard is skipped, but the safety confirmations are not.
	SkipWizard    bool
	AssumeYes     bool
	AllowMatchAll bool
}

Config is the complete description of a Wireblast run.

Address and MAC fields are kept as strings because that is what a user types and what the TUI edits; Validate parses them and reports precise errors, and Resolve turns them into the typed values the dataplane uses.

func Default 

func Default() Config

Default returns the configuration Wireblast starts from before any flag or wizard input is applied.

func (*Config) IsIPv6 added in v0.2.0 

func (c *Config) IsIPv6() bool

IsIPv6 reports whether the run's addressing is IPv6, inferred from the destination (or, failing that, the source). Malformed input reads as IPv4, which is harmless: the address validation reports the real error separately.

func (*Config) RateLimited 

func (c *Config) RateLimited() bool

RateLimited reports whether any rate limit is in force. When false the run transmits as fast as the NIC allows.

func (*Config) Transmits 

func (c *Config) Transmits() bool

Transmits reports whether the run puts any packets on the wire. Only ModeReceive does not.

func (*Config) UsesFlows 

func (c *Config) UsesFlows() bool

UsesFlows reports whether the mode walks a flow table.

func (*Config) UsesIPStack 

func (c *Config) UsesIPStack() bool

UsesIPStack reports whether the mode builds IP packets, i.e. whether the IP addressing, port and flow fields are meaningful.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks the configuration for syntactic and cross-field errors without touching the system. It reports every problem it finds, joined, so a form can show them all at once.

It does not check anything that needs the machine (interface existence, MTU, privileges, routing); those are preflight's job.

type FlowOrder 

type FlowOrder string

FlowOrder selects how flows are walked. Sequential is the required, default and fully deterministic behaviour. 

const (
	FlowSequential FlowOrder = "sequential"
	FlowRandom     FlowOrder = "random"
)

type Mode 

type Mode string

Mode is the traffic pattern to generate. 

const (
	ModeUDP    Mode = "udp"     // stateless UDP flows
	ModeTCPSYN Mode = "tcp-syn" // stateless TCP SYN flows (no handshake, no state)
	ModeIMIX   Mode = "imix"    // UDP flows using the classic IMIX size distribution
	ModeRaw    Mode = "raw"     // fixed EtherType + payload pattern
	ModePCAP   Mode = "pcap"    // replay an Ethernet PCAP file
	// ModeReceive transmits nothing at all. It turns Wireblast into the other
	// end of a test: point one machine's traffic at it and watch what arrives.
	ModeReceive Mode = "receive"
)

func (Mode) Describe 

func (m Mode) Describe() string

Describe returns a one-line explanation for the wizard and CLI help.

type PcapTiming 

type PcapTiming string

PcapTiming selects how PCAP replay is paced. 

const (
	// PcapRate ignores the capture's timestamps and paces with --pps/--bps.
	PcapRate PcapTiming = "rate"
	// PcapOriginal preserves the capture's relative inter-packet gaps.
	PcapOriginal PcapTiming = "original"
)

type RxMode 

type RxMode string

RxMode selects what (if anything) is redirected out of the kernel network stack and into Wireblast's AF_XDP sockets. The default is RxNone: transmit only, nothing is taken from the kernel. 

const (
	RxNone          RxMode = "none"           // transmit only (default, safe)
	RxGeneratedFlow RxMode = "generated-flow" // likely return traffic for this test
	RxUDPPort       RxMode = "udp-port"       // UDP to specific destination ports
	RxTCPPort       RxMode = "tcp-port"       // TCP to specific destination ports
	RxCIDR          RxMode = "cidr"           // traffic sourced from a CIDR
	// RxKeepManagement takes everything except the traffic that keeps the box
	// reachable: SSH and DNS to and from this host, plus ARP and IPv6 ND. It is
	// the safe way to capture broadly on the interface you are logged in over.
	RxKeepManagement RxMode = "keep-management"
	RxAll            RxMode = "all" // everything, dangerous
)

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.