1libxdp(3) libxdp - library for loading XDP programs libxdp(3)
2
6 This directory contains the files for the libxdp library for attaching
7 XDP programs to network interfaces. The library is fairly lightweight
8 and relies on libbpf to do the heavy lifting for processing eBPF object
9 files etc.
10 The primary feature that libxdp provides on top of libbpf is the abil‐
13 ity to load multiple XDP programs in sequence on a single network de‐
14 vice (which is not natively supported by the kernel). This support re‐
15 lies on the freplace functionality in the kernel, which makes it possi‐
16 ble to attach an eBPF program as a replacement for a global function in
17 another (already loaded) eBPF program.
18 Using libxdp from an application
21 Basic usage of libxdp from an application is quite straight forward.
22 The following example loads, then unloads, an XDP program from the 'lo'
23 interface:
24 #define IFINDEX 1
26 struct xdp_program *prog;
28 int err;
29 prog = xdp_program__open_file("my-program.o", "section_name", NULL);
31 err = xdp_program__attach(prog, IFINDEX, XDP_MODE_NATIVE, 0);
32 if (!err)
34 xdp_program__detach(prog, IFINDEX, XDP_MODE_NATIVE, 0);
35 xdp_program__close(prog);
37 The xdp_program structure is an opaque structure that represents a sin‐
40 gle XDP program. libxdp contains functions to create such a struct ei‐
41 ther from a BPF object file on disk, from a libbpf BPF object, or from
42 an identifier of a program that is already loaded into the kernel:
43 struct xdp_program *xdp_program__from_bpf_obj(struct bpf_object *obj,
45 const char *section_name);
46 struct xdp_program *xdp_program__find_file(const char *filename,
47 const char *section_name,
48 struct bpf_object_open_opts *opts);
49 struct xdp_program *xdp_program__open_file(const char *filename,
50 const char *section_name,
51 struct bpf_object_open_opts *opts);
52 struct xdp_program *xdp_program__from_fd(int fd);
53 struct xdp_program *xdp_program__from_id(__u32 prog_id);
54 struct xdp_program *xdp_program__from_pin(const char *pin_path);
55 The functions that open a BPF object or file need the function name of
58 the XDP program as well as the file name or object, since an ELF file
59 can contain multiple XDP programs. The xdp_program__find_file() func‐
60 tion takes a filename without a path, and will look for the object in
61 LIBXDP_OBJECT_PATH which defaults to /usr/lib/bpf (or /usr/lib64/bpf on
62 systems using a split library path). This is convenient for applica‐
63 tions shipping pre-compiled eBPF object files.
64 The xdp_program__attach() function will attach the program to an inter‐
67 face, building a dispatcher program to execute it. Multiple programs
68 can be attached at once with xdp_program__attach_multi(); they will be
69 sorted in order of their run priority, and execution from one program
70 to the next will proceed based on the chain call actions defined for
71 each program (see the Program metadata section below). Because the
72 loading process involves modifying the attach type of the program, the
73 attach functions only work with struct xdp_program objects that have
74 not yet been loaded into the kernel.
75 Due to limitations in the kernel support, it is currently not possible
78 to attach another program to an already-attached list of programs. As
79 such, the only way to actually run multiple programs on a single inter‐
80 face is to attach them all at the same time with xdp_program__at‐
81 tach_multi(). It is expected that this restriction will be lifted in an
82 upcoming kernel version, after which xdp_program__attach() will simply
83 add the program being loaded into the existing chain of programs run‐
84 ning on the interface.
85
88 To support multiple XDP programs on the same interface, libxdp uses two
89 pieces of metadata for each XDP program: Run priority and chain call
90 actions.
91 Run priority
94 This is the priority of the program and is a simple integer used to
95 sort programs when loading multiple programs onto the same interface.
96 Programs that wish to run early (such as a packet filter) should set
97 low values for this, while programs that want to run later (such as a
98 packet forwarder or counter) should set higher values. Note that later
99 programs are only run if the previous programs end with a return code
100 that is part of its chain call actions (see below). If not specified,
101 the default priority value is 50.
102 Chain call actions
105 These are the program return codes that the program indicate for pack‐
106 ets that should continue processing. If the program returns one of
107 these actions, later programs in the call chain will be run, whereas if
108 it returns any other action, processing will be interrupted, and the
109 XDP dispatcher will return the verdict immediately. If not set, this
110 defaults to just XDP_PASS, which is likely the value most programs
111 should use.
112 Specifying metadata
115 The metadata outlined above is specified as BTF information embedded in
116 the ELF file containing the XDP program. The xdp_helpers.h file shipped
117 with libxdp contains helper macros to include this information, which
118 can be used as follows:
119 #include <bpf/bpf_helpers.h>
121 #include <xdp/xdp_helpers.h>
122 struct {
124 __uint(priority, 10);
125 __uint(XDP_PASS, 1);
126 __uint(XDP_DROP, 1);
127 } XDP_RUN_CONFIG(my_xdp_func);
128 This example specifies that the XDP program in my_xdp_func should have
131 priority 10 and that its chain call actions are XDP_PASS and XDP_DROP.
132 In a source file with multiple XDP programs in the same file, a defini‐
133 tion like the above can be included for each program (main XDP func‐
134 tion). Any program that does not specify any config information will
135 use the default values outlined above.
136 Inspecting and modifying metadata
139 libxdp exposes the following functions that an application can use to
140 inspect and modify the metadata on an XDP program. Modification is only
141 possible before a program is attached on an interface. These functions
142 won't modify the BTF information itself, but the new values will be
143 stored as part of the program attachment.
144 unsigned int xdp_program__run_prio(const struct xdp_program *xdp_prog);
146 int xdp_program__set_run_prio(struct xdp_program *xdp_prog,
147 unsigned int run_prio);
148 bool xdp_program__chain_call_enabled(const struct xdp_program *xdp_prog,
149 enum xdp_action action);
150 int xdp_program__set_chain_call_enabled(struct xdp_program *prog,
151 unsigned int action,
152 bool enabled);
153 int xdp_program__print_chain_call_actions(const struct xdp_program *prog,
154 char *buf,
155 size_t buf_len);
156
159 To support multiple non-offloaded programs on the same network inter‐
160 face, libxdp uses a dispatcher program which is a small wrapper program
161 that will call each component program in turn, expect the return code,
162 and then chain call to the next program based on the chain call actions
163 of the previous program (see the Program metadata section above).
164 While applications using libxdp do not need to know the details of the
167 dispatcher program to just load an XDP program unto an interface,
168 libxdp does expose the dispatcher and its attached component programs,
169 which can be used to list the programs currently attached to an inter‐
170 face.
171 The structure used for this is struct xdp_multiprog, which can only be
174 constructed from the programs loaded on an interface based on ifindex.
175 The API for getting a multiprog reference and iterating through the at‐
176 tached programs looks like this:
177 struct xdp_multiprog *xdp_multiprog__get_from_ifindex(int ifindex);
179 struct xdp_program *xdp_multiprog__next_prog(const struct xdp_program *prog,
180 const struct xdp_multiprog *mp);
181 void xdp_multiprog__close(struct xdp_multiprog *mp);
182 int xdp_multiprog__detach(struct xdp_multiprog *mp, int ifindex);
183 enum xdp_attach_mode xdp_multiprog__attach_mode(const struct xdp_multiprog *mp);
184 struct xdp_program *xdp_multiprog__main_prog(const struct xdp_multiprog *mp);
185 struct xdp_program *xdp_multiprog__hw_prog(const struct xdp_multiprog *mp);
186 bool xdp_multiprog__is_legacy(const struct xdp_multiprog *mp);
187 If a non-offloaded program is attached to the interface which libxdp
190 doesn't recognise as a dispatcher program, an xdp_multiprog structure
191 will still be returned, and xdp_multiprog__is_legacy() will return true
192 for that program (note that this also holds true if only an offloaded
193 program is loaded). A reference to that (regular) XDP program can be
194 obtained by xdp_multiprog__main_prog(). If the program attached to the
195 interface is a dispatcher program, xdp_multiprog__main_prog() will re‐
196 turn a reference to the dispatcher program itself, which is mainly use‐
197 ful for obtaining other data about that program (such as the program
198 ID). A reference to an offloaded program can be acquired using xdp_mul‐
199 tiprog_hw_prog(). Function xdp_multiprog__attach_mode() returns the at‐
200 tach mode of the non-offloaded program, whether an offloaded program is
201 attached should be checked through xdp_multiprog_hw_prog().
202 Pinning in bpffs
205 The kernel will automatically detach component programs from the dis‐
206 patcher once the last reference to them disappears. To prevent this
207 from happening, libxdp will pin the component program references in
208 bpffs before attaching the dispatcher to the network interface. The
209 pathnames generated for pinning is as follows:
210 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID - dispatcher program for
213 IFINDEX with BPF program ID DID
214 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog0-prog - component program
216 0, program reference
217 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog0-link - component program
219 0, bpf_link reference
220 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog1-prog - component program
222 1, program reference
223 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog1-link - component program
225 1, bpf_link reference
226 — etc, up to ten component programs
228 If set, the LIBXDP_BPFFS environment variable will override the loca‐
231 tion of bpffs, but the xdp subdirectory is always used.
232
235 Please report any bugs on Github: https://github.com/xdp-project/xdp-
236 tools/issues
237
240 libxdp and this man page were written by Toke Høiland-Jørgensen
241v1.1.1 February 8, 2021 libxdp(3)