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 |
14 { -f | --bpffs } | { -m | --mapcompat } | { -n | --nomount }
15 | { -L | --use-loader } }
16 COMMANDS := { show | list | dump xlated | dump jited | pin | load |
18 loadall | help }
19
21 bpftool prog { show | list } [PROG]
22 bpftool prog dump xlated PROG [{file FILE | opcodes | visual | linum}]
23 bpftool prog dump jited PROG [{file FILE | opcodes | linum}]
24 bpftool prog pin PROG FILE
25 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX | name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
26 bpftool prog attach PROG ATTACH_TYPE [MAP]
27 bpftool prog detach PROG ATTACH_TYPE [MAP]
28 bpftool prog tracelog
29 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]
30 bpftool prog profile PROG [duration DURATION] METRICs
31 bpftool prog help
32 MAP := { id MAP_ID | pinned FILE }
34 PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
35 TYPE := {
36 socket | kprobe | kretprobe | classifier | action |
37 tracepoint | raw_tracepoint | xdp | perf_event | cgroup/skb |
38 cgroup/sock | cgroup/dev | lwt_in | lwt_out | lwt_xmit |
39 lwt_seg6local | sockops | sk_skb | sk_msg | lirc_mode2 |
40 cgroup/bind4 | cgroup/bind6 | cgroup/post_bind4 | cgroup/post_bind6 |
41 cgroup/connect4 | cgroup/connect6 | cgroup/getpeername4 | cgroup/getpeername6 |
42 cgroup/getsockname4 | cgroup/getsockname6 | cgroup/sendmsg4 | cgroup/sendmsg6 |
43 cgroup/recvmsg4 | cgroup/recvmsg6 | cgroup/sysctl |
44 cgroup/getsockopt | cgroup/setsockopt | cgroup/sock_release |
45 struct_ops | fentry | fexit | freplace | sk_lookup
46 }
47 ATTACH_TYPE := {
48 msg_verdict | skb_verdict | stream_verdict | 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 version number (similar to bpftool version), and op‐
215 tional features that were included when bpftool was compiled.
216 Optional features include linking against libbfd to provide
217 the disassembler for JIT-ted programs (bpftool prog dump
218 jited) and usage of BPF skeletons (some features like bpftool
219 prog profile or showing pids associated to BPF objects may
220 rely on 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 -f, --bpffs
235 When showing BPF programs, show file names of pinned pro‐
236 grams.
237 -m, --mapcompat
239 Allow loading maps with unknown map definitions.
240 -n, --nomount
242 Do not automatically attempt to mount any virtual file system
243 (such as tracefs or BPF virtual file system) when necessary.
244 -L, --use-loader
246 Load program as a "loader" program. This is useful to debug
247 the generation of such programs. When this option is in use,
248 bpftool attempts to load the programs from the object file
249 into the kernel, but does not pin them (therefore, the PATH
250 must not be provided).
251 When combined with the -d|--debug option, additional debug
253 messages are generated, and the execution of the loader pro‐
254 gram will use the bpf_trace_printk() helper to log each step
255 of loading BTF, creating the maps, and loading the programs
256 (see bpftool prog tracelog as a way to dump those messages).
257
259 # bpftool prog show
260 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
262 loaded_at 2017-09-29T20:11:00+0000 uid 0
263 xlated 528B jited 370B memlock 4096B map_ids 10
264 pids systemd(1)
265 # bpftool --json --pretty prog show
267 [{
269 "id": 10,
270 "type": "xdp",
271 "tag": "005a3d2123620c8b",
272 "gpl_compatible": true,
273 "run_time_ns": 81632,
274 "run_cnt": 10,
275 "loaded_at": 1506715860,
276 "uid": 0,
277 "bytes_xlated": 528,
278 "jited": true,
279 "bytes_jited": 370,
280 "bytes_memlock": 4096,
281 "map_ids": [10
282 ],
283 "pids": [{
284 "pid": 1,
285 "comm": "systemd"
286 }
287 ]
288 }
289 ]
290 # bpftool prog dump xlated id 10 file /tmp/t
292 $ ls -l /tmp/t
293 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
296 # bpftool prog dump jited tag 005a3d2123620c8b
298 0: push %rbp
300 1: mov %rsp,%rbp
301 2: sub $0x228,%rsp
302 3: sub $0x28,%rbp
303 4: mov %rbx,0x0(%rbp)
304 # mount -t bpf none /sys/fs/bpf/
306 # bpftool prog pin id 10 /sys/fs/bpf/prog
307 # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
308 # ls -l /sys/fs/bpf/
309 -rw------- 1 root root 0 Jul 22 01:43 prog
312 -rw------- 1 root root 0 Jul 22 01:44 prog2
313 # bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
315 0: push %rbp
317 55
318 1: mov %rsp,%rbp
319 48 89 e5
320 4: sub $0x228,%rsp
321 48 81 ec 28 02 00 00
322 b: sub $0x28,%rbp
323 48 83 ed 28
324 f: mov %rbx,0x0(%rbp)
325 48 89 5d 00
326 # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
328 # bpftool prog show pinned /sys/fs/bpf/xdp1
329 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
332 loaded_at 2018-06-25T16:17:31-0700 uid 0
333 xlated 488B jited 336B memlock 4096B map_ids 7
334 # rm /sys/fs/bpf/xdp1
336 # bpftool prog profile id 337 duration 10 cycles instructions llc_misses
338 51397 run_cnt
341 40176203 cycles (83.05%)
342 42518139 instructions # 1.06 insns per cycle (83.39%)
343 123 llc_misses # 2.89 LLC misses per million insns (83.15%)
344 Output below is for the trace logs.
346 Run in separate terminals:
347 # bpftool prog tracelog
348 # bpftool prog load -L -d file.o
349 bpftool-620059 [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
352 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
353 bpftool-620059 [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
354 bpftool-620059 [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0
355
357 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
358 bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8),
359 bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8),
360 bpftool-perf(8), bpftool-struct_ops(8)
361 BPFTOOL-PROG(8)