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
14 device (which is not natively supported by the kernel). This support
15 relies on the freplace functionality in the kernel, which makes it pos‐
16 sible to attach an eBPF program as a replacement for a global function
17 in 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);
32 if (!err)
34 xdp_program__detach(prog, IFINDEX, XDP_MODE_NATIVE);
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
41 either from a BPF object file on disk, from a libbpf BPF object, or
42 from 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_pro‐
81 gram__attach_multi(). It is expected that this restriction will be
82 lifted in an upcoming kernel version, after which xdp_program__attach()
83 will simply add the program being loaded into the existing chain of
84 programs running 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 <xdp/xdp_helpers.h>
121 struct {
123 __uint(priority, 10);
124 __uint(XDP_PASS, 1);
125 __uint(XDP_DROP, 1);
126 } XDP_RUN_CONFIG(my_xdp_func);
127 This example specifies that the XDP program in my_xdp_func should have
130 priority 10 and that its chain call actions are XDP_PASS and XDP_DROP.
131 In a source file with multiple XDP programs in the same file, a defini‐
132 tion like the above can be included for each program (main XDP func‐
133 tion). Any program that does not specify any config information will
134 use the default values outlined above.
135 Inspecting and modifying metadata
138 libxdp exposes the following functions that an application can use to
139 inspect and modify the metadata on an XDP program. Modification is only
140 possible before a program is attached on an interface. These functions
141 won't modify the BTF information itself, but the new values will be
142 stored as part of the program attachment.
143 unsigned int xdp_program__run_prio(const struct xdp_program *xdp_prog);
145 int xdp_program__set_run_prio(struct xdp_program *xdp_prog,
146 unsigned int run_prio);
147 bool xdp_program__chain_call_enabled(const struct xdp_program *xdp_prog,
148 enum xdp_action action);
149 int xdp_program__set_chain_call_enabled(struct xdp_program *prog,
150 unsigned int action,
151 bool enabled);
152 int xdp_program__print_chain_call_actions(const struct xdp_program *prog,
153 char *buf,
154 size_t buf_len);
155
158 To support multiple programs on the same network interface, libxdp uses
159 a dispatcher program which is a small wrapper program that will call
160 each component program in turn, expect the return code, and then chain
161 call to the next program based on the chain call actions of the previ‐
162 ous program (see the Program metadata section above).
163 While applications using libxdp do not need to know the details of the
166 dispatcher program to just load an XDP program unto an interface,
167 libxdp does expose the dispatcher and its attached component programs,
168 which can be used to list the programs currently attached to an inter‐
169 face.
170 The structure used for this is struct xdp_multiprog, which can only be
173 constructed from the programs loaded on an interface based on ifindex.
174 The API for getting a multiprog reference and iterating through the
175 attached programs looks like this:
176 struct xdp_multiprog *xdp_multiprog__get_from_ifindex(int ifindex);
178 struct xdp_program *xdp_multiprog__next_prog(const struct xdp_program *prog,
179 const struct xdp_multiprog *mp);
180 void xdp_multiprog__close(struct xdp_multiprog *mp);
181 int xdp_multiprog__detach(struct xdp_multiprog *mp, int ifindex);
182 enum xdp_attach_mode xdp_multiprog__attach_mode(const struct xdp_multiprog *mp);
183 struct xdp_program *xdp_multiprog__main_prog(const struct xdp_multiprog *mp);
184 bool xdp_multiprog__is_legacy(const struct xdp_multiprog *mp);
185 If a program is attached to the interface which libxdp doesn't recog‐
188 nise as a dispatcher program, an xdp_multiprog structure will still be
189 returned, and xdp_multiprog__is_legacy() will return true for that pro‐
190 gram. A reference to that (regular) XDP program can be obtained by
191 xdp_multiprog__main_prog(). If the program attached to the interface is
192 a dispatcher program, xdp_multiprog__main_prog() will return a refer‐
193 ence to the dispatcher program itself, which is mainly useful for
194 obtaining other data about that program (such as the program ID).
195 Pinning in bpffs
198 The kernel will automatically detach component programs from the dis‐
199 patcher once the last reference to them disappears. To prevent this
200 from happening, libxdp will pin the component program references in
201 bpffs before attaching the dispatcher to the network interface. The
202 pathnames generated for pinning is as follows:
203 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID - dispatcher program for
206 IFINDEX with BPF program ID DID
207 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog0-prog - component program
209 0, program reference
210 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog0-link - component program
212 0, bpf_link reference
213 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog1-prog - component program
215 1, program reference
216 — /sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog1-link - component program
218 1, bpf_link reference
219 — etc, up to ten component programs
221
224 Please report any bugs on Github: https://github.com/xdp-project/xdp-
225 tools/issues
226
229 libxdp and this man page were written by Toke Høiland-Jørgensen
230v1.0.0~beta3 July 30, 2020 libxdp(3)