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 | { -l | --legacy } | { -f | --bpffs } | { -m | --mapcompat } | { -n
14 | --nomount } | { -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 | visual | linum}]
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] [dev NAME] [pinmaps MAP_DIR]
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 msg_verdict | skb_verdict | stream_verdict | stream_parser | flow_dissector
48 }
49 METRICs := {
50 cycles | instructions | l1d_loads | llc_misses |
51 itlb_misses | dtlb_misses
52 }
53
56 bpftool prog { show | list } [PROG]
57 Show information about loaded programs. If PROG is specified
58 show information only about given programs, otherwise list
59 all programs currently loaded on the system. In case of tag
60 or name, PROG may match several programs which will all be
61 shown.
62 Output will start with program ID followed by program type
64 and zero or more named attributes (depending on kernel ver‐
65 sion).
66 Since Linux 5.1 the kernel can collect statistics on BPF pro‐
68 grams (such as the total time spent running the program, and
69 the number of times it was run). If available, bpftool shows
70 such statistics. However, the kernel does not collect them by
71 defaults, as it slightly impacts performance on each program
72 run. Activation or deactivation of the feature is performed
73 via the kernel.bpf_stats_enabled sysctl knob.
74 Since Linux 5.8 bpftool is able to discover information about
76 processes that hold open file descriptors (FDs) against BPF
77 programs. On such kernels bpftool will automatically emit
78 this information as well.
79 bpftool prog dump xlated PROG [{ file FILE | opcodes | visual |
81 linum }]
82 Dump eBPF instructions of the programs from the kernel. By
83 default, eBPF will be disassembled and printed to standard
84 output in human-readable format. In this case, opcodes con‐
85 trols if raw opcodes should be printed as well.
86 In case of tag or name, PROG may match several programs which
88 will all be dumped. However, if file or visual is specified,
89 PROG must match a single program.
90 If file is specified, the binary image will instead be writ‐
92 ten to FILE.
93 If visual is specified, control flow graph (CFG) will be
95 built instead, and eBPF instructions will be presented with
96 CFG in DOT format, on standard output.
97 If the programs have line_info available, the source line
99 will be displayed by default. If linum is specified, the
100 filename, line number and line column will also be displayed
101 on top of the source line.
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 by default. If linum is specified, the filename,
114 line number and line column will also be displayed on top of
115 the source line.
116 bpftool prog pin PROG FILE
118 Pin program PROG as FILE.
119 Note: FILE must be located in bpffs mount. It must not con‐
121 tain a dot character ('.'), which is reserved for future ex‐
122 tensions of bpffs.
123 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX |
125 name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
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 dev NAME is specified program
138 will be loaded onto given networking device (offload). Op‐
139 tional pinmaps argument can be provided to pin all maps under
140 MAP_DIR directory.
141 Note: PATH must be located in bpffs mount. It must not con‐
143 tain a dot character ('.'), which is reserved for future ex‐
144 tensions of bpffs.
145 bpftool prog attach PROG ATTACH_TYPE [MAP]
147 Attach bpf program PROG (with type specified by ATTACH_TYPE).
148 Most ATTACH_TYPEs require a MAP parameter, with the exception
149 of flow_dissector which is attached to current networking
150 name space.
151 bpftool prog detach PROG ATTACH_TYPE [MAP]
153 Detach bpf program PROG (with type specified by ATTACH_TYPE).
154 Most ATTACH_TYPEs require a MAP parameter, with the exception
155 of flow_dissector which is detached from the current network‐
156 ing name space.
157 bpftool prog tracelog
159 Dump the trace pipe of the system to the console (stdout).
160 Hit <Ctrl+C> to stop printing. BPF programs can write to this
161 trace pipe at runtime with the bpf_trace_printk() helper.
162 This should be used only for debugging purposes. For stream‐
163 ing data from BPF programs to user space, one can use perf
164 events (see also bpftool-map(8)).
165 bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]]
167 [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
168 Run BPF program PROG in the kernel testing infrastructure for
169 BPF, meaning that the program works on the data and context
170 provided by the user, and not on actual packets or monitored
171 functions etc. Return value and duration for the test run are
172 printed out to the console.
173 Input data is read from the FILE passed with data_in. If
175 this FILE is "-", input data is read from standard input. In‐
176 put context, if any, is read from FILE passed with ctx_in.
177 Again, "-" can be used to read from standard input, but only
178 if standard input is not already in use for input data. If a
179 FILE is passed with data_out, output data is written to that
180 file. Similarly, output context is written to the FILE passed
181 with ctx_out. For both output flows, "-" can be used to print
182 to the standard output (as plain text, or JSON if relevant
183 option was passed). If output keywords are omitted, output
184 data and context are discarded. Keywords data_size_out and
185 ctx_size_out are used to pass the size (in bytes) for the
186 output buffers to the kernel, although the default of 32 kB
187 should be more than enough for most cases.
188 Keyword repeat is used to indicate the number of consecutive
190 runs to perform. Note that output data and context printed to
191 files correspond to the last of those runs. The duration
192 printed out at the end of the runs is an average over all
193 runs performed by the command.
194 Not all program types support test run. Among those which do,
196 not all of them can take the ctx_in/ctx_out arguments.
197 bpftool does not perform checks on program types.
198 bpftool prog profile PROG [duration DURATION] METRICs
200 Profile METRICs for bpf program PROG for DURATION seconds or
201 until user hits <Ctrl+C>. DURATION is optional. If DURATION
202 is not specified, the profiling will run up to UINT_MAX sec‐
203 onds.
204 bpftool prog help
206 Print short help message.
207
209 -h, --help
210 Print short help message (similar to bpftool help).
211 -V, --version
213 Print bpftool's version number (similar to bpftool version),
214 the number of the libbpf version in use, and optional fea‐
215 tures that were included when bpftool was compiled. Optional
216 features include linking against libbfd to provide the disas‐
217 sembler for JIT-ted programs (bpftool prog dump jited) and
218 usage of BPF skeletons (some features like bpftool prog pro‐
219 file or showing pids associated to BPF objects may rely on
220 it).
221 -j, --json
223 Generate JSON output. For commands that cannot produce JSON,
224 this option has no effect.
225 -p, --pretty
227 Generate human-readable JSON output. Implies -j.
228 -d, --debug
230 Print all logs available, even debug-level information. This
231 includes logs from libbpf as well as from the verifier, when
232 attempting to load programs.
233 -l, --legacy
235 Use legacy libbpf mode which has more relaxed BPF program re‐
236 quirements. By default, bpftool has more strict requirements
237 about section names, changes pinning logic and doesn't sup‐
238 port some of the older non-BTF map declarations.
239 See
241 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
242 for details.
243 -f, --bpffs
245 When showing BPF programs, show file names of pinned pro‐
246 grams.
247 -m, --mapcompat
249 Allow loading maps with unknown map definitions.
250 -n, --nomount
252 Do not automatically attempt to mount any virtual file system
253 (such as tracefs or BPF virtual file system) when necessary.
254 -L, --use-loader
256 Load program as a "loader" program. This is useful to debug
257 the generation of such programs. When this option is in use,
258 bpftool attempts to load the programs from the object file
259 into the kernel, but does not pin them (therefore, the PATH
260 must not be provided).
261 When combined with the -d|--debug option, additional debug
263 messages are generated, and the execution of the loader pro‐
264 gram will use the bpf_trace_printk() helper to log each step
265 of loading BTF, creating the maps, and loading the programs
266 (see bpftool prog tracelog as a way to dump those messages).
267
269 # bpftool prog show
270 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
272 loaded_at 2017-09-29T20:11:00+0000 uid 0
273 xlated 528B jited 370B memlock 4096B map_ids 10
274 pids systemd(1)
275 # bpftool --json --pretty prog show
277 [{
279 "id": 10,
280 "type": "xdp",
281 "tag": "005a3d2123620c8b",
282 "gpl_compatible": true,
283 "run_time_ns": 81632,
284 "run_cnt": 10,
285 "loaded_at": 1506715860,
286 "uid": 0,
287 "bytes_xlated": 528,
288 "jited": true,
289 "bytes_jited": 370,
290 "bytes_memlock": 4096,
291 "map_ids": [10
292 ],
293 "pids": [{
294 "pid": 1,
295 "comm": "systemd"
296 }
297 ]
298 }
299 ]
300 # bpftool prog dump xlated id 10 file /tmp/t
302 $ ls -l /tmp/t
303 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
306 # bpftool prog dump jited tag 005a3d2123620c8b
308 0: push %rbp
310 1: mov %rsp,%rbp
311 2: sub $0x228,%rsp
312 3: sub $0x28,%rbp
313 4: mov %rbx,0x0(%rbp)
314 # mount -t bpf none /sys/fs/bpf/
316 # bpftool prog pin id 10 /sys/fs/bpf/prog
317 # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
318 # ls -l /sys/fs/bpf/
319 -rw------- 1 root root 0 Jul 22 01:43 prog
322 -rw------- 1 root root 0 Jul 22 01:44 prog2
323 # bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
325 0: push %rbp
327 55
328 1: mov %rsp,%rbp
329 48 89 e5
330 4: sub $0x228,%rsp
331 48 81 ec 28 02 00 00
332 b: sub $0x28,%rbp
333 48 83 ed 28
334 f: mov %rbx,0x0(%rbp)
335 48 89 5d 00
336 # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
338 # bpftool prog show pinned /sys/fs/bpf/xdp1
339 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
342 loaded_at 2018-06-25T16:17:31-0700 uid 0
343 xlated 488B jited 336B memlock 4096B map_ids 7
344 # rm /sys/fs/bpf/xdp1
346 # bpftool prog profile id 337 duration 10 cycles instructions llc_misses
348 51397 run_cnt
351 40176203 cycles (83.05%)
352 42518139 instructions # 1.06 insns per cycle (83.39%)
353 123 llc_misses # 2.89 LLC misses per million insns (83.15%)
354 Output below is for the trace logs.
356 Run in separate terminals:
357 # bpftool prog tracelog
358 # bpftool prog load -L -d file.o
359 bpftool-620059 [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
362 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
363 bpftool-620059 [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
364 bpftool-620059 [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0
365
367 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
368 bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8),
369 bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8),
370 bpftool-perf(8), bpftool-struct_ops(8)
371 BPFTOOL-PROG(8)