xdp-filter(8)

📦
version 1.6.3 · 13 versions
, in arch rolling, ubuntu stonking

💖 NAME 💖

okay so bestie, meet xdp-filter — a simple XDP-powered packet filter ✨ it's the manual page xdp-filter(8), and it's exactly what it says on the tin: an XDP-powered utility for filtering packets, no drama, no nonsense 💅

🦋 SYNOPSIS 🦋

XDP-filter is a packet filtering utility powered by XDP. And the whole point of it? It is deliberately simple — which means nope, it does not have the same matching capabilities as, like, netfilter. But here's the trade-off that makes it iconic: thanks to XDP, it can achieve very high drop rates — literally tens of millions of packets per second on a single CPU core 🔥 one (1) core. periodt.

✨ Running xdp-filter ✨

The syntax for running xdp-filter is:

xdp-filter COMMAND [options]

Where COMMAND can be one of:

  • load — load xdp-filter on an interface
  • unload — unload xdp-filter from an interface
  • port — add a port to the filter list
  • ip — add an IP address to the filter list
  • ether — add an Ethernet MAC address to the filter list
  • status — show current xdp-filter status
  • poll — poll statistics output
  • help — show the list of available commands

Each command, and its options are explained below. Or use xdp-filter COMMAND --help to see the options for each command 🫶 no gatekeeping here.

👑 The LOAD command 👑

To use xdp-filter, it must first be loaded onto an interface — like, it can't filter anything while it's just vibing in your shell. This is accomplished with the load command, which takes the name of the interface as a parameter, and optionally allows specifying the features that should be included. By default all features are loaded, but de-selecting some features can speed up the packet matching, and increase performance by a substantial amount 📈 so being picky is genuinely a flex.

The syntax for the load command is:

xdp-filter load [options] <ifname>

Where <ifname> is the name of the interface to load xdp-filter onto, and must be specified. The supported options are:

  • -m, --mode <mode> — specifies which mode to load the XDP program to be loaded in. The valid values are native, which is the default in-driver XDP mode, skb, which causes the so-called skb mode (also known as generic XDP) to be used, or hw which causes the program to be offloaded to the hardware 🦋
  • -p, --policy <policy> — this sets the policy xdp-filter applies to packets not matched by any of the filter rules. The default is allow, in which packets not matching any rules are allowed to pass. The other option is deny, in which all packets are dropped except those matched by the filter options 💀

xdp-filter cannot be loaded simultaneously in deny and allow policy modes on the system. Note that loading xdp-filter in deny mode will drop all traffic on the interface until suitable allow rules are installed, so some care is needed to avoid being locked out of a remote system.

🚨 bestie I mean this SO seriously: deny mode drops everything until you install the allow rules you actually want. if you're on a remote box and you fumble this, you're not coming back. no cap.
  • -f, --features <feats> — use this option to select which features to include when loaded xdp-filter. The default is to load all available features. So select individual features specify one or more of these:
    • tcp: Support filtering on TCP port number
    • udp: Support filtering on UDP port number
    • ipv6: Support filtering on IPv6 addresses
    • ipv4: Support filtering on IPv4 addresses
    • ethernet: Support filtering on Ethernet MAC addresses

Specify multiple features by separating them with a comma. E.g.: tcp,udp,ipv6.

  • -v, --verbose — enable debug logging. Specify twice for even more verbosity 🔍
  • -h, --help — display a summary of the available options

🧚 The UNLOAD command 🧚

The unload command unloads xdp-filter from one (or all) interfaces, and cleans up the program state 🧹 closure, but make it networking.

