1xdp-loader(8) XDP program loader xdp-loader(8)
2
6 XDP-loader is a simple loader for XDP programs with support for attach‐
7 ing multiple programs to the same interface. To achieve this it exposes
8 the same load and unload semantics exposed by the libxdp library.
9 Running xdp-loader
13 The syntax for running xdp-loader is:
14 xdp-loader COMMAND [options]
16 Where COMMAND can be one of:
18 load - load an XDP program on an interface
19 unload - unload an XDP program from an interface
20 status - show current XDP program status
21 help - show the list of available commands
22 Each command, and its options are explained below. Or use xdp-loader
25 COMMAND --help to see the options for each command.
26
29 The load command loads one or more XDP programs onto an interface.
30 The syntax for the load command is:
33 xdp-loader load [options] <ifname> <programs>
36 Where <ifname> is the name of the interface to load the programs onto,
39 and the <programs> is one or more file names containing XDP programs.
40 The programs will be loaded onto the interface in the order of their
41 preference, as specified by the program metadata (see libxdp(3)).
42 The supported options are:
45 -m, --mode <mode>
48 Specifies which mode to load the XDP program to be loaded in. The valid
49 values are 'native', which is the default in-driver XDP mode, 'skb',
50 which causes the so-called skb mode (also known as generic XDP) to be
51 used, or 'hw' which causes the program to be offloaded to the hardware.
52 -p, --pin-path <path>
55 This specifies a root path under which to pin any maps that define the
56 'pinning' attribute in their definitions. This path must be located on
57 a bpffs file system. If not set, maps will not be pinned, even if they
58 specify pinning in their definitions. When pinning maps, if the pinned
59 location for a map already exist, the map pinned there will be reused
60 if it is compatible with the type of the map being loaded.
61 -s, --section <section>
64 Specify which ELF section to load the XDP program(s) from in each file.
65 The default is to use the first program in each file. If this option is
66 set, it applies to all programs being loaded.
67 -v, --verbose
70 Enable debug logging. Specify twice for even more verbosity.
71 -h, --help
74 Display a summary of the available options
75
78 The unload command is used for unloading programs from an interface.
79 The syntax for the unload command is:
82 xdp-loader unload [options] <ifname>
85 Where <ifname> is the name of the interface to load the programs onto.
88 Either the --all or --id options must be used to specify which pro‐
89 gram(s) to unload.
90 The supported options are:
93 -i, --id <id>
96 Unload a single program from the interface by ID. Use xdp-loader status
97 to obtain the ID of the program being unloaded. If this program is the
98 last program loaded on the interface, the dispatcher program will also
99 be removed, which makes the operation equivalent to specifying --all.
100 -a, --all
103 Unload all XDP programs on the interface, as well as the multi-program
104 dispatcher.
105 -v, --verbose
108 Enable debug logging. Specify twice for even more verbosity.
109 -h, --help
112 Display a summary of the available options
113
116 The status command displays a list of interfaces in the system, and the
117 XDP program(s) loaded on each interface. For each interface, a list of
118 programs are shown, with the run priority and "chain actions" for each
119 program. See the section on program metadata for the meaning of this
120 metadata.
121 -v, --verbose
124 Enable debug logging. Specify twice for even more verbosity.
125 -h, --help
128 Display a summary of the available options
129
133 To load an XDP program on the eth0 interface simply do:
134 # xdp-loader load eth0 xdp_drop.o
136 # xdp-loader status
137 CURRENT XDP PROGRAM STATUS:
139 Interface Prio Program name Mode ID Tag Chain actions
141 -------------------------------------------------------------------------------------
142 lo <no XDP program>
143 eth0 xdp_dispatcher native 50 d51e469e988d81da
144 => 50 xdp_drop 55 57cd311f2e27366b XDP_PASS
145 Which shows that a dispatcher program was loaded on the interface, and
149 the xdp_drop program was installed as the first (and only) component
150 program after it. In this instance, the program does not specify any of
151 the metadata above, so the defaults (priority 50 and XDP_PASS as its
152 chain call action) was used.
153 To use the automatic map pinning, include the pinning attribute into
156 the map definition in the program, something like:
157 struct {
159 __uint(type, BPF_MAP_TYPE_ARRAY);
160 __uint(max_entries, 10);
161 __type(key, __u32);
162 __type(value, __u64);
163 __uint(pinning, LIBBPF_PIN_BY_NAME);
164 } my_map SEC(".maps");
165 And load it with the --pin-path attribute:
168 # xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog
170 This will pin the map at /sys/fs/bpf/my-prog/my_map. If this already
173 exists, the pinned map will be reused instead of creating a new one,
174 which allows different BPF programs to share the map.
175
178 Please report any bugs on Github: https://github.com/xdp-project/xdp-
179 tools/issues
180
183 xdp-loader and this man page were written by Toke Høiland-Jørgensen.
184V1.0.0~BETA3 JULY 30, 2020 xdp-loader(8)