xdp-filter

Load the filter on an interface in skb (generic) mode with default allow policy

$ sudo xdp-filter load [[-p|--policy]] allow [[-m|--mode]] skb [network_interface]

$ sudo xdp-filter unload [network_interface]

$ sudo xdp-filter port [destination_port]

$ sudo xdp-filter ip [[-m|--mode]] src [source_ip]

$ sudo xdp-filter ether [[-m|--mode]] src [mac_address]

$ sudo xdp-filter poll [[-i|--interval]] 10000

xdp-filter [OPTIONS] COMMAND [ARGS]

Commands:
  xdp-filter attach -i IFACE -p PROG_FILE [-F FUNC_NAME] [-m MODE | -S | -D | -U] [--force] [--reuse-maps]
  xdp-filter detach -i IFACE [-m MODE | -S | -D | -U | --all]
  xdp-filter show -i IFACE
  xdp-filter list
  xdp-filter stats -i IFACE [-p PROG_FILE] [--interval SECONDS]
  xdp-filter help
  xdp-filter version

attach
    Attaches an XDP eBPF program from a specified object file to a network interface.

detach
    Detaches an XDP program from a specified network interface and mode.

show
    Displays the current XDP program status for a given network interface.

list
    Lists all XDP programs currently loaded on the system.

stats
    Shows statistics for an XDP program attached to an interface, including packet counts and actions.

-i IFACE
    Specifies the network interface name (e.g., eth0) to operate on. Required for most commands.

-p PROG_FILE
    Specifies the path to the ELF object file containing the compiled eBPF XDP program.

-F FUNC_NAME
    Specifies the name of the function within the eBPF object file to be attached as the XDP program. Defaults to xdp_filter.

-m MODE
    Specifies the XDP mode to use for attachment or detachment. Can be generic, driver, or offload. (Mutually exclusive with -S, -D, -U).

-S
    Shortcut for setting XDP mode to generic (SKB mode).

-D
    Shortcut for setting XDP mode to driver.

-U
    Shortcut for setting XDP mode to offload (hardware offload).

--force
    Forces attachment of the XDP program, replacing any existing program on the interface in the specified mode.

--reuse-maps
    Instructs xdp-filter to reuse existing BPF maps if they already exist with the same name and definition.

--all
    Used with detach to detach XDP programs from all possible modes (generic, driver, offload) on the specified interface.

--interval SECONDS
    Specifies the refresh interval in seconds for displaying statistics with the stats command.

-h, --help
    Displays a help message and exits.

-v, --version
    Displays version information and exits.

xdp-filter is a command-line utility used to manage eXpress Data Path (XDP) programs on Linux network interfaces. XDP is a high-performance, programmable network data path in the Linux kernel that allows for custom packet processing at the earliest possible point, even before the kernel’s networking stack fully processes the packet. This enables extremely fast packet filtering, forwarding, or modification, making it ideal for scenarios like DDoS mitigation, load balancing, or custom network monitoring.

The utility takes an eBPF (extended Berkeley Packet Filter) program, typically compiled from C code into an ELF object file (.o file), and attaches it to a specified network interface. It supports various XDP modes, including generic (software-based, works on any driver), driver-specific (optimized for specific NIC drivers), and hardware offload (program runs directly on the NIC). xdp-filter simplifies the complex process of loading, attaching, detaching, and inspecting the status and statistics of these powerful low-level network programs. It provides a user-friendly interface to leverage the benefits of XDP for high-performance networking tasks.

Using xdp-filter requires root privileges for attaching or detaching programs. The system must have a Linux kernel version that supports XDP (typically 4.8 or later for basic XDP, with continuous improvements in newer versions) and eBPF. Attaching programs in driver or offload modes requires specific NIC driver or hardware support, respectively; otherwise, only generic mode will work. Care must be taken when deploying XDP programs, as a faulty program can lead to network disruption or even kernel crashes if not properly developed and tested. Always ensure your eBPF program is well-tested and validated before deploying in a production environment.

XDP supports three primary modes:
1. Generic (SKB) Mode: The default software-based mode, which works on any network driver. It attaches the XDP program slightly later in the packet reception path, after the SKB (socket buffer) is allocated.
2. Driver Mode: This mode allows the XDP program to run earlier, directly within the network driver's receive path, for improved performance. It requires specific driver support.
3. Hardware Offload Mode: The most performant mode, where the XDP program is offloaded and executed directly by the network interface card (NIC) hardware. This requires a NIC with XDP offload capabilities. Choosing the correct mode is crucial for optimal performance and compatibility.

An eBPF program for XDP is typically written in C, compiled into an ELF object file (.o) using a compiler like clang with the BPF backend. This object file contains the BPF bytecode and metadata, which xdp-filter then loads into the kernel. The program's entry point function, usually named xdp_filter, receives a pointer to an xdp_md (XDP metadata) struct and returns an XDP action code (e.g., XDP_PASS to allow, XDP_DROP to discard, XDP_REDIRECT to redirect to another interface, or XDP_TX to transmit back on the same interface). BPF maps are often used by these programs for persistent storage and to communicate with userspace.

The development of XDP and its associated tools like xdp-filter is closely tied to the evolution of eBPF in the Linux kernel. XDP was initially introduced around Linux kernel 4.8 to provide a high-performance, programmable data path for network processing. xdp-filter emerged as part of the broader effort to make eBPF and XDP more accessible to users. It leverages the libbpf library, which simplifies the loading and management of eBPF programs. Over time, as eBPF capabilities expanded and XDP gained wider adoption for use cases such as next-generation firewalls and load balancers, xdp-filter became a standard utility for interacting with XDP programs, often found within the iproute2 or similar network utility packages.

ip(8), bpftool(8), tc(8), bpf(2)