Troubleshooting

Wireblast tries to fail before it touches anything, and to say what would fix it. If you’re here, something got past that. These are the ones people actually hit.

It won’t start

insufficient privileges

error  insufficient privileges
       AF_XDP needs to create raw sockets and load an XDP program, which
       requires root or CAP_NET_RAW.

Run it with sudo, or grant the capabilities once:

sudo setcap cap_net_raw,cap_bpf,cap_sys_resource+ep $(command -v wireblast)

Re-apply that whenever you replace the binary, since capabilities live on the file.If sudo wireblast says “command not found”, you installed with go install and the binary is in your user’s GOPATH, which root’s PATH doesn’t include. Copy it to /usr/local/bin.

locked-memory limit too low

error  locked-memory limit too low
       this run needs about 118 MiB of locked memory (12 queues x 4096 frames
       x 2048 bytes), but the limit is 8 MiB.

The most common first-run failure. Three fixes, all fine:

ulimit -l 121634          # this shell only

# /etc/security/limits.conf, permanent
* soft memlock unlimited
* hard memlock unlimited

sudo wireblast --queues 3 ...    # less memory, no host changes

Wireblast already raises its own soft limit to the hard limit before checking, so if you’re seeing this, the hard limit is the binding one.

no interface named ...

wireblast: no interface named "vlan.2131"

Check the name with ip -br link show. If you meant a VLAN, see the next entry.

... is a VLAN sub-interface

vlan.2043 is a VLAN sub-interface (VLAN 2043 on eno2). AF_XDP attaches to the
physical NIC, so use --interface eno2 --vlan 2043 instead and Wireblast will
emit tagged frames itself.

Do what it says. Details in VLAN-tagged traffic.

XDP program is already attached

open AF_XDP on eno2: afxdp: could not open eno2 (12 queues): generic attach:
afxdp: XDP program id 1234 is already attached

Something else owns the interface. Either another Wireblast is running:

pgrep -a wireblast

Or a previous run died without cleaning up, which is possible on kernels older than 5.9, where the program isn’t tied to the process lifetime. Clear it:

sudo ip link set dev eno2 xdp off

Confirm it’s gone with ip link show eno2. There should be no xdp in the output.

It won’t accept my settings

packet-size is out of range ... with a VLAN tag

--packet-size 64 is out of range for --mode udp with a VLAN tag; use 68-9018

A tagged frame can’t be smaller than 68 bytes. Use 68. Why.

packets are larger than the interface MTU

error  packets are larger than the interface MTU
       eno2 has an MTU of 1500, but the largest packet carries 1980 bytes
       above the Ethernet header.
       Use --packet-size 1518 or smaller, or raise the MTU yourself with
       `sudo ip link set eno2 mtu 2000`.

Wireblast will not change your MTU. Either send smaller frames or raise it yourself.The VLAN tag doesn’t count against the MTU, which is why a 1500-byte MTU accepts --packet-size 1522 when tagged.

raw Ethernet frames carry no IP addresses

raw Ethernet frames carry no IP addresses, so there is nothing to resolve a
next-hop MAC from.
Give an explicit --dst-mac (or fill in Destination MAC in the wizard) to continue.

--mode raw always needs --dst-mac.

has no IPv4 address to send from

wireblast: eno2 has no IPv4 address to send from; set --src-ip explicitly

Normal on a NIC used only for testing, especially when the addresses live on a VLAN sub-interface. Pass --src-ip. It doesn’t have to be an address the host owns, because nothing needs to route back.

rx-mode all requires --allow-match-all

--rx-mode all redirects EVERY packet on eno2 away from the kernel, taking SSH, DNS
and all other traffic on this interface with it. Pass --allow-match-all if
that is really what you want

Working as intended. --yes deliberately doesn’t cover this. See transmit and receive.

the destination did not answer ARP

the destination 192.0.2.10 did not answer ARP on eno2, so its MAC address is
unknown.

Either it isn’t reachable (ping -c1 it), or you’re deliberately sending at something that won’t answer, in which case pass --dst-mac directly. Wireblast never falls back to broadcast. Full decision tree in flows and addressing.

It runs, but the numbers are wrong

It seems to hang for ten seconds at startup

It isn’t hanging:

attaching XDP to eno2 and waiting for the link...
link came back after 11.8s

Attaching native XDP reinitialises the driver’s queues, which drops carrier. Normal, and the run clock doesn’t start until it’s back. Rerunning with r in the TUI skips it entirely. More.

bwm-ng shows a lower number than Wireblast

Expected. The kernel’s counters exclude the FCS, and on a VLAN sub-interface they also exclude the Ethernet header and tag. About 6% at 64-byte frames, 1% at IMIX.Point bwm-ng at the physical NIC and it lands just under Wireblast’s L2. Full explanation.

Which bit rate should I use?

L1 for link utilisation, the “am I filling the pipe” question. L2 for the frame you asked for. --bps is measured in L1.

It says generic XDP, not native

Your driver has no native XDP support, so the kernel fell back. It still works, just much slower and it drops under load. See hardware and drivers.On AWS, ENA needs at least two combined queues and an MTU at or below 3000:

sudo ethtool -L ens5 combined 2
sudo ip link set ens5 mtu 3000

The actual rate is below what I set

If TX errors are zero, you’ve found the box’s limit rather than a fault. Finding your max rate walks through isolating whether it’s the CPU, the NIC or the path.

The receiver counts fewer packets than the sender sent

Check Drops/errors on the receiver. Climbing means its rings filled up, so try more queues or a lower rate. Clean but short means the loss is in the path between them, not at either end.

Getting back to a clean state

# Is anything still running?
pgrep -a wireblast

# Is an XDP program still attached?
ip link show eno2 | grep xdp

# Clear it
sudo ip link set dev eno2 xdp off

# Forget saved settings
sudo wireblast --forget

On kernel 5.9 and later the program is held by a BPF link the kernel tears down when the process dies, so a crashed Wireblast cleans up after itself. On older kernels, the manual xdp off is your recovery.

Getting started

Concepts

Traffic patterns

Guides

Reference

It won’t start

It won’t accept my settings

It runs, but the numbers are wrong

Getting back to a clean state

​It won’t start

​It won’t accept my settings

​It runs, but the numbers are wrong

​Getting back to a clean state

It won’t start

It won’t accept my settings

It runs, but the numbers are wrong

Getting back to a clean state