> ## Documentation Index
> Fetch the complete documentation index at: https://wireblast.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Short answers to the things people ask first.

## Getting going

<AccordionGroup>
  <Accordion title="Do I need special hardware?">
    No. Wireblast runs on any Linux box with a NIC, and it works across a `veth` pair with no NIC at all.

    You get the best performance on a driver with native XDP support (Intel `ixgbe`, `i40e`, `ice`, Mellanox `mlx5`, AWS `ena`), but everything works in generic mode too. It's just slower.
  </Accordion>

  <Accordion title="Can I try it without a spare interface?">
    Yes. A `veth` pair and a network namespace give you a sender and a receiver on one machine, and nothing you do there can touch your real network. About four commands: see the [namespace lab](/guides/namespace-lab).
  </Accordion>

  <Accordion title="Does it need root?">
    Root, or the capabilities:

    ```bash theme={null}
    sudo setcap cap_net_raw,cap_bpf,cap_sys_resource+ep $(command -v wireblast)
    ```

    AF\_XDP has to create raw sockets and load an XDP program, and both are privileged operations.
  </Accordion>

  <Accordion title="Will it break my SSH session?">
    Not by default. Wireblast transmits only, installing an XDP program that matches nothing, so every packet the interface receives keeps going up the kernel stack exactly as before.

    It can if you turn receiving on with a broad filter. That's why `--rx-mode all` needs both a flag and a typed confirmation. Details in [transmit and receive](/concepts/receive).

    Separately, attaching to a physical NIC drops carrier for several seconds, so don't do it on the interface you're logged in over.
  </Accordion>

  <Accordion title="Can I capture everything except SSH and DNS?">
    Yes: `--rx-mode keep-management`. It redirects everything on the interface to Wireblast but leaves SSH, DNS, and ARP/ND with the kernel, so you can capture broadly on the same NIC you're logged in over without losing your session. No `--allow-match-all` needed, because it can't strand the box.

    See [transmit and receive](/concepts/receive#capturing-everything-safely-keep-management).
  </Accordion>

  <Accordion title="Will it change anything on my machine?">
    Nothing permanent. It won't touch your MTU, routes, addresses, queue counts or memory limits. It tells you when one of those would help (for example `ip link set eno2 mtu 3000`) and leaves the change to you.

    It does temporarily tune the interface's NAPI settings (`napi_defer_hard_irqs`, `gro_flush_timeout`) on a native-XDP NIC, because that is a large receive-side performance win, and it puts them back when it exits. The dashboard shows what it tuned, and you can opt out if something else owns that interface's tuning.

    The one thing it writes to disk is `~/.wireblast/`, which remembers your settings between runs. Clear it with `--forget`.
  </Accordion>
</AccordionGroup>

## While running

<AccordionGroup>
  <Accordion title="Why did my link go down for ten seconds?">
    Attaching a native XDP program makes the driver reinitialise its queues, which drops carrier while the link renegotiates. On a 10G Intel NIC that's typically 8 to 11 seconds. It's normal.

    The run clock doesn't start until the link is back, so you don't lose any of your requested duration. And it only happens once per process: pressing `r` to run again reuses the attachment and restarts in about two seconds.
  </Accordion>

  <Accordion title="Which bit rate should I use, L1 or L2?">
    **L1** for link utilisation, the "am I filling the pipe" question. A 10G link carries 10 Gbit/s of L1 and nothing more.

    **L2** for the frame you actually asked for, `--packet-size` bytes of it.

    `--bps` is measured in L1, so `--bps 10G` means 10G line rate. [Full explanation](/concepts/numbers).
  </Accordion>

  <Accordion title="Why does bwm-ng show a lower number than Wireblast?">
    Because the kernel's byte counters exclude the 4-byte FCS by specification, and on a VLAN sub-interface they also exclude the Ethernet header and the tag.

    About 6% low at 64-byte frames, 1% at IMIX. Point it at the physical NIC and it lands just under Wireblast's L2. Nothing is wrong; they're counting at different layers.
  </Accordion>

  <Accordion title="Is --packet-size the frame or the payload?">
    The whole Ethernet frame, **including the 4-byte FCS**. So `--packet-size 64` is the classic 64-byte frame. Wireblast writes 60 bytes and the NIC appends the FCS.

    This is the single definition that trips people up most.
  </Accordion>

  <Accordion title="Is --pps per queue or in total?">
    In total. `--pps 1M` is a million packets per second aggregate, whether Wireblast is using one queue or twelve. Measured across 1, 4 and 12 queues on the same NIC: 999.34, 999.35 and 999.44 kpps.
  </Accordion>

  <Accordion title="Why can't I use --packet-size 64 with a VLAN tag?">
    The 64-byte Ethernet minimum is measured on the untagged frame, so a tagged frame can't be smaller than 68. The NIC pads anything shorter, which would make every rate Wireblast reported short by the difference.

    Use 68. Verified on ixgbe: 64, 66 and 68 with a tag all left as 68-byte frames.
  </Accordion>
</AccordionGroup>

## Capabilities

<AccordionGroup>
  <Accordion title="Does it measure latency?">
    No. Wireblast counts packets and bytes. There's no latency measurement, no jitter, and no hardware timestamping. If you need those, you need a different class of tool.
  </Accordion>

  <Accordion title="Does it support IPv6?">
    Yes. Give it an IPv6 source and destination and it builds IPv6 frames: UDP, TCP SYN, IMIX, raw and PCAP, plus flows and CIDR cycling across a prefix. Next-hop resolution uses neighbour discovery (NDP) the same way the IPv4 path uses ARP.

    The smallest frame is a little larger than IPv4, 66 bytes for UDP and 78 for TCP (add 4 with a VLAN tag), because the IPv6 header is 40 bytes and its UDP checksum is mandatory.

    On the receive side the address-based filters (`cidr`, `generated-flow`, `keep-management`, `all`) work for IPv6; the `udp-port` and `tcp-port` filters are still IPv4 only. There are runnable [IPv6 examples](https://github.com/atoonk/wireblast/tree/main/examples) in the repo.
  </Accordion>

  <Accordion title="Is the TCP mode a real TCP session?">
    No. It's stateless SYNs: correct checksums, no handshake, no connection state, no retransmission. Useful for stressing a connection table, not for measuring throughput of an actual TCP flow.
  </Accordion>

  <Accordion title="Can it replay a pcap?">
    Yes, frame for frame, from `.pcap` or `.pcapng`. You choose between the capture's original timing and a rate you set. See [PCAP replay](/patterns/pcap).

    It doesn't rewrite addresses or recompute checksums unless you explicitly override the MACs.
  </Accordion>

  <Accordion title="Can I generate from several interfaces at once?">
    Not in one process. Run one Wireblast per interface.
  </Accordion>

  <Accordion title="Does it do QinQ or stacked VLAN tags?">
    No, one 802.1Q tag only.
  </Accordion>

  <Accordion title="Is there JSON output?">
    Not yet. `--no-tui` prints plain text, and the `ran for` summary block is the stable thing to parse.
  </Accordion>

  <Accordion title="Is there a config file?">
    No. Everything is flags, and the TUI remembers your last run in `~/.wireblast/` so you don't have to retype them.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="It says the locked-memory limit is too low">
    The most common first-run failure. AF\_XDP buffers are locked pages, one UMEM per queue, and the usual 8 MB default isn't enough.

    ```bash theme={null}
    ulimit -l 121634          # this shell
    ```

    Or use fewer queues with `--queues 3`, which needs no host changes at all. Wireblast prints the exact numbers for your run.
  </Accordion>

  <Accordion title="It says an XDP program is already attached">
    Either another Wireblast is running (`pgrep -a wireblast`), or a previous one died without cleaning up. Clear it:

    ```bash theme={null}
    sudo ip link set dev eno2 xdp off
    ```

    On kernel 5.9 and later this shouldn't happen: the program is held by a BPF link the kernel tears down when the process dies.
  </Accordion>

  <Accordion title="It won't resolve the destination MAC">
    Wireblast works one out from your routing and neighbour tables, and stops if it can't. It never falls back to broadcast, because flooding every port in the broadcast domain isn't a reasonable thing to do by accident.

    Pass `--dst-mac` directly if you're deliberately sending at something that won't answer ARP. The [decision tree](/patterns/flows#working-out-the-next-hop-mac) covers each failure.
  </Accordion>

  <Accordion title="I picked my VLAN interface and it refused">
    AF\_XDP attaches to the physical device. Use `--interface eno2 --vlan 100` and Wireblast builds the tag itself.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Project

<AccordionGroup>
  <Accordion title="What's it built on?">
    [go-afxdp](https://github.com/atoonk/go-afxdp), a standalone Go library for AF\_XDP. Wireblast is the packet generator on top of it. If you want to write your own line-rate tool in Go, start with the library.
  </Accordion>

  <Accordion title="Does it use libpcap or DPDK?">
    Neither. It's pure Go with `CGO_ENABLED=0`, so you get one static binary with no runtime dependencies. PCAP files are read with a pure-Go parser.
  </Accordion>

  <Accordion title="Does it run on macOS or Windows?">
    No. AF\_XDP is a Linux kernel facility, so there's no port and there won't be one.
  </Accordion>
</AccordionGroup>