#+EXPORT_FILE_NAME: xdp-filter #+TITLE: xdp-filter #+MAN_CLASS_OPTIONS: :section-id "8\" \"DATE\" \"VERSION\" \"A simple XDP-powered packet filter" # This file serves both as a README on github, and as the source for the man # page; the latter through the org-mode man page export support. # . # To export the man page, simply use the org-mode exporter; (require 'ox-man) if # it's not available. There's also a Makefile rule to export it. * XDP-filter - a simple XDP-powered packet filter 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: #+begin_src sh 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 #+end_src 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] = Where == is the name of the interface to load =xdp-filter= onto, and must be specified. The supported options are: ** -m, --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 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 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] = Where == 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 == 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] = Where == 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 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 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] = Where == 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 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] = Where == 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 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 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: #+begin_src sh # xdp-filter load eth0 -f tcp,udp # xdp-filter port 80 #+end_src 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!): #+begin_src sh # xdp-filter load eth0 -f ipv6 -w # xdp-filter ip fc00:dead:cafe::1 -m src #+end_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!): #+begin_src sh # xdp-filter load eth0 -f ipv6,tcp -w # xdp-filter port 22 # xdp-filter ip fc00:dead:cafe::1 -m src #+end_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.