xdp-filter.8

.TH "xdp-filter" "8" "SEPTEMBER  5, 2022" "V1.4.3" "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] <ifname>\fP

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

.SS "-m, --mode <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 <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 <feats>"
.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] <ifname>\fP

.PP
Where \fI<ifname>\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<ifname>\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] <port>\fP

.PP
Where \fI<port>\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 <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 <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] <ip>\fP

.PP
Where \fI<ip>\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 <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] <addr>\fP

.PP
Where \fI<addr>\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 <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 <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.