1xdp-loader(8)                 XDP program loader                 xdp-loader(8)
2
3
4

NAME

6       xdp-loader - an XDP program loader
7

SYNOPSIS

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
15
16   Running xdp-loader
17       The syntax for running xdp-loader is:
18
19              xdp-loader COMMAND [options]
20
21              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
29
30       Each  command,  and  its options are explained below. Or use xdp-loader
31       COMMAND --help to see the options for each command.
32
33

The LOAD command

35       The load command loads one or more XDP programs onto an interface.
36
37
38       The syntax for the load command is:
39
40
41       xdp-loader load [options] <ifname> <programs>
42
43
44       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
49
50       The supported options are:
51
52
53   -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
66
67   -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
75
76   -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
81
82   -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
88
89   -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
96
97   -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
105
106   -v, --verbose
107       Enable debug logging. Specify twice for even more verbosity.
108
109
110   -h, --help
111       Display a summary of the available options
112
113

The UNLOAD command

115       The unload command is used for unloading programs from an interface.
116
117
118       The syntax for the unload command is:
119
120
121       xdp-loader unload [options] <ifname>
122
123
124       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
128
129       The supported options are:
130
131
132   -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
138
139   -a, --all
140       Unload  all XDP programs on the interface, as well as the multi-program
141       dispatcher.
142
143
144   -v, --verbose
145       Enable debug logging. Specify twice for even more verbosity.
146
147
148   -h, --help
149       Display a summary of the available options
150
151

The STATUS command

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
159
160   -v, --verbose
161       Enable debug logging. Specify twice for even more verbosity.
162
163
164   -h, --help
165       Display a summary of the available options
166
167

The FEATURES command

169       The features command displays the XDP features supported by the NIC.
170
171
172       Currently supported XDP features are:
173
174
175   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
180
181   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
185
186   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
190
191   NETDEV_XDP_ACT_XSK_ZEROCOPY
192       The networking device supports AF_XDP in zero copy mode.
193
194
195   NETDEV_XDP_ACT_HW_OFFLOAD
196       The networking device supports XDP hw offloading.
197
198
199   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
204
205   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
209

The CLEAN command

211       The syntax for the clean command is:
212
213
214       xdp-loader clean [options] [ifname]
215
216
217       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
225
226       The supported options are:
227
228
229   -v, --verbose
230       Enable debug logging. Specify twice for even more verbosity.
231
232
233   -h, --help
234       Display a summary of the available options
235
236

Examples

238       To load an XDP program on the eth0 interface simply do:
239
240              # xdp-loader load eth0 xdp_drop.o
241              # xdp-loader status
242
243              CURRENT XDP PROGRAM STATUS:
244
245              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
251
252
253       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
259
260       To  use  the  automatic map pinning, include the pinning attribute into
261       the map definition in the program, something like:
262
263              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
271
272       And load it with the --pin-path attribute:
273
274              # xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
275
276
277       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
281

SEE ALSO

283       libxdp(3) for details on the XDP loading semantics and kernel  compati‐
284       bility requirements.
285
286

BUGS

288       Please  report  any bugs on Github: https://github.com/xdp-project/xdp-
289       tools/issues
290
291

AUTHOR

293       xdp-loader and this man page were written by Toke Høiland-Jørgensen.
294
295
296
297V1.4.1                         OCTOBER 20, 2023                  xdp-loader(8)
Impressum