1BPFTOOL-PROG(8) BPFTOOL-PROG(8)
2
6 bpftool-prog - tool for inspection and simple manipulation of eBPF
7 progs
8
10 bpftool [OPTIONS] prog COMMAND
11 OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug }
13 | { -f | --bpffs } | { -m | --mapcompat } | { -n | --nomount } | {
14 -L | --use-loader } }
15 COMMANDS := { show | list | dump xlated | dump jited | pin | load |
17 loadall | help }
18
20 bpftool prog { show | list } [PROG]
21 bpftool prog dump xlated PROG [{ file FILE | [opcodes] [linum] [visual] }]
22 bpftool prog dump jited PROG [{ file FILE | [opcodes] [linum] }]
23 bpftool prog pin PROG FILE
24 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map { idx IDX | name NAME } MAP] [{ offload_dev | xdpmeta_dev } NAME] [pinmaps MAP_DIR] [autoattach]
25 bpftool prog attach PROG ATTACH_TYPE [MAP]
26 bpftool prog detach PROG ATTACH_TYPE [MAP]
27 bpftool prog tracelog
28 bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]] [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
29 bpftool prog profile PROG [duration DURATION] METRICs
30 bpftool prog help
31 MAP := { id MAP_ID | pinned FILE }
33 PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
34 TYPE := {
35 socket | kprobe | kretprobe | classifier | action |
36 tracepoint | raw_tracepoint | xdp | perf_event | cgroup/skb |
37 cgroup/sock | cgroup/dev | lwt_in | lwt_out | lwt_xmit |
38 lwt_seg6local | sockops | sk_skb | sk_msg | lirc_mode2 |
39 cgroup/bind4 | cgroup/bind6 | cgroup/post_bind4 | cgroup/post_bind6 |
40 cgroup/connect4 | cgroup/connect6 | cgroup/getpeername4 | cgroup/getpeername6 |
41 cgroup/getsockname4 | cgroup/getsockname6 | cgroup/sendmsg4 | cgroup/sendmsg6 |
42 cgroup/recvmsg4 | cgroup/recvmsg6 | cgroup/sysctl |
43 cgroup/getsockopt | cgroup/setsockopt | cgroup/sock_release |
44 struct_ops | fentry | fexit | freplace | sk_lookup
45 }
46 ATTACH_TYPE := {
47 sk_msg_verdict | sk_skb_verdict | sk_skb_stream_verdict |
48 sk_skb_stream_parser | flow_dissector
49 }
50 METRICs := {
51 cycles | instructions | l1d_loads | llc_misses |
52 itlb_misses | dtlb_misses
53 }
54
57 bpftool prog { show | list } [PROG]
58 Show information about loaded programs. If PROG is specified
59 show information only about given programs, otherwise list
60 all programs currently loaded on the system. In case of tag
61 or name, PROG may match several programs which will all be
62 shown.
63 Output will start with program ID followed by program type
65 and zero or more named attributes (depending on kernel ver‐
66 sion).
67 Since Linux 5.1 the kernel can collect statistics on BPF pro‐
69 grams (such as the total time spent running the program, and
70 the number of times it was run). If available, bpftool shows
71 such statistics. However, the kernel does not collect them by
72 defaults, as it slightly impacts performance on each program
73 run. Activation or deactivation of the feature is performed
74 via the kernel.bpf_stats_enabled sysctl knob.
75 Since Linux 5.8 bpftool is able to discover information about
77 processes that hold open file descriptors (FDs) against BPF
78 programs. On such kernels bpftool will automatically emit
79 this information as well.
80 bpftool prog dump xlated PROG [{ file FILE | [opcodes] [linum] [vis‐
82 ual] }]
83 Dump eBPF instructions of the programs from the kernel. By
84 default, eBPF will be disassembled and printed to standard
85 output in human-readable format. In this case, opcodes con‐
86 trols if raw opcodes should be printed as well.
87 In case of tag or name, PROG may match several programs which
89 will all be dumped. However, if file or visual is specified,
90 PROG must match a single program.
91 If file is specified, the binary image will instead be writ‐
93 ten to FILE.
94 If visual is specified, control flow graph (CFG) will be
96 built instead, and eBPF instructions will be presented with
97 CFG in DOT format, on standard output.
98 If the programs have line_info available, the source line
100 will be displayed. If linum is specified, the filename, line
101 number and line column will also be displayed.
102 bpftool prog dump jited PROG [{ file FILE | [opcodes] [linum] }]
104 Dump jited image (host machine code) of the program.
105 If FILE is specified image will be written to a file, other‐
107 wise it will be disassembled and printed to stdout. PROG
108 must match a single program when file is specified.
109 opcodes controls if raw opcodes will be printed.
111 If the prog has line_info available, the source line will be
113 displayed. If linum is specified, the filename, line number
114 and line column will also be displayed.
115 bpftool prog pin PROG FILE
117 Pin program PROG as FILE.
118 Note: FILE must be located in bpffs mount. It must not con‐
120 tain a dot character ('.'), which is reserved for future ex‐
121 tensions of bpffs.
122 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map { idx IDX
124 | name NAME } MAP] [{ offload_dev | xdpmeta_dev } NAME] [pinmaps
125 MAP_DIR] [autoattach]
126 Load bpf program(s) from binary OBJ and pin as PATH. bpftool
127 prog load pins only the first program from the OBJ as PATH.
128 bpftool prog loadall pins all programs from the OBJ under
129 PATH directory. type is optional, if not specified program
130 type will be inferred from section names. By default bpftool
131 will create new maps as declared in the ELF object being
132 loaded. map parameter allows for the reuse of existing maps.
133 It can be specified multiple times, each time for a different
134 map. IDX refers to index of the map to be replaced in the
135 ELF file counting from 0, while NAME allows to replace a map
136 by name. MAP specifies the map to use, referring to it by id
137 or through a pinned file. If offload_dev NAME is specified
138 program will be loaded onto given networking device (off‐
139 load). If xdpmeta_dev NAME is specified program will become
140 device-bound without offloading, this facilitates access to
141 XDP metadata. Optional pinmaps argument can be provided to
142 pin all maps under MAP_DIR directory.
143 If autoattach is specified program will be attached before
145 pin. In that case, only the link (representing the program
146 attached to its hook) is pinned, not the program as such, so
147 the path won't show in bpftool prog show -f, only show in
148 bpftool link show -f. Also, this only works when bpftool
149 (libbpf) is able to infer all necessary information from the
150 object file, in particular, it's not supported for all pro‐
151 gram types. If a program does not support autoattach, bpftool
152 falls back to regular pinning for that program instead.
153 Note: PATH must be located in bpffs mount. It must not con‐
155 tain a dot character ('.'), which is reserved for future ex‐
156 tensions of bpffs.
157 bpftool prog attach PROG ATTACH_TYPE [MAP]
159 Attach bpf program PROG (with type specified by ATTACH_TYPE).
160 Most ATTACH_TYPEs require a MAP parameter, with the exception
161 of flow_dissector which is attached to current networking
162 name space.
163 bpftool prog detach PROG ATTACH_TYPE [MAP]
165 Detach bpf program PROG (with type specified by ATTACH_TYPE).
166 Most ATTACH_TYPEs require a MAP parameter, with the exception
167 of flow_dissector which is detached from the current network‐
168 ing name space.
169 bpftool prog tracelog
171 Dump the trace pipe of the system to the console (stdout).
172 Hit <Ctrl+C> to stop printing. BPF programs can write to this
173 trace pipe at runtime with the bpf_trace_printk() helper.
174 This should be used only for debugging purposes. For stream‐
175 ing data from BPF programs to user space, one can use perf
176 events (see also bpftool-map(8)).
177 bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]]
179 [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
180 Run BPF program PROG in the kernel testing infrastructure for
181 BPF, meaning that the program works on the data and context
182 provided by the user, and not on actual packets or monitored
183 functions etc. Return value and duration for the test run are
184 printed out to the console.
185 Input data is read from the FILE passed with data_in. If
187 this FILE is "-", input data is read from standard input. In‐
188 put context, if any, is read from FILE passed with ctx_in.
189 Again, "-" can be used to read from standard input, but only
190 if standard input is not already in use for input data. If a
191 FILE is passed with data_out, output data is written to that
192 file. Similarly, output context is written to the FILE passed
193 with ctx_out. For both output flows, "-" can be used to print
194 to the standard output (as plain text, or JSON if relevant
195 option was passed). If output keywords are omitted, output
196 data and context are discarded. Keywords data_size_out and
197 ctx_size_out are used to pass the size (in bytes) for the
198 output buffers to the kernel, although the default of 32 kB
199 should be more than enough for most cases.
200 Keyword repeat is used to indicate the number of consecutive
202 runs to perform. Note that output data and context printed to
203 files correspond to the last of those runs. The duration
204 printed out at the end of the runs is an average over all
205 runs performed by the command.
206 Not all program types support test run. Among those which do,
208 not all of them can take the ctx_in/ctx_out arguments.
209 bpftool does not perform checks on program types.
210 bpftool prog profile PROG [duration DURATION] METRICs
212 Profile METRICs for bpf program PROG for DURATION seconds or
213 until user hits <Ctrl+C>. DURATION is optional. If DURATION
214 is not specified, the profiling will run up to UINT_MAX sec‐
215 onds.
216 bpftool prog help
218 Print short help message.
219
221 -h, --help
222 Print short help message (similar to bpftool help).
223 -V, --version
225 Print bpftool's version number (similar to bpftool version),
226 the number of the libbpf version in use, and optional fea‐
227 tures that were included when bpftool was compiled. Optional
228 features include linking against LLVM or libbfd to provide
229 the disassembler for JIT-ted programs (bpftool prog dump
230 jited) and usage of BPF skeletons (some features like bpftool
231 prog profile or showing pids associated to BPF objects may
232 rely on it).
233 -j, --json
235 Generate JSON output. For commands that cannot produce JSON,
236 this option has no effect.
237 -p, --pretty
239 Generate human-readable JSON output. Implies -j.
240 -d, --debug
242 Print all logs available, even debug-level information. This
243 includes logs from libbpf as well as from the verifier, when
244 attempting to load programs.
245 -f, --bpffs
247 When showing BPF programs, show file names of pinned pro‐
248 grams.
249 -m, --mapcompat
251 Allow loading maps with unknown map definitions.
252 -n, --nomount
254 Do not automatically attempt to mount any virtual file system
255 (such as tracefs or BPF virtual file system) when necessary.
256 -L, --use-loader
258 Load program as a "loader" program. This is useful to debug
259 the generation of such programs. When this option is in use,
260 bpftool attempts to load the programs from the object file
261 into the kernel, but does not pin them (therefore, the PATH
262 must not be provided).
263 When combined with the -d|--debug option, additional debug
265 messages are generated, and the execution of the loader pro‐
266 gram will use the bpf_trace_printk() helper to log each step
267 of loading BTF, creating the maps, and loading the programs
268 (see bpftool prog tracelog as a way to dump those messages).
269
271 # bpftool prog show
272 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
274 loaded_at 2017-09-29T20:11:00+0000 uid 0
275 xlated 528B jited 370B memlock 4096B map_ids 10
276 pids systemd(1)
277 # bpftool --json --pretty prog show
279 [{
281 "id": 10,
282 "type": "xdp",
283 "tag": "005a3d2123620c8b",
284 "gpl_compatible": true,
285 "run_time_ns": 81632,
286 "run_cnt": 10,
287 "loaded_at": 1506715860,
288 "uid": 0,
289 "bytes_xlated": 528,
290 "jited": true,
291 "bytes_jited": 370,
292 "bytes_memlock": 4096,
293 "map_ids": [10
294 ],
295 "pids": [{
296 "pid": 1,
297 "comm": "systemd"
298 }
299 ]
300 }
301 ]
302 # bpftool prog dump xlated id 10 file /tmp/t
304 $ ls -l /tmp/t
305 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
308 # bpftool prog dump jited tag 005a3d2123620c8b
310 0: push %rbp
312 1: mov %rsp,%rbp
313 2: sub $0x228,%rsp
314 3: sub $0x28,%rbp
315 4: mov %rbx,0x0(%rbp)
316 # mount -t bpf none /sys/fs/bpf/
318 # bpftool prog pin id 10 /sys/fs/bpf/prog
319 # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
320 # ls -l /sys/fs/bpf/
321 -rw------- 1 root root 0 Jul 22 01:43 prog
324 -rw------- 1 root root 0 Jul 22 01:44 prog2
325 # bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
327 0: push %rbp
329 55
330 1: mov %rsp,%rbp
331 48 89 e5
332 4: sub $0x228,%rsp
333 48 81 ec 28 02 00 00
334 b: sub $0x28,%rbp
335 48 83 ed 28
336 f: mov %rbx,0x0(%rbp)
337 48 89 5d 00
338 # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
340 # bpftool prog show pinned /sys/fs/bpf/xdp1
341 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
344 loaded_at 2018-06-25T16:17:31-0700 uid 0
345 xlated 488B jited 336B memlock 4096B map_ids 7
346 # rm /sys/fs/bpf/xdp1
348 # bpftool prog profile id 337 duration 10 cycles instructions llc_misses
350 51397 run_cnt
353 40176203 cycles (83.05%)
354 42518139 instructions # 1.06 insns per cycle (83.39%)
355 123 llc_misses # 2.89 LLC misses per million insns (83.15%)
356 Output below is for the trace logs.
358 Run in separate terminals:
359 # bpftool prog tracelog
360 # bpftool prog load -L -d file.o
361 bpftool-620059 [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
364 bpftool-620059 [004] d... 2634685.517912: bpf_trace_printk: map_create sample_map idx 0 type 2 value_size 4 value_btf_id 0 r=6
365 bpftool-620059 [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
366 bpftool-620059 [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0
367
369 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
370 bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8),
371 bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8),
372 bpftool-perf(8), bpftool-struct_ops(8)
373 BPFTOOL-PROG(8)