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 }] | { -f | --bpffs }
13 }
14 COMMANDS := { show | list | dump xlated | dump jited | pin | load |
16 loadall | help }
17
19 bpftool prog { show | list } [PROG]
20 bpftool prog dump xlated PROG [{file FILE | opcodes | visual | linum}]
21 bpftool prog dump jited PROG [{file FILE | opcodes | linum}]
22 bpftool prog pin PROG FILE
23 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX | name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
24 bpftool prog attach PROG ATTACH_TYPE [MAP]
25 bpftool prog detach PROG ATTACH_TYPE [MAP]
26 bpftool prog tracelog
27 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]
28 bpftool prog profile PROG [duration DURATION] METRICs
29 bpftool prog help
30 MAP := { id MAP_ID | pinned FILE }
32 PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
33 TYPE := {
34 socket | kprobe | kretprobe | classifier | action |
35 tracepoint | raw_tracepoint | xdp | perf_event | cgroup/skb |
36 cgroup/sock | cgroup/dev | lwt_in | lwt_out | lwt_xmit |
37 lwt_seg6local | sockops | sk_skb | sk_msg | lirc_mode2 |
38 cgroup/bind4 | cgroup/bind6 | cgroup/post_bind4 | cgroup/post_bind6 |
39 cgroup/connect4 | cgroup/connect6 | cgroup/getpeername4 | cgroup/getpeername6 |
40 cgroup/getsockname4 | cgroup/getsockname6 | cgroup/sendmsg4 | cgroup/sendmsg6 |
41 cgroup/recvmsg4 | cgroup/recvmsg6 | cgroup/sysctl |
42 cgroup/getsockopt | cgroup/setsockopt |
43 struct_ops | fentry | fexit | freplace | sk_lookup
44 }
45 ATTACH_TYPE := {
46 msg_verdict | stream_verdict | stream_parser | flow_dissector
47 }
48 METRICs := {
49 cycles | instructions | l1d_loads | llc_misses
50 }
51
54 bpftool prog { show | list } [PROG]
55 Show information about loaded programs. If PROG is specified
56 show information only about given programs, otherwise list
57 all programs currently loaded on the system. In case of tag
58 or name, PROG may match several programs which will all be
59 shown.
60 Output will start with program ID followed by program type
62 and zero or more named attributes (depending on kernel ver‐
63 sion).
64 Since Linux 5.1 the kernel can collect statistics on BPF pro‐
66 grams (such as the total time spent running the program, and
67 the number of times it was run). If available, bpftool shows
68 such statistics. However, the kernel does not collect them by
69 defaults, as it slightly impacts performance on each program
70 run. Activation or deactivation of the feature is performed
71 via the kernel.bpf_stats_enabled sysctl knob.
72 Since Linux 5.8 bpftool is able to discover information about
74 processes that hold open file descriptors (FDs) against BPF
75 programs. On such kernels bpftool will automatically emit
76 this information as well.
77 bpftool prog dump xlated PROG [{ file FILE | opcodes | visual |
79 linum }]
80 Dump eBPF instructions of the programs from the kernel. By
81 default, eBPF will be disassembled and printed to standard
82 output in human-readable format. In this case, opcodes con‐
83 trols if raw opcodes should be printed as well.
84 In case of tag or name, PROG may match several programs which
86 will all be dumped. However, if file or visual is specified,
87 PROG must match a single program.
88 If file is specified, the binary image will instead be writ‐
90 ten to FILE.
91 If visual is specified, control flow graph (CFG) will be
93 built instead, and eBPF instructions will be presented with
94 CFG in DOT format, on standard output.
95 If the programs have line_info available, the source line
97 will be displayed by default. If linum is specified, the
98 filename, line number and line column will also be displayed
99 on top of the source line.
100 bpftool prog dump jited PROG [{ file FILE | opcodes | linum }]
102 Dump jited image (host machine code) of the program.
103 If FILE is specified image will be written to a file, other‐
105 wise it will be disassembled and printed to stdout. PROG
106 must match a single program when file is specified.
107 opcodes controls if raw opcodes will be printed.
109 If the prog has line_info available, the source line will be
111 displayed by default. If linum is specified, the filename,
112 line number and line column will also be displayed on top of
113 the source line.
114 bpftool prog pin PROG FILE
116 Pin program PROG as FILE.
117 Note: FILE must be located in bpffs mount. It must not con‐
119 tain a dot character ('.'), which is reserved for future
120 extensions of bpffs.
121 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX |
123 name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
124 Load bpf program(s) from binary OBJ and pin as PATH. bpftool
125 prog load pins only the first program from the OBJ as PATH.
126 bpftool prog loadall pins all programs from the OBJ under
127 PATH directory. type is optional, if not specified program
128 type will be inferred from section names. By default bpftool
129 will create new maps as declared in the ELF object being
130 loaded. map parameter allows for the reuse of existing maps.
131 It can be specified multiple times, each time for a different
132 map. IDX refers to index of the map to be replaced in the
133 ELF file counting from 0, while NAME allows to replace a map
134 by name. MAP specifies the map to use, referring to it by id
135 or through a pinned file. If dev NAME is specified program
136 will be loaded onto given networking device (offload).
137 Optional pinmaps argument can be provided to pin all maps
138 under MAP_DIR directory.
139 Note: PATH must be located in bpffs mount. It must not con‐
141 tain a dot character ('.'), which is reserved for future
142 extensions of bpffs.
143 bpftool prog attach PROG ATTACH_TYPE [MAP]
145 Attach bpf program PROG (with type specified by ATTACH_TYPE).
146 Most ATTACH_TYPEs require a MAP parameter, with the exception
147 of flow_dissector which is attached to current networking
148 name space.
149 bpftool prog detach PROG ATTACH_TYPE [MAP]
151 Detach bpf program PROG (with type specified by ATTACH_TYPE).
152 Most ATTACH_TYPEs require a MAP parameter, with the exception
153 of flow_dissector which is detached from the current network‐
154 ing name space.
155 bpftool prog tracelog
157 Dump the trace pipe of the system to the console (stdout).
158 Hit <Ctrl+C> to stop printing. BPF programs can write to this
159 trace pipe at runtime with the bpf_trace_printk() helper.
160 This should be used only for debugging purposes. For stream‐
161 ing data from BPF programs to user space, one can use perf
162 events (see also bpftool-map(8)).
163 bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]]
165 [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
166 Run BPF program PROG in the kernel testing infrastructure for
167 BPF, meaning that the program works on the data and context
168 provided by the user, and not on actual packets or monitored
169 functions etc. Return value and duration for the test run are
170 printed out to the console.
171 Input data is read from the FILE passed with data_in. If
173 this FILE is "-", input data is read from standard input.
174 Input context, if any, is read from FILE passed with ctx_in.
175 Again, "-" can be used to read from standard input, but only
176 if standard input is not already in use for input data. If a
177 FILE is passed with data_out, output data is written to that
178 file. Similarly, output context is written to the FILE passed
179 with ctx_out. For both output flows, "-" can be used to print
180 to the standard output (as plain text, or JSON if relevant
181 option was passed). If output keywords are omitted, output
182 data and context are discarded. Keywords data_size_out and
183 ctx_size_out are used to pass the size (in bytes) for the
184 output buffers to the kernel, although the default of 32 kB
185 should be more than enough for most cases.
186 Keyword repeat is used to indicate the number of consecutive
188 runs to perform. Note that output data and context printed to
189 files correspond to the last of those runs. The duration
190 printed out at the end of the runs is an average over all
191 runs performed by the command.
192 Not all program types support test run. Among those which do,
194 not all of them can take the ctx_in/ctx_out arguments.
195 bpftool does not perform checks on program types.
196 bpftool prog profile PROG [duration DURATION] METRICs
198 Profile METRICs for bpf program PROG for DURATION seconds or
199 until user hits <Ctrl+C>. DURATION is optional. If DURATION
200 is not specified, the profiling will run up to UINT_MAX sec‐
201 onds.
202 bpftool prog help
204 Print short help message.
205
207 -h, --help
208 Print short help message (similar to bpftool help).
209 -V, --version
211 Print version number (similar to bpftool version), and
212 optional features that were included when bpftool was com‐
213 piled. Optional features include linking against libbfd to
214 provide the disassembler for JIT-ted programs (bpftool prog
215 dump jited) and usage of BPF skeletons (some features like
216 bpftool prog profile or showing pids associated to BPF
217 objects may rely on it).
218 -j, --json
220 Generate JSON output. For commands that cannot produce JSON,
221 this option has no effect.
222 -p, --pretty
224 Generate human-readable JSON output. Implies -j.
225 -d, --debug
227 Print all logs available, even debug-level information. This
228 includes logs from libbpf as well as from the verifier, when
229 attempting to load programs.
230 -f, --bpffs
232 When showing BPF programs, show file names of pinned pro‐
233 grams.
234 -m, --mapcompat
236 Allow loading maps with unknown map definitions.
237 -n, --nomount
239 Do not automatically attempt to mount any virtual file system
240 (such as tracefs or BPF virtual file system) when necessary.
241
243 # bpftool prog show
244 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
246 loaded_at 2017-09-29T20:11:00+0000 uid 0
247 xlated 528B jited 370B memlock 4096B map_ids 10
248 pids systemd(1)
249 # bpftool --json --pretty prog show
251 [{
253 "id": 10,
254 "type": "xdp",
255 "tag": "005a3d2123620c8b",
256 "gpl_compatible": true,
257 "run_time_ns": 81632,
258 "run_cnt": 10,
259 "loaded_at": 1506715860,
260 "uid": 0,
261 "bytes_xlated": 528,
262 "jited": true,
263 "bytes_jited": 370,
264 "bytes_memlock": 4096,
265 "map_ids": [10
266 ],
267 "pids": [{
268 "pid": 1,
269 "comm": "systemd"
270 }
271 ]
272 }
273 ]
274 # bpftool prog dump xlated id 10 file /tmp/t
276 $ ls -l /tmp/t
277 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
280 # bpftool prog dump jited tag 005a3d2123620c8b
282 0: push %rbp
284 1: mov %rsp,%rbp
285 2: sub $0x228,%rsp
286 3: sub $0x28,%rbp
287 4: mov %rbx,0x0(%rbp)
288 # mount -t bpf none /sys/fs/bpf/
290 # bpftool prog pin id 10 /sys/fs/bpf/prog
291 # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
292 # ls -l /sys/fs/bpf/
293 -rw------- 1 root root 0 Jul 22 01:43 prog
296 -rw------- 1 root root 0 Jul 22 01:44 prog2
297 # bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
299 0: push %rbp
301 55
302 1: mov %rsp,%rbp
303 48 89 e5
304 4: sub $0x228,%rsp
305 48 81 ec 28 02 00 00
306 b: sub $0x28,%rbp
307 48 83 ed 28
308 f: mov %rbx,0x0(%rbp)
309 48 89 5d 00
310 # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
312 # bpftool prog show pinned /sys/fs/bpf/xdp1
313 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
316 loaded_at 2018-06-25T16:17:31-0700 uid 0
317 xlated 488B jited 336B memlock 4096B map_ids 7
318 # rm /sys/fs/bpf/xdp1
320 # bpftool prog profile id 337 duration 10 cycles instructions llc_misses
322 51397 run_cnt
325 40176203 cycles (83.05%)
326 42518139 instructions # 1.06 insns per cycle (83.39%)
327 123 llc_misses # 2.89 LLC misses per million insns (83.15%)
328
330 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
331 bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8),
332 bpftool-iter(8), bpftool-link(8), bpftool-map(8), bpftool-net(8),
333 bpftool-perf(8), bpftool-struct_ops(8)
334 BPFTOOL-PROG(8)