1 .. SPDX-License-Identifier: (GPL-2.0-only OR B
2
3 ================
4 bpftool-prog
5 ================
6 ----------------------------------------------
7 tool for inspection and simple manipulation of
8 ----------------------------------------------
9
10 :Manual section: 8
11
12 .. include:: substitutions.rst
13
14 SYNOPSIS
15 ========
16
17 **bpftool** [*OPTIONS*] **prog** *COMMAND*
18
19 *OPTIONS* := { |COMMON_OPTIONS| |
20 { **-f** | **--bpffs** } | { **-m** | **--mapc
21 { **-L** | **--use-loader** } }
22
23 *COMMANDS* :=
24 { **show** | **list** | **dump xlated** | **du
25 **loadall** | **help** }
26
27 PROG COMMANDS
28 =============
29
30 | **bpftool** **prog** { **show** | **list** }
31 | **bpftool** **prog dump xlated** *PROG* [{ *
32 | **bpftool** **prog dump jited** *PROG* [{ *
33 | **bpftool** **prog pin** *PROG* *FILE*
34 | **bpftool** **prog** { **load** | **loadall*
35 | **bpftool** **prog attach** *PROG* *ATTACH_T
36 | **bpftool** **prog detach** *PROG* *ATTACH_T
37 | **bpftool** **prog tracelog**
38 | **bpftool** **prog run** *PROG* **data_in**
39 | **bpftool** **prog profile** *PROG* [**durat
40 | **bpftool** **prog help**
41 |
42 | *MAP* := { **id** *MAP_ID* | **pinned** *FIL
43 | *PROG* := { **id** *PROG_ID* | **pinned** *F
44 | *TYPE* := {
45 | **socket** | **kprobe** | **kretprobe**
46 | **tracepoint** | **raw_tracepoint** | **
47 | **cgroup/sock** | **cgroup/dev** | **lwt
48 | **lwt_seg6local** | **sockops** | **sk_s
49 | **cgroup/bind4** | **cgroup/bind6** | **
50 | **cgroup/connect4** | **cgroup/connect6*
51 | **cgroup/getpeername4** | **cgroup/getpe
52 | **cgroup/getsockname4** | **cgroup/getso
53 | **cgroup/sendmsg4** | **cgroup/sendmsg6*
54 | **cgroup/recvmsg4** | **cgroup/recvmsg6*
55 | **cgroup/getsockopt** | **cgroup/setsock
56 | **struct_ops** | **fentry** | **fexit**
57 | }
58 | *ATTACH_TYPE* := {
59 | **sk_msg_verdict** | **sk_skb_verdict**
60 | **sk_skb_stream_parser** | **flow_dissec
61 | }
62 | *METRICs* := {
63 | **cycles** | **instructions** | **l1d_lo
64 | **itlb_misses** | **dtlb_misses**
65 | }
66
67
68 DESCRIPTION
69 ===========
70 bpftool prog { show | list } [*PROG*]
71 Show information about loaded programs. I
72 information only about given programs, oth
73 currently loaded on the system. In case of
74 match several programs which will all be s
75
76 Output will start with program ID followed
77 named attributes (depending on kernel vers
78
79 Since Linux 5.1 the kernel can collect sta
80 the total time spent running the program,
81 run). If available, bpftool shows such sta
82 not collect them by defaults, as it slight
83 program run. Activation or deactivation of
84 **kernel.bpf_stats_enabled** sysctl knob.
85
86 Since Linux 5.8 bpftool is able to discove
87 that hold open file descriptors (FDs) agai
88 bpftool will automatically emit this infor
89
90 bpftool prog dump xlated *PROG* [{ file *FILE*
91 Dump eBPF instructions of the programs fro
92 will be disassembled and printed to standa
93 format. In this case, **opcodes** controls
94 as well.
95
96 In case of **tag** or **name**, *PROG* may
97 will all be dumped. However, if **file**
98 *PROG* must match a single program.
99
100 If **file** is specified, the binary image
101 *FILE*.
102
103 If **visual** is specified, control flow g
104 and eBPF instructions will be presented wi
105 output.
106
107 If the programs have line_info available,
108 displayed. If **linum** is specified, the
109 column will also be displayed.
110
111 bpftool prog dump jited *PROG* [{ file *FILE*
112 Dump jited image (host machine code) of th
113
114 If *FILE* is specified image will be writt
115 be disassembled and printed to stdout. *PR
116 when **file** is specified.
117
118 **opcodes** controls if raw opcodes will b
119
120 If the prog has line_info available, the s
121 **linum** is specified, the filename, line
122 be displayed.
123
124 bpftool prog pin *PROG* *FILE*
125 Pin program *PROG* as *FILE*.
126
127 Note: *FILE* must be located in *bpffs* mo
128 character ('.'), which is reserved for fut
129
130 bpftool prog { load | loadall } *OBJ* *PATH* [
131 Load bpf program(s) from binary *OBJ* and
132 load** pins only the first program from th
133 loadall** pins all programs from the *OBJ*
134 is optional, if not specified program type
135 names. By default bpftool will create new
136 object being loaded. **map** parameter al
137 maps. It can be specified multiple times,
138 *IDX* refers to index of the map to be rep
139 from 0, while *NAME* allows to replace a m
140 map to use, referring to it by **id** or t
141 **offload_dev** *NAME* is specified progra
142 networking device (offload). If **xdpmeta_
143 will become device-bound without offloadin
144 metadata. Optional **pinmaps** argument ca
145 under *MAP_DIR* directory.
146
147 If **autoattach** is specified program wil
148 case, only the link (representing the prog
149 pinned, not the program as such, so the pa
150 show -f**, only show in **bpftool link sho
151 when bpftool (libbpf) is able to infer all
152 object file, in particular, it's not suppo
153 program does not support autoattach, bpfto
154 for that program instead.
155
156 Note: *PATH* must be located in *bpffs* mo
157 character ('.'), which is reserved for fut
158
159 bpftool prog attach *PROG* *ATTACH_TYPE* [*MAP
160 Attach bpf program *PROG* (with type speci
161 *ATTACH_TYPEs* require a *MAP* parameter,
162 *flow_dissector* which is attached to curr
163
164 bpftool prog detach *PROG* *ATTACH_TYPE* [*MAP
165 Detach bpf program *PROG* (with type speci
166 *ATTACH_TYPEs* require a *MAP* parameter,
167 *flow_dissector* which is detached from th
168
169 bpftool prog tracelog
170 Dump the trace pipe of the system to the c
171 stop printing. BPF programs can write to t
172 the **bpf_trace_printk**\ () helper. This
173 purposes. For streaming data from BPF prog
174 perf events (see also **bpftool-map**\ (8)
175
176 bpftool prog run *PROG* data_in *FILE* [data_o
177 Run BPF program *PROG* in the kernel testi
178 meaning that the program works on the data
179 user, and not on actual packets or monitor
180 and duration for the test run are printed
181
182 Input data is read from the *FILE* passed
183 is "**-**", input data is read from standa
184 is read from *FILE* passed with **ctx_in**
185 read from standard input, but only if stan
186 for input data. If a *FILE* is passed with
187 written to that file. Similarly, output co
188 passed with **ctx_out**. For both output f
189 print to the standard output (as plain tex
190 passed). If output keywords are omitted, o
191 discarded. Keywords **data_size_out** and
192 the size (in bytes) for the output buffers
193 default of 32 kB should be more than enoug
194
195 Keyword **repeat** is used to indicate the
196 perform. Note that output data and context
197 the last of those runs. The duration print
198 an average over all runs performed by the
199
200 Not all program types support test run. Am
201 them can take the **ctx_in**/**ctx_out** a
202 perform checks on program types.
203
204 bpftool prog profile *PROG* [duration *DURATIO
205 Profile *METRICs* for bpf program *PROG* f
206 user hits <Ctrl+C>. *DURATION* is optional
207 the profiling will run up to **UINT_MAX**
208
209 bpftool prog help
210 Print short help message.
211
212 OPTIONS
213 =======
214 .. include:: common_options.rst
215
216 -f, --bpffs
217 When showing BPF programs, show file names
218
219 -m, --mapcompat
220 Allow loading maps with unknown map defini
221
222 -n, --nomount
223 Do not automatically attempt to mount any
224 tracefs or BPF virtual file system) when n
225
226 -L, --use-loader
227 Load program as a "loader" program. This i
228 of such programs. When this option is in u
229 programs from the object file into the ker
230 (therefore, the *PATH* must not be provide
231
232 When combined with the **-d**\ \|\ **--deb
233 messages are generated, and the execution
234 the **bpf_trace_printk**\ () helper to log
235 creating the maps, and loading the program
236 as a way to dump those messages).
237
238 EXAMPLES
239 ========
240 **# bpftool prog show**
241
242 ::
243
244 10: xdp name some_prog tag 005a3d2123620
245 loaded_at 2017-09-29T20:11:00+0000
246 xlated 528B jited 370B memlock 4
247 pids systemd(1)
248
249 **# bpftool --json --pretty prog show**
250
251 ::
252
253 [{
254 "id": 10,
255 "type": "xdp",
256 "tag": "005a3d2123620c8b",
257 "gpl_compatible": true,
258 "run_time_ns": 81632,
259 "run_cnt": 10,
260 "loaded_at": 1506715860,
261 "uid": 0,
262 "bytes_xlated": 528,
263 "jited": true,
264 "bytes_jited": 370,
265 "bytes_memlock": 4096,
266 "map_ids": [10
267 ],
268 "pids": [{
269 "pid": 1,
270 "comm": "systemd"
271 }
272 ]
273 }
274 ]
275
276 |
277 | **# bpftool prog dump xlated id 10 file /tmp
278 | **$ ls -l /tmp/t**
279
280 ::
281
282 -rw------- 1 root root 560 Jul 22 01:42 /t
283
284 **# bpftool prog dump jited tag 005a3d2123620c
285
286 ::
287
288 0: push %rbp
289 1: mov %rsp,%rbp
290 2: sub $0x228,%rsp
291 3: sub $0x28,%rbp
292 4: mov %rbx,0x0(%rbp)
293
294 |
295 | **# mount -t bpf none /sys/fs/bpf/**
296 | **# bpftool prog pin id 10 /sys/fs/bpf/prog*
297 | **# bpftool prog load ./my_prog.o /sys/fs/bp
298 | **# ls -l /sys/fs/bpf/**
299
300 ::
301
302 -rw------- 1 root root 0 Jul 22 01:43 prog
303 -rw------- 1 root root 0 Jul 22 01:44 prog
304
305 **# bpftool prog dump jited pinned /sys/fs/bpf
306
307 ::
308
309 0: push %rbp
310 55
311 1: mov %rsp,%rbp
312 48 89 e5
313 4: sub $0x228,%rsp
314 48 81 ec 28 02 00 00
315 b: sub $0x28,%rbp
316 48 83 ed 28
317 f: mov %rbx,0x0(%rbp)
318 48 89 5d 00
319
320 |
321 | **# bpftool prog load xdp1_kern.o /sys/fs/bp
322 | **# bpftool prog show pinned /sys/fs/bpf/xdp
323
324 ::
325
326 9: xdp name xdp_prog1 tag 539ec6ce11b52f
327 loaded_at 2018-06-25T16:17:31-0700
328 xlated 488B jited 336B memlock 4
329
330 **# rm /sys/fs/bpf/xdp1**
331
332 |
333 | **# bpftool prog profile id 337 duration 10
334
335 ::
336
337 51397 run_cnt
338 40176203 cycles
339 42518139 instructions # 1.06 insns
340 123 llc_misses # 2.89 LLC mi
341
342 |
343 | Output below is for the trace logs.
344 | Run in separate terminals:
345 | **# bpftool prog tracelog**
346 | **# bpftool prog load -L -d file.o**
347
348 ::
349
350 bpftool-620059 [004] d... 2634685.517903:
351 bpftool-620059 [004] d... 2634685.517912:
352 bpftool-620059 [004] d... 2634685.517997:
353 bpftool-620059 [004] d... 2634685.517999:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.