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 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 | visual |
82 linum }]
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 by default. If linum is specified, the
101 filename, line number and line column will also be displayed
102 on top of the source line.
103 bpftool prog dump jited PROG [{ file FILE | opcodes | linum }]
105 Dump jited image (host machine code) of the program.
106 If FILE is specified image will be written to a file, other‐
108 wise it will be disassembled and printed to stdout. PROG
109 must match a single program when file is specified.
110 opcodes controls if raw opcodes will be printed.
112 If the prog has line_info available, the source line will be
114 displayed by default. If linum is specified, the filename,
115 line number and line column will also be displayed on top of
116 the source line.
117 bpftool prog pin PROG FILE
119 Pin program PROG as FILE.
120 Note: FILE must be located in bpffs mount. It must not con‐
122 tain a dot character ('.'), which is reserved for future ex‐
123 tensions of bpffs.
124 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX |
126 name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
127 Load bpf program(s) from binary OBJ and pin as PATH. bpftool
128 prog load pins only the first program from the OBJ as PATH.
129 bpftool prog loadall pins all programs from the OBJ under
130 PATH directory. type is optional, if not specified program
131 type will be inferred from section names. By default bpftool
132 will create new maps as declared in the ELF object being
133 loaded. map parameter allows for the reuse of existing maps.
134 It can be specified multiple times, each time for a different
135 map. IDX refers to index of the map to be replaced in the
136 ELF file counting from 0, while NAME allows to replace a map
137 by name. MAP specifies the map to use, referring to it by id
138 or through a pinned file. If dev NAME is specified program
139 will be loaded onto given networking device (offload). Op‐
140 tional pinmaps argument can be provided to pin all maps under
141 MAP_DIR directory.
142 Note: PATH must be located in bpffs mount. It must not con‐
144 tain a dot character ('.'), which is reserved for future ex‐
145 tensions of bpffs.
146 bpftool prog attach PROG ATTACH_TYPE [MAP]
148 Attach bpf program PROG (with type specified by ATTACH_TYPE).
149 Most ATTACH_TYPEs require a MAP parameter, with the exception
150 of flow_dissector which is attached to current networking
151 name space.
152 bpftool prog detach PROG ATTACH_TYPE [MAP]
154 Detach bpf program PROG (with type specified by ATTACH_TYPE).
155 Most ATTACH_TYPEs require a MAP parameter, with the exception
156 of flow_dissector which is detached from the current network‐
157 ing name space.
158 bpftool prog tracelog
160 Dump the trace pipe of the system to the console (stdout).
161 Hit <Ctrl+C> to stop printing. BPF programs can write to this
162 trace pipe at runtime with the bpf_trace_printk() helper.
163 This should be used only for debugging purposes. For stream‐
164 ing data from BPF programs to user space, one can use perf
165 events (see also bpftool-map(8)).
166 bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]]
168 [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
169 Run BPF program PROG in the kernel testing infrastructure for
170 BPF, meaning that the program works on the data and context
171 provided by the user, and not on actual packets or monitored
172 functions etc. Return value and duration for the test run are
173 printed out to the console.
174 Input data is read from the FILE passed with data_in. If
176 this FILE is "-", input data is read from standard input. In‐
177 put context, if any, is read from FILE passed with ctx_in.
178 Again, "-" can be used to read from standard input, but only
179 if standard input is not already in use for input data. If a
180 FILE is passed with data_out, output data is written to that
181 file. Similarly, output context is written to the FILE passed
182 with ctx_out. For both output flows, "-" can be used to print
183 to the standard output (as plain text, or JSON if relevant
184 option was passed). If output keywords are omitted, output
185 data and context are discarded. Keywords data_size_out and
186 ctx_size_out are used to pass the size (in bytes) for the
187 output buffers to the kernel, although the default of 32 kB
188 should be more than enough for most cases.
189 Keyword repeat is used to indicate the number of consecutive
191 runs to perform. Note that output data and context printed to
192 files correspond to the last of those runs. The duration
193 printed out at the end of the runs is an average over all
194 runs performed by the command.
195 Not all program types support test run. Among those which do,
197 not all of them can take the ctx_in/ctx_out arguments.
198 bpftool does not perform checks on program types.
199 bpftool prog profile PROG [duration DURATION] METRICs
201 Profile METRICs for bpf program PROG for DURATION seconds or
202 until user hits <Ctrl+C>. DURATION is optional. If DURATION
203 is not specified, the profiling will run up to UINT_MAX sec‐
204 onds.
205 bpftool prog help
207 Print short help message.
208
210 -h, --help
211 Print short help message (similar to bpftool help).
212 -V, --version
214 Print bpftool's version number (similar to bpftool version),
215 the number of the libbpf version in use, and optional fea‐
216 tures that were included when bpftool was compiled. Optional
217 features include linking against libbfd to provide the disas‐
218 sembler for JIT-ted programs (bpftool prog dump jited) and
219 usage of BPF skeletons (some features like bpftool prog pro‐
220 file or showing pids associated to BPF objects may rely on
221 it).
222 -j, --json
224 Generate JSON output. For commands that cannot produce JSON,
225 this option has no effect.
226 -p, --pretty
228 Generate human-readable JSON output. Implies -j.
229 -d, --debug
231 Print all logs available, even debug-level information. This
232 includes logs from libbpf as well as from the verifier, when
233 attempting to load programs.
234 -l, --legacy
236 Use legacy libbpf mode which has more relaxed BPF program re‐
237 quirements. By default, bpftool has more strict requirements
238 about section names, changes pinning logic and doesn't sup‐
239 port some of the older non-BTF map declarations.
240 See
242 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
243 for details.
244 -f, --bpffs
246 When showing BPF programs, show file names of pinned pro‐
247 grams.
248 -m, --mapcompat
250 Allow loading maps with unknown map definitions.
251 -n, --nomount
253 Do not automatically attempt to mount any virtual file system
254 (such as tracefs or BPF virtual file system) when necessary.
255 -L, --use-loader
257 Load program as a "loader" program. This is useful to debug
258 the generation of such programs. When this option is in use,
259 bpftool attempts to load the programs from the object file
260 into the kernel, but does not pin them (therefore, the PATH
261 must not be provided).
262 When combined with the -d|--debug option, additional debug
264 messages are generated, and the execution of the loader pro‐
265 gram will use the bpf_trace_printk() helper to log each step
266 of loading BTF, creating the maps, and loading the programs
267 (see bpftool prog tracelog as a way to dump those messages).
268
270 # bpftool prog show
271 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
273 loaded_at 2017-09-29T20:11:00+0000 uid 0
274 xlated 528B jited 370B memlock 4096B map_ids 10
275 pids systemd(1)
276 # bpftool --json --pretty prog show
278 [{
280 "id": 10,
281 "type": "xdp",
282 "tag": "005a3d2123620c8b",
283 "gpl_compatible": true,
284 "run_time_ns": 81632,
285 "run_cnt": 10,
286 "loaded_at": 1506715860,
287 "uid": 0,
288 "bytes_xlated": 528,
289 "jited": true,
290 "bytes_jited": 370,
291 "bytes_memlock": 4096,
292 "map_ids": [10
293 ],
294 "pids": [{
295 "pid": 1,
296 "comm": "systemd"
297 }
298 ]
299 }
300 ]
301 # bpftool prog dump xlated id 10 file /tmp/t
303 $ ls -l /tmp/t
304 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
307 # bpftool prog dump jited tag 005a3d2123620c8b
309 0: push %rbp
311 1: mov %rsp,%rbp
312 2: sub $0x228,%rsp
313 3: sub $0x28,%rbp
314 4: mov %rbx,0x0(%rbp)
315 # mount -t bpf none /sys/fs/bpf/
317 # bpftool prog pin id 10 /sys/fs/bpf/prog
318 # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
319 # ls -l /sys/fs/bpf/
320 -rw------- 1 root root 0 Jul 22 01:43 prog
323 -rw------- 1 root root 0 Jul 22 01:44 prog2
324 # bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
326 0: push %rbp
328 55
329 1: mov %rsp,%rbp
330 48 89 e5
331 4: sub $0x228,%rsp
332 48 81 ec 28 02 00 00
333 b: sub $0x28,%rbp
334 48 83 ed 28
335 f: mov %rbx,0x0(%rbp)
336 48 89 5d 00
337 # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
339 # bpftool prog show pinned /sys/fs/bpf/xdp1
340 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
343 loaded_at 2018-06-25T16:17:31-0700 uid 0
344 xlated 488B jited 336B memlock 4096B map_ids 7
345 # rm /sys/fs/bpf/xdp1
347 # bpftool prog profile id 337 duration 10 cycles instructions llc_misses
349 51397 run_cnt
352 40176203 cycles (83.05%)
353 42518139 instructions # 1.06 insns per cycle (83.39%)
354 123 llc_misses # 2.89 LLC misses per million insns (83.15%)
355 Output below is for the trace logs.
357 Run in separate terminals:
358 # bpftool prog tracelog
359 # bpftool prog load -L -d file.o
360 bpftool-620059 [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
363 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
364 bpftool-620059 [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
365 bpftool-620059 [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0
366
368 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
369 bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8),
370 bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8),
371 bpftool-perf(8), bpftool-struct_ops(8)
372 BPFTOOL-PROG(8)