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 clean - clean up detached program links in XDP bpffs directory
26 help - show the list of available commands
27 Each command, and its options are explained below. Or use xdp-loader
30 COMMAND --help to see the options for each command.
31
34 The load command loads one or more XDP programs onto an interface.
35 The syntax for the load command is:
38 xdp-loader load [options] <ifname> <programs>
41 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 The supported options are:
50 -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 -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 -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 -v, --verbose
80 Enable debug logging. Specify twice for even more verbosity.
81 -h, --help
84 Display a summary of the available options
85
88 The unload command is used for unloading programs from an interface.
89 The syntax for the unload command is:
92 xdp-loader unload [options] <ifname>
95 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 The supported options are:
103 -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 -a, --all
113 Unload all XDP programs on the interface, as well as the multi-program
114 dispatcher.
115 -v, --verbose
118 Enable debug logging. Specify twice for even more verbosity.
119 -h, --help
122 Display a summary of the available options
123
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 -v, --verbose
134 Enable debug logging. Specify twice for even more verbosity.
135 -h, --help
138 Display a summary of the available options
139
142 The syntax for the clean command is:
143 xdp-loader clean [options] [ifname]
146 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 The supported options are:
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 To load an XDP program on the eth0 interface simply do:
170 # xdp-loader load eth0 xdp_drop.o
172 # xdp-loader status
173 CURRENT XDP PROGRAM STATUS:
175 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 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 To use the automatic map pinning, include the pinning attribute into
192 the map definition in the program, something like:
193 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 And load it with the --pin-path attribute:
204 # xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
206 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
214 libxdp(3) for details on the XDP loading semantics and kernel compati‐
215 bility requirements.
216
219 Please report any bugs on Github: https://github.com/xdp-project/xdp-
220 tools/issues
221
224 xdp-loader and this man page were written by Toke Høiland-Jørgensen.
225V1.2.6 AUGUST 16, 2022 xdp-loader(8)