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                     clean       - clean up detached program links in XDP bpffs directory
26                     help        - show the list of available commands
27
28
29       Each  command,  and  its options are explained below. Or use xdp-loader
30       COMMAND --help to see the options for each command.
31
32

The LOAD command

34       The load command loads one or more XDP programs onto an interface.
35
36
37       The syntax for the load command is:
38
39
40       xdp-loader load [options] <ifname> <programs>
41
42
43       Where <ifname> is the name of the interface to load the programs  onto,
44       and  the  <programs> is one or more file names containing XDP programs.
45       The programs will be loaded onto the interface in the  order  of  their
46       preference, as specified by the program metadata (see libxdp(3)).
47
48
49       The supported options are:
50
51
52   -m, --mode <mode>
53       Specifies which mode to load the XDP program to be loaded in. The valid
54       values are 'native', which is the default in-driver  XDP  mode,  'skb',
55       which  causes  the so-called skb mode (also known as generic XDP) to be
56       used, 'hw' which causes the program to be offloaded to the hardware, or
57       'unspecified' which leaves it up to the kernel to pick a mode (which it
58       will do by picking native mode if the driver supports  it,  or  generic
59       mode otherwise). Note that using 'unspecified' can make it difficult to
60       predict what mode a program will end up being loaded in. For this  rea‐
61       son, the default is 'native'.
62
63
64   -p, --pin-path <path>
65       This  specifies a root path under which to pin any maps that define the
66       'pinning' attribute in their definitions. This path must be located  on
67       a  bpffs file system. If not set, maps will not be pinned, even if they
68       specify pinning in their definitions. When pinning maps, if the  pinned
69       location  for  a map already exist, the map pinned there will be reused
70       if it is compatible with the type of the map being loaded.
71
72
73   -s, --section <section>
74       Specify which ELF section to load the XDP program(s) from in each file.
75       The default is to use the first program in each file. If this option is
76       set, it applies to all programs being loaded.
77
78
79   -v, --verbose
80       Enable debug logging. Specify twice for even more verbosity.
81
82
83   -h, --help
84       Display a summary of the available options
85
86

The UNLOAD command

88       The unload command is used for unloading programs from an interface.
89
90
91       The syntax for the unload command is:
92
93
94       xdp-loader unload [options] <ifname>
95
96
97       Where <ifname> is the name of the interface to load the programs  onto.
98       Either  the  --all  or  --id options must be used to specify which pro‐
99       gram(s) to unload.
100
101
102       The supported options are:
103
104
105   -i, --id <id>
106       Unload a single program from the interface by ID. Use xdp-loader status
107       to  obtain the ID of the program being unloaded. If this program is the
108       last program loaded on the interface, the dispatcher program will  also
109       be removed, which makes the operation equivalent to specifying --all.
110
111
112   -a, --all
113       Unload  all XDP programs on the interface, as well as the multi-program
114       dispatcher.
115
116
117   -v, --verbose
118       Enable debug logging. Specify twice for even more verbosity.
119
120
121   -h, --help
122       Display a summary of the available options
123
124

The STATUS command

126       The status command displays a list of interfaces in the system, and the
127       XDP  program(s) loaded on each interface. For each interface, a list of
128       programs are shown, with the run priority and "chain actions" for  each
129       program.  See  the  section on program metadata for the meaning of this
130       metadata.
131
132
133   -v, --verbose
134       Enable debug logging. Specify twice for even more verbosity.
135
136
137   -h, --help
138       Display a summary of the available options
139
140

The CLEAN command

142       The syntax for the clean command is:
143
144
145       xdp-loader clean [options] [ifname]
146
147
148       The clean command cleans up any detached program links in the XDP bpffs
149       directory.  When a network interface disappears, any programs loaded in
150       software mode (e.g. skb, native) remain pinned in the bpffs  directory,
151       but  become detached from the interface. These need to be unlinked from
152       the filesystem. The clean command takes an optional interface parameter
153       to  only  unlink  detached programs corresponding to the interface.  By
154       default, all detached programs for all interfaces are unlinked.
155
156
157       The supported options are:
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

Examples

169       To load an XDP program on the eth0 interface simply do:
170
171              # xdp-loader load eth0 xdp_drop.o
172              # xdp-loader status
173
174              CURRENT XDP PROGRAM STATUS:
175
176              Interface        Prio  Program name     Mode     ID   Tag               Chain actions
177              -------------------------------------------------------------------------------------
178              lo               <no XDP program>
179              eth0                   xdp_dispatcher   native   50   d51e469e988d81da
180               =>              50    xdp_drop                  55   57cd311f2e27366b  XDP_PASS
181
182
183
184       Which shows that a dispatcher program was loaded on the interface,  and
185       the  xdp_drop  program  was installed as the first (and only) component
186       program after it. In this instance, the program does not specify any of
187       the  metadata  above,  so the defaults (priority 50 and XDP_PASS as its
188       chain call action) was used.
189
190
191       To use the automatic map pinning, include the  pinning  attribute  into
192       the map definition in the program, something like:
193
194              struct {
195                   __uint(type, BPF_MAP_TYPE_ARRAY);
196                   __uint(max_entries, 10);
197                   __type(key, __u32);
198                   __type(value, __u64);
199                   __uint(pinning, LIBBPF_PIN_BY_NAME);
200              } my_map SEC(".maps");
201
202
203       And load it with the --pin-path attribute:
204
205              # xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
206
207
208       This  will  pin  the map at /sys/fs/bpf/my-prog/my_map. If this already
209       exists, the pinned map will be reused instead of creating  a  new  one,
210       which allows different BPF programs to share the map.
211
212

SEE ALSO

214       libxdp(3)  for details on the XDP loading semantics and kernel compati‐
215       bility requirements.
216
217

BUGS

219       Please report any bugs on  Github:  https://github.com/xdp-project/xdp-
220       tools/issues
221
222

AUTHOR

224       xdp-loader and this man page were written by Toke Høiland-Jørgensen.
225
226
227
228V1.2.6                          AUGUST 16, 2022                  xdp-loader(8)
Impressum