xdp-forward.8

.TH "xdp-forward" "8" "OCTOBER 11, 2024" "V1.5.1" "XDP program loader"

.SH "NAME"
xdp-forward \- the XDP forwarding plane
.SH "SYNOPSIS"
.PP
xdp-forward is an XDP forwarding plane, which will accelerate packet forwarding
using XDP. To use it, simply load it on the set of interfaces to accelerate
forwarding between. The userspace component of xdp-forward will then configure
and load XDP programs on those interfaces, and forward packets between them
using XDP_REDIRECT, using the kernel routing table or netfilter flowtable to
determine the destination for each packet.

.PP
Any packets that xdp-forward does not know how to forward will be passed up to
the networking stack and handled by the kernel like normal. Depending on the
mode xdp-forward is loaded in, this leads to different forwarding behaviours.
See the sectinon on \fBOperating modes\fP below.

.SS "Running xdp-forward"
.PP
The syntax for running xdp-forward is:

.RS
.nf
\fCxdp-forward COMMAND [options]

Where COMMAND can be one of:
       load        - Load the XDP forwarding plane
       unload      - Unload the XDP forwarding plane
       help        - show the list of available commands
\fP
.fi
.RE

.PP
Each command, and its options are explained below. Or use \fIxdp\-forward COMMAND
\-\-help\fP to see the options for each command.

.SH "The LOAD command"
.PP
The \fIload\fP command loads the XDP forwarding plane on a list of interfaces.

.PP
The syntax for the \fIload\fP command is:

.PP
\fIxdp\-forward load [options] <ifname...>\fP

.PP
Where \fI<ifname...>\fP is the name of the set of interfaces to forward packets
between. An XDP program will be loaded on each interface, configured to forward
packets to all other interfaces in the set (using the kernel routing table to
determine the destination interface of each packet).

.PP
The supported options are:

.SS "-f, --fwd-mode <mode>"
.PP
Specifies which forwarding mode \fIxdp\-forward\fP should operate in. Depending on
the mode selected, \fIxdp\-forward\fP will perform forwarding in different ways,
which can lead to different behaviour, including which subset of kernel
configuration (such as firewall rules) is respected during forwarding. See the
section \fBFORWARDING MODES\fP below for a full description of each mode.

.SS "-F, --fib-mode <mode>"
.PP
Specifies how \fIxdp\-forward\fP performs routing table lookup in the linux kernel.
See the section \fBFIB MODES\fP below for a full description of each mode.

.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, 'hw' which causes
the program to be offloaded to the hardware, or 'unspecified' which leaves it up
to the kernel to pick a mode (which it will do by picking native mode if the
driver supports it, or generic mode otherwise). Note that using 'unspecified'
can make it difficult to predict what mode a program will end up being loaded
in. For this reason, the default is 'native'. Note that hardware with support
for the 'hw' mode is rare: Solarflare cards (using the 'sfc' driver) are the
only devices with support for this in the mainline Linux kernel.

.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 is used for unloading programs from an interface.

.PP
The syntax for the \fIunload\fP command is:

.PP
\fIxdp\-forward unload [options] <ifname...>\fP

.PP
Where \fI<ifname...>\fP is the list of interfaces to unload the XDP forwarding plane
from. Note that while \fIxdp\-forward\fP will examine the XDP programs loaded on each
interface and make sure to only unload its own program, it will not check that
the list of supplied interfaces is the same as the one supplied during load. As
such, it is possible to perform a partial unload by supplying a different list
of interfaces, which may lead to unexpected behaviour.

.PP
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 "FORWARDING MODES"
.PP
The \fIxdp\-forward\fP utility supports the following forwarding modes (selected by
the \fI\-\-fwd\-mode\fP parameter to \fIxdp\-forward load\fP.

.SS "fib (default)"
.PP
In the \fIfib\fP forwarding mode, \fIxdp\-forward\fP will perform a lookup in
the kernel routing table (or FIB) for each packet, and forward packets between
the configured interfaces based on the result of the lookup. Any packet where
the lookup fails will be passed up to the stack. This includes packets that
require neighbour discovery for the next hop, meaning that packets will
periodically pass up the kernel stack for next hop discovery (initially, and
when the nexthop entry expires).

.PP
Note that no checks other than the FIB lookup is performed; in particular, this
completely bypasses the netfilter subsystem, so firewall rules will not be
checked before forwarding.

.SS "flowtable"
.PP
The \fIflowtable\fP operating mode offloads netfilter sw flowtable logic in
the XDP layer if the hardware flowtable is not available.
At the moment \fIxdp\-forward\fP is able to offload just TCP or UDP netfilter
flowtable entries to XDP. The user is supposed to configure the flowtable
separately.

.SH "FIB MODES"
.PP
The \fIxdp\-forward\fP utility supports the following fib modes (selected by
the \fI\-\-fib\-mode\fP parameter to \fIxdp\-forward load\fP.

.SS "full (default)"
.PP
In the \fIfull\fP operating mode, \fIxdp\-forward\fP will perform a full lookup in
the kernel routing table (or FIB) for each packet, and forward packets between
the configured interfaces based on the result of the lookup. In particular,
it will apply any policy routing rules configured by the user.

.SS "direct"
.PP
The \fIdirect\fP mode functions like \fIfull\fP, except it passes the
\fIBPF_FIB_LOOKUP_DIRECT\fP flag to the FIB lookup routine. This means that any
policy routing rules configured will be skipped during the lookup, which can
improve performance (but won't obey the policy of those rules, obviously).

.SH "Examples"
.PP
In order to enable flowtable offloading for tcp and udp traffic between NICs
n0 and n1, issue the following commands:

.RS
.nf
\fC#nft -f /dev/stdin <<EOF
table inet filter {
    flowtable ft {
        hook ingress priority filter
        devices = { n0, n1 }
    }
    chain forward {
        type filter hook forward priority filter
        meta l4proto { tcp, udp } flow add @ft
    }
}
EOF

#xdp-forward load -f flowtable n0 n1
\fP
.fi
.RE

.SH "SEE ALSO"
.PP
\fIlibxdp(3)\fP for details on the XDP loading semantics and kernel compatibility
requirements.

.SH "BUGS"
.PP
Please report any bugs on Github: \fIhttps://github.com/xdp-project/xdp-tools/issues\fP

.SH "AUTHOR"
.PP
xdp-forward is written by Toke Høiland-Jørgensen, based on the xdp_fwd kernel
sample, which was originally written by David Ahern. This man page was written
by Toke Høiland-Jørgensen.