.TH "xdp-filter" "8" "SEPTEMBER 5, 2022" "V1.4.0" "A simple XDP-powered packet filter" .SH "NAME" xdp-filter \- a simple XDP-powered packet filter .SH "SYNOPSIS" .PP 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. .SS "Running xdp-filter" .PP The syntax for running xdp-filter is: .RS .nf \fCxdp-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 \fP .fi .RE .PP Each command, and its options are explained below. Or use \fIxdp\-filter COMMAND \-\-help\fP to see the options for each command. .SH "The LOAD command" .PP To use \fIxdp\-filter\fP, it must first be loaded onto an interface. This is accomplished with the \fIload\fP 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. .PP The syntax for the \fIload\fP command is: .PP \fIxdp\-filter load [options] \fP .PP Where \fI\fP is the name of the interface to load \fIxdp\-filter\fP onto, and must be specified. The supported options are: .SS "-m, --mode " .PP 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 \fIskb mode\fP (also known as \fIgeneric XDP\fP) to be used, or 'hw' which causes the program to be offloaded to the hardware. .SS "-p, --policy " .PP This sets the policy \fIxdp\-filter\fP applies to packets \fBnot\fP matched by any of the filter rules. The default is \fIallow\fP, in which packets not matching any rules are allowed to pass. The other option is \fIdeny\fP, in which \fBall\fP packets are dropped \fBexcept\fP those matched by the filter options. .PP \fIxdp\-filter\fP cannot be loaded simultaneously in \fIdeny\fP and \fIallow\fP policy modes on the system. Note that loading \fIxdp\-filter\fP in \fIdeny\fP 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. .SS "-f, --features " .PP Use this option to select which features to include when loaded \fIxdp\-filter\fP. The default is to load all available features. So select individual features specify one or more of these: .IP \(bu 4 \fBtcp\fP: Support filtering on TCP port number .IP \(bu 4 \fBudp\fP: Support filtering on UDP port number .IP \(bu 4 \fBipv6\fP: Support filtering on IPv6 addresses .IP \(bu 4 \fBipv4\fP: Support filtering on IPv4 addresses .IP \(bu 4 \fBethernet\fP: Support filtering on Ethernet MAC addresses .PP Specify multiple features by separating them with a comma. E.g.: \fItcp,udp,ipv6\fP. .SS "-v, --verbose" .PP Enable debug logging. Specify twice for even more verbosity. .SS "-h, --help" .PP Display a summary of the available options .SH "The UNLOAD command" .PP The \fIunload\fP command unloads \fIxdp\-filter\fP from one (or all) interfaces, and cleans up the program state. .PP The syntax for the \fIload\fP command is: .PP \fIxdp\-filter unload [options] \fP .PP Where \fI\fP is the name of the interface to unload \fIxdp\-filter\fP from, and must be specified unless the \fB--all\fP option is used. The supported options are: .SS "-a, --all" .PP Specify this option to remove \fIxdp\-filter\fP from all interfaces it was loaded onto. If this option is specified, no \fI\fP is needed. .PP This option can also be used to clean up all \fIxdp\-filter\fP state if the XDP program(s) were unloaded by other means. .SS "-k, --keep-maps" .PP Specify this option to prevent \fIxdp\-filter\fP 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 \fIxdp\-filter\fP is loaded again. .SS "-v, --verbose" .PP Enable debug logging. Specify twice for even more verbosity. .SS "-h, --help" .PP Display a summary of the available options .SH "The PORT command" .PP Use the \fIport\fP command to add a TCP or UDP port to the \fIxdp\-filter\fP match list. For this to work, \fIxdp\-filter\fP must be loaded with either the \fBudp\fP or the \fBtcp\fP feature (or both) on at least one interface. .PP The syntax for the \fIport\fP command is: .PP \fIxdp\-filter port [options] \fP .PP Where \fI\fP is the port number to add (or remove if the \fB--remove\fP is specified). The supported options are: .SS "-r, --remove" .PP Remove the port instead of adding it. .SS "-m, --mode " .PP Select filtering mode. Valid options are \fBsrc\fP and \fBdst\fP, both of which may be specified as \fIsrc,dst\fP. If \fBsrc\fP is specified, the port number will added as a \fIsource port\fP match, while if \fBdst\fP is specified, the port number will be added as a \fIdestination port\fP match. If both are specified, a packet will be matched if \fBeither\fP its source or destination port is the specified port number. .SS "-p, --proto " .PP Specify one (or both) of \fBudp\fP and/or \fBtcp\fP to match UDP or TCP ports, respectively. .SS "-s, --status" .PP If this option is specified, the current list of matched ports will be printed after inserting the port number. Otherwise, nothing will be printed. .SS "-v, --verbose" .PP Enable debug logging. Specify twice for even more verbosity. .SS "-h, --help" .PP Display a summary of the available options .SH "The IP command" .PP Use the \fIip\fP command to add an IPv6 or an IPv4 address to the \fIxdp\-filter\fP match list. .PP The syntax for the \fIip\fP command is: .PP \fIxdp\-filter ip [options] \fP .PP Where \fI\fP is the IP address to add (or remove if the \fB--remove\fP is specified). Either IPv4 or IPv6 addresses can be specified, but \fIxdp\-filter\fP must be loaded with the corresponding features (\fBipv4\fP and \fBipv6\fP, respectively). The supported options are: .SS "-r, --remove" .PP Remove the IP address instead of adding it. .SS "-m, --mode " .PP Select filtering mode. Valid options are \fBsrc\fP and \fBdst\fP, both of which may be specified as \fIsrc,dst\fP. If \fBsrc\fP is specified, the IP address will added as a \fIsource IP\fP match, while if \fBdst\fP is specified, the IP address will be added as a \fIdestination IP\fP match. If both are specified, a packet will be matched if \fBeither\fP its source or destination IP is the specified IP address. .SS "-s, --status" .PP If this option is specified, the current list of matched ips will be printed after inserting the IP address. Otherwise, nothing will be printed. .SS "-v, --verbose" .PP Enable debug logging. Specify twice for even more verbosity. .SS "-h, --help" .PP Display a summary of the available options .SH "The ETHER command" .PP Use the \fIether\fP command to add an Ethernet MAC address to the \fIxdp\-filter\fP match list. For this to work, \fIxdp\-filter\fP must be loaded with either the \fBethernet\fP feature on at least one interface. .PP The syntax for the \fIether\fP command is: .PP \fIxdp\-filter ether [options] \fP .PP Where \fI\fP is the MAC address to add (or remove if the \fB--remove\fP is specified). The supported options are: .SS "-r, --remove" .PP Remove the MAC address instead of adding it. .SS "-m, --mode " .PP Select filtering mode. Valid options are \fBsrc\fP and \fBdst\fP, both of which may be specified as \fIsrc,dst\fP. If \fBsrc\fP is specified, the MAC address will added as a \fIsource MAC\fP match, while if \fBdst\fP is specified, the MAC address will be added as a \fIdestination MAC\fP match. If both are specified, a packet will be matched if \fBeither\fP its source or destination MAC is the specified MAC address. .SS "-s, --status" .PP If this option is specified, the current list of matched ips will be printed after inserting the MAC address. Otherwise, nothing will be printed. .SS "-v, --verbose" .PP Enable debug logging. Specify twice for even more verbosity. .SS "-h, --help" .PP Display a summary of the available options .SH "The STATUS command" .PP The \fIstatus\fP command prints the current status of \fIxdp\-filter\fP: 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. .PP The syntax for the \fIstatus\fP command is: .PP \fIxdp\-filter status [options]\fP .PP Where the supported options are: .SS "-v, --verbose" .PP Enable debug logging. Specify twice for even more verbosity. .SS "-h, --help" .PP Display a summary of the available options .SH "The POLL command" .PP The \fIpoll\fP command periodically polls the \fIxdp\-filter\fP statistics map and prints out the total number of packets and bytes processed by \fIxdp\-filter\fP, 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 \fIxdp\-filter\fP, and to compare the performance of the different feature sets selectable by the \fIload\fP parameter. .PP The syntax for the \fIpoll\fP command is: .PP \fIxdp\-filter poll [options]\fP .PP Where the supported options are: .SS "-i, --interval " .PP The polling interval, in milliseconds. Defaults to 1000 (1 second). .SS "-v, --verbose" .PP Enable debug logging. Specify twice for even more verbosity. .SS "-h, --help" .PP Display a summary of the available options .SH "Examples" .PP To filter all packets arriving on port 80 on eth0, issue the following commands: .RS .nf \fC# xdp-filter load eth0 -f tcp,udp # xdp-filter port 80 \fP .fi .RE .PP To filter all packets \fBexcept\fP those from IP address fc00:dead:cafe::1 issue the following commands (careful, this can lock you out of remote access!): .RS .nf \fC# xdp-filter load eth0 -f ipv6 -p deny # xdp-filter ip fc00:dead:cafe::1 -m src \fP .fi .RE .PP To allow packets from \fBeither\fP IP fc00:dead:cafe::1 \fBor\fP arriving on port 22, issue the following (careful, this can lock you out of remote access!): .RS .nf \fC# xdp-filter load eth0 -f ipv6,tcp -p deny # xdp-filter port 22 # xdp-filter ip fc00:dead:cafe::1 -m src \fP .fi .RE .SH "BUGS" .PP Please report any bugs on Github: \fIhttps://github.com/xdp-project/xdp-tools/issues\fP .SH "AUTHOR" .PP 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.