(yes, the original page says "load" right here — it's a typo, we're very clearly talking about unload, and I'm keeping the receipts for you.)

The syntax for the unload command is:

xdp-filter unload [options] <ifname>

Where <ifname> is the name of the interface to unload xdp-filter from, and must be specified unless the --all option is used. The supported options are:

  • -a, --all — specify this option to remove xdp-filter from all interfaces it was loaded onto. If this option is specified, no <ifname> is needed 👍

This option can also be used to clean up all xdp-filter state if the XDP program(s) were unloaded by other means.

  • -k, --keep-maps — specify this option to prevent xdp-filter from clearing its map state. By default, all BPF maps no longer needed by any loaded program are removed. However, this will also remove the contents of the maps (the filtering rules), so this option can be used to keep the maps around so the rules persist until xdp-filter is loaded again 🫶
  • -v, --verbose — enable debug logging. Specify twice for even more verbosity 🔍
  • -h, --help — display a summary of the available options

🌸 The PORT command 🌸

Use the port command to add a TCP or UDP port to the xdp-filter match list. For this to work, xdp-filter must be loaded with either the udp or the tcp feature (or both) on at least one interface ⚠️ otherwise it's just shouting into the void.

The syntax for the port command is:

xdp-filter port [options] <port>

Where <port> is the port number to add (or remove if the --remove is specified). The supported options are:

  • -r, --remove — remove the port instead of adding it.
  • -m, --mode <mode> — select filtering mode. Valid options are src and dst, both of which may be specified as src,dst. If src is specified, the port number will added as a source port match, while if dst is specified, the port number will be added as a destination port match. If both are specified, a packet will be matched if either its source or destination port is the specified port number ✨
  • -p, --proto <proto> — specify one (or both) of udp and/or tcp to match UDP or TCP ports, respectively.
  • -s, --status — if this option is specified, the current list of matched ports will be printed after inserting the port number. Otherwise, nothing will be printed 🤫
  • -v, --verbose — enable debug logging. Specify twice for even more verbosity 🔍
  • -h, --help — display a summary of the available options

🎀 The IP command 🎀

Use the ip command to add an IPv6 or an IPv4 address to the xdp-filter match list.

The syntax for the ip command is:

xdp-filter ip [options] <ip>

Where <ip> is the IP address to add (or remove if the --remove is specified). Either IPv4 or IPv6 addresses can be specified, but xdp-filter must be loaded with the corresponding features (ipv4 and ipv6, respectively) 👑 The supported options are:

  • -r, --remove — remove the IP address instead of adding it.
  • -m, --mode <mode> — select filtering mode. Valid options are src and dst, both of which may be specified as src,dst. If src is specified, the IP address will added as a source IP match, while if dst is specified, the IP address will be added as a destination IP match. If both are specified, a packet will be matched if either its source or destination IP is the specified IP address 💅
  • -s, --status — if this option is specified, the current list of matched ips will be printed after inserting the IP address. Otherwise, nothing will be printed 🤫
  • -v, --verbose — enable debug logging. Specify twice for even more verbosity 🔍
  • -h, --help — display a summary of the available options

🌈 The ETHER command 🌈

Use the ether command to add an Ethernet MAC address to the xdp-filter match list. For this to work, xdp-filter must be loaded with either the ethernet feature on at least one interface ⚠️

The syntax for the ether command is:

xdp-filter ether [options] <addr>

Where <addr> is the MAC address to add (or remove if the --remove is specified). The supported options are:

  • -r, --remove — remove the MAC address instead of adding it.
  • -m, --mode <mode> — select filtering mode. Valid options are src and dst, both of which may be specified as src,dst. If src is specified, the MAC address will added as a source MAC match, while if dst is specified, the MAC address will be added as a destination MAC match. If both are specified, a packet will be matched if either its source or destination MAC is the specified MAC address 🦋
  • -s, --status — if this option is specified, the current list of matched ips will be printed after inserting the MAC address. Otherwise, nothing will be printed 🤫 (yep, the original text says "ips" here even though we're doing MACs — keeping the lore intact, bestie)
  • -v, --verbose — enable debug logging. Specify twice for even more verbosity 🔍
  • -h, --help — display a summary of the available options

⭐ The STATUS command ⭐

The status command prints the current status of xdp-filter: which interfaces it is loaded on, the current list of rules, and some statistics for how many packets have been processed in total, and how many times each rule has been hit 📊 it's giving main character energy for your ruleset.

The syntax for the status command is:

xdp-filter status [options]

Where the supported options are:

  • -v, --verbose — enable debug logging. Specify twice for even more verbosity 🔍
  • -h, --help — display a summary of the available options

🍓 The POLL command 🍓

The poll command periodically polls the xdp-filter statistics map and prints out the total number of packets and bytes processed by xdp-filter, as well as the number in the last polling interval, converted to packets (and bytes) per second ⏱️ This can be used to inspect the performance of xdp-filter, and to compare the performance of the different feature sets selectable by the load parameter 🔥

The syntax for the poll command is:

xdp-filter poll [options]

Where the supported options are:

  • -i, --interval <interval> — the polling interval, in milliseconds. Defaults to 1000 (1 second).
  • -v, --verbose — enable debug logging. Specify twice for even more verbosity 🔍
  • -h, --help — display a summary of the available options

💜 Examples 💜

To filter all packets arriving on port 80 on eth0, issue the following commands:

# xdp-filter load eth0 -f tcp,udp
# xdp-filter port 80

To filter all packets except those from IP address fc00:dead:cafe::1 issue the following commands (careful, this can lock you out of remote access!):

# xdp-filter load eth0 -f ipv6 -p deny
# xdp-filter ip fc00:dead:cafe::1 -m src

To allow packets from either IP fc00:dead:cafe::1 or arriving on port 22, issue the following (careful, this can lock you out of remote access!):

# xdp-filter load eth0 -f ipv6,tcp -p deny
# xdp-filter port 22
# xdp-filter ip fc00:dead:cafe::1 -m src
😭 bestie, see those two "(careful, this can lock you out of remote access!)" notes? they are NOT decorative. -p deny means everything gets dropped until your allow rules land. respect the deny.

💀 BUGS 💀

Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues

(they want your bug reports, fr fr — don't suffer in silence 🙈)

🫶 AUTHOR 🫶

xdp-filter was written by Toke Høiland-Jørgensen and Jesper Dangaard Brouer. This man page was written by Toke Høiland-Jørgensen. legends only 👑

and that's the whole page, bestie 💖 this was xdp-filter V1.6.3, dated SEPTEMBER 5, 2022 🌸 go forth and drop packets at tens of millions per second on a single CPU core ✨

📦 where this page comes from