Skip to main content
The [net] section configures Firedancer’s networking stack, including the network interface, XDP (Express Data Path) settings, and related options.

​
Network Provider

​
net.provider
string
default:"xdp"
The provider determines which Linux networking stack is used by Firedancer.Options:
  • xdp (default): Use Linux express data path APIs for high performance networking. These APIs map memory from the network device directly into Firedancer to bypass parts of the kernel when reading and writing data.
  • socket: Use UDP sockets and system calls like send(2) for networking. Slower and provided on a best-effort basis as a fallback for hosts which do not support XDP.
Using the XDP networking stack is strongly preferred where possible, as it is faster and better tested.
​
net.interface
string
default:""
Which interface to bind to for network traffic. Currently, only one interface is supported for networking. If this is empty, the default is the interface used to route to 8.8.8.8.You can check your default interface with: ip route get 8.8.8.8
​
net.bind_address
string
default:""
Optional IPv4 bind address for peer-to-peer traffic. For incoming packets, specifies the destination address to listen on. For outgoing packets, sets the default source address.When left unspecified (default), listens on all addresses, and derives the source address for outgoing packets based on address and route tables.This option is passed to the Agave client with the --bind-address argument.
​
net.ingress_buffer_size
integer
default:"16384"
The maximum number of packets in-flight between a net tile and downstream consumers, after which additional packets begin to replace older ones, which will be dropped.Smaller values use less memory. Larger values decrease link overruns caused by excessive latency.

​
XDP Configuration

The [net.xdp] section contains XDP-specific network configuration. Only active if [net.provider] is set to "xdp".
​
net.xdp.xdp_mode
string
default:"skb"
XDP is redundantly provided by different parts in the kernel. This option selects the XDP provider.Options:
  • skb (default): XDP provided by the kernel’s generic network code. This is the slowest mode, but it is well tested and compatible with all Linux network devices and drivers.
  • drv: XDP provided by the device driver. This mode is much faster than “skb” but only works for certain hardware. May require very recent Linux versions. Tested extensively with ConnectX NICs (mlx5), Intel X710 (i40e), and Intel E810 (ice).
  • default: Selects “skb” or “drv” automatically.
If the kernel/hardware does not support driver mode, then fdctl run will fail to start up with “operation not supported”.
​
net.xdp.xdp_zero_copy
boolean
default:"false"
This option helps reduce CPU usage when receiving packets. If enabled, the net tile instructs the network device to copy packets directly (DMA) into the working memory of downstream tiles. This allows scaling ingress up to 100 Gbps per net tile.Only works when XDP is provided by the network driver (xdp_mode = “drv”). If the kernel/hardware does not support zero copy, fdctl run will fail to start up with “operation not supported”.
​
net.xdp.xdp_rx_queue_size
integer
default:"32768"
XDP uses metadata queues shared across the kernel and userspace to relay events about incoming packets. This setting defines the number of entries in the RX queue, which has to be a power of two.Smaller values use less memory. Larger values reduce packet loss caused by excessive scheduling or inter-CPU latency.
​
net.xdp.xdp_tx_queue_size
integer
default:"32768"
This setting defines the number of entries in the TX metadata queue, which has to be a power of two.Smaller values use less memory. Larger values reduce packet loss caused by excessive scheduling or inter-CPU latency.
​
net.xdp.flush_timeout_micros
integer
default:"20"
When the oldest packet in a batch has been queued for more than the specified duration, flushes the batch out to the network device.Smaller values improve latency, larger values may improve throughput.
​
net.xdp.rss_queue_mode
string
default:"simple"
RSS (RX hardware flow steering) queue mode. Each XDP net tile services exactly one hardware queue.Options:
  • simple (default): Reduces the total queue count to equal the number of net tiles. All packets (both interesting to Firedancer and not) are sharded amongst these queues. Simple, reliable, and works everywhere but suboptimal performance impact.
  • dedicated: Reserves a dedicated hardware queue for each net tile. Uses ethtool ‘ntuple’ rules to route incoming packets based on UDP dst port. This mode may not work with some network device setups.
  • auto: Attempts to run in “dedicated” mode but automatically falls back to “simple” mode if necessary.
​
net.xdp.native_bond
boolean
default:"false"
Enable native network bonding support. If native_bond is set to true and [net.interface] is a ‘bond’ type network device, install XDP config at bond slave devices instead of the bond device itself.Requires net_tile_count to be divisible by the number of slave devices. Supports up to 16 slave devices.

​
Socket Configuration

The [net.socket] section is only active when [net.provider] is set to "socket".
​
net.socket.receive_buffer_size
integer
default:"134217728"
Sets the socket receive buffer size via SO_RCVBUF. Raises net.core.rmem_max accordingly.
​
net.socket.send_buffer_size
integer
default:"134217728"
Sets the socket send buffer size via SO_SNDBUF. Raises net.core.wmem_max accordingly.

​
Gossip Configuration

The [gossip] section configures how your validator connects to the gossip network.
​
gossip.entrypoints
array
default:"[]"
Routable DNS name or IP address and port number to use to rendezvous with the gossip cluster.These entrypoints are passed to the Agave client with the --entrypoint argument.
​
gossip.port_check
boolean
default:"true"
If true, checks at startup that at least one of the provided entrypoints can connect to this validator on all necessary ports. If it can’t, then the validator will exit.This option is passed to the Agave client inverted with the --no-port-check argument.
​
gossip.port
integer
default:"8001"
required
The port number to use for receiving gossip messages on this validator.This option is passed to the Agave client with the --gossip-port argument. This argument is required.

​
Configuration Examples

[net]
    provider = "xdp"
    interface = "eth0"
    bind_address = "192.168.1.100"
    
    [net.xdp]
        xdp_mode = "drv"
        xdp_zero_copy = true
        rss_queue_mode = "auto"
For production validators, use XDP with driver mode (xdp_mode = "drv") whenever possible for best performance. Ensure your network hardware supports XDP and that you have recent kernel versions.
The default XDP mode is “skb” which is compatible with all hardware but slower. For optimal performance on supported hardware, switch to “drv” mode.

Build docs developers (and LLMs) love

Get started for freeTalk to us