Scroll to navigation

xdp-filter(8) A simple XDP-powered packet filter xdp-filter(8)

NAME

xdp-filter - a simple XDP-powered packet filter

SYNOPSIS

XDP-filter is a packet filtering utility powered by XDP. It is deliberately simple and so does not have the same matching capabilities as, e.g., netfilter. Instead, thanks to XDP, it can achieve very high drop rates: tens of millions of packets per second on a single CPU core.

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.

The LOAD command

To use xdp-filter, it must first be loaded onto an interface. 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.

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.

-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.

The syntax for the load 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.

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.

-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.

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

BUGS

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

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.

September 5, 2022 V1.2.9