1xdp-loader(8) XDP program loader xdp-loader(8)
2
6 xdp-loader - an XDP program loader
7
9 XDP-loader is a simple loader for XDP programs with support for attach‐
10 ing multiple programs to the same interface. To achieve this it exposes
11 the same load and unload semantics exposed by the libxdp library. See
12 the libxdp(3) man page for details of how this works, and what kernel
13 features it relies on.
14 Running xdp-loader
17 The syntax for running xdp-loader is:
18 xdp-loader COMMAND [options]
20 Where COMMAND can be one of:
22 load - load an XDP program on an interface
23 unload - unload an XDP program from an interface
24 status - show current XDP program status
25 features - show XDP features supported by the NIC
26 clean - clean up detached program links in XDP bpffs directory
27 help - show the list of available commands
28 Each command, and its options are explained below. Or use xdp-loader
31 COMMAND --help to see the options for each command.
32
35 The load command loads one or more XDP programs onto an interface.
36 The syntax for the load command is:
39 xdp-loader load [options] <ifname> <programs>
42 Where <ifname> is the name of the interface to load the programs onto,
45 and the <programs> is one or more file names containing XDP programs.
46 The programs will be loaded onto the interface in the order of their
47 preference, as specified by the program metadata (see libxdp(3)).
48 The supported options are:
51 -m, --mode <mode>
54 Specifies which mode to load the XDP program to be loaded in. The valid
55 values are 'native', which is the default in-driver XDP mode, 'skb',
56 which causes the so-called skb mode (also known as generic XDP) to be
57 used, 'hw' which causes the program to be offloaded to the hardware, or
58 'unspecified' which leaves it up to the kernel to pick a mode (which it
59 will do by picking native mode if the driver supports it, or generic
60 mode otherwise). Note that using 'unspecified' can make it difficult to
61 predict what mode a program will end up being loaded in. For this rea‐
62 son, the default is 'native'. Note that hardware with support for the
63 'hw' mode is rare: Solarflare cards (using the 'sfc' driver) are the
64 only devices with support for this in the mainline Linux kernel.
65 -p, --pin-path <path>
68 This specifies a root path under which to pin any maps that define the
69 'pinning' attribute in their definitions. This path must be located on
70 a bpffs file system. If not set, maps will not be pinned, even if they
71 specify pinning in their definitions. When pinning maps, if the pinned
72 location for a map already exist, the map pinned there will be reused
73 if it is compatible with the type of the map being loaded.
74 -s, --section <section>
77 Specify which ELF section to load the XDP program(s) from in each file.
78 The default is to use the first program in each file. If this option is
79 set, it applies to all programs being loaded.
80 -n, --prog-name <prog_name>
83 Specify which BPF program with the name to load the XDP program(s) from
84 in each file. The default is to use the first program in each file.
85 Only one of --section and --prog-name may be specified. If this option
86 is set, it applies to all programs being loaded.
87 -P, --prio <priority>
90 Specify the priority to load the XDP program(s) with (this affects the
91 order of programs running on the interface). The default is to use the
92 value from the metadata in the program ELF file, or a value of 50 if
93 the program has no such metadata. If this option is set, it applies to
94 all programs being loaded.
95 -A, --actions <actions>
98 Specify the "chain call actions" of the loaded XDP program(s). These
99 are the XDP actions that will cause the next program loaded on the in‐
100 terface to be called, instead of returning immediately. The default is
101 to use the value set in the metadata in the program ELF file, or
102 XDP_PASS if no such metadata is set. If this option is set, it applies
103 to all programs being loaded.
104 -v, --verbose
107 Enable debug logging. Specify twice for even more verbosity.
108 -h, --help
111 Display a summary of the available options
112
115 The unload command is used for unloading programs from an interface.
116 The syntax for the unload command is:
119 xdp-loader unload [options] <ifname>
122 Where <ifname> is the name of the interface to load the programs onto.
125 Either the --all or --id options must be used to specify which pro‐
126 gram(s) to unload.
127 The supported options are:
130 -i, --id <id>
133 Unload a single program from the interface by ID. Use xdp-loader status
134 to obtain the ID of the program being unloaded. If this program is the
135 last program loaded on the interface, the dispatcher program will also
136 be removed, which makes the operation equivalent to specifying --all.
137 -a, --all
140 Unload all XDP programs on the interface, as well as the multi-program
141 dispatcher.
142 -v, --verbose
145 Enable debug logging. Specify twice for even more verbosity.
146 -h, --help
149 Display a summary of the available options
150
153 The status command displays a list of interfaces in the system, and the
154 XDP program(s) loaded on each interface. For each interface, a list of
155 programs are shown, with the run priority and "chain actions" for each
156 program. See the section on program metadata for the meaning of this
157 metadata.
158 -v, --verbose
161 Enable debug logging. Specify twice for even more verbosity.
162 -h, --help
165 Display a summary of the available options
166
169 The features command displays the XDP features supported by the NIC.
170 Currently supported XDP features are:
173 NETDEV_XDP_ACT_BASIC
176 The networking device has basic support for running XDP programs, and
177 can handle the base set of return codes (XDP_ABORTED, XDP_DROP,
178 XDP_PASS, XDP_TX).
179 NETDEV_XDP_ACT_REDIRECT
182 The network device supports handling the XDP_REDIRECT return code. This
183 means packets can be redirected from this device by XDP.
184 NETDEV_XDP_ACT_NDO_XMIT
187 The networking interfaces implements the ndo_xdp_xmit callback. This
188 means packets can be redirected to this device by XDP.
189 NETDEV_XDP_ACT_XSK_ZEROCOPY
192 The networking device supports AF_XDP in zero copy mode.
193 NETDEV_XDP_ACT_HW_OFFLOAD
196 The networking device supports XDP hw offloading.
197 NETDEV_XDP_ACT_RX_SG
200 The networking device supports non-linear XDP frames on the receive
201 side. This means XDP can be used with big MTUs on this device (if the
202 XDP program is compiled with fragments support)
203 NETDEV_XDP_ACT_NDO_XMIT_SG
206 The networking device supports non-linear XDP frames on the transmit
207 side. This means non-linear frames can be redirected to this device.
208
211 The syntax for the clean command is:
212 xdp-loader clean [options] [ifname]
215 The clean command cleans up any detached program links in the XDP bpffs
218 directory. When a network interface disappears, any programs loaded in
219 software mode (e.g. skb, native) remain pinned in the bpffs directory,
220 but become detached from the interface. These need to be unlinked from
221 the filesystem. The clean command takes an optional interface parameter
222 to only unlink detached programs corresponding to the interface. By
223 default, all detached programs for all interfaces are unlinked.
224 The supported options are:
227 -v, --verbose
230 Enable debug logging. Specify twice for even more verbosity.
231 -h, --help
234 Display a summary of the available options
235
238 To load an XDP program on the eth0 interface simply do:
239 # xdp-loader load eth0 xdp_drop.o
241 # xdp-loader status
242 CURRENT XDP PROGRAM STATUS:
244 Interface Prio Program name Mode ID Tag Chain actions
246 -------------------------------------------------------------------------------------
247 lo <no XDP program>
248 eth0 xdp_dispatcher native 50 d51e469e988d81da
249 => 50 xdp_drop 55 57cd311f2e27366b XDP_PASS
250 Which shows that a dispatcher program was loaded on the interface, and
254 the xdp_drop program was installed as the first (and only) component
255 program after it. In this instance, the program does not specify any of
256 the metadata above, so the defaults (priority 50 and XDP_PASS as its
257 chain call action) was used.
258 To use the automatic map pinning, include the pinning attribute into
261 the map definition in the program, something like:
262 struct {
264 __uint(type, BPF_MAP_TYPE_ARRAY);
265 __uint(max_entries, 10);
266 __type(key, __u32);
267 __type(value, __u64);
268 __uint(pinning, LIBBPF_PIN_BY_NAME);
269 } my_map SEC(".maps");
270 And load it with the --pin-path attribute:
273 # xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
275 This will pin the map at /sys/fs/bpf/my-prog/my_map. If this already
278 exists, the pinned map will be reused instead of creating a new one,
279 which allows different BPF programs to share the map.
280
283 libxdp(3) for details on the XDP loading semantics and kernel compati‐
284 bility requirements.
285
288 Please report any bugs on Github: https://github.com/xdp-project/xdp-
289 tools/issues
290
293 xdp-loader and this man page were written by Toke Høiland-Jørgensen.
294V1.4.1 OCTOBER 20, 2023 xdp-loader(8)