1 .. SPDX-License-Identifier: (GPL-2.0-only OR B <<
2 <<
3 ================ 1 ================
4 bpftool-prog 2 bpftool-prog
5 ================ 3 ================
6 ---------------------------------------------- 4 -------------------------------------------------------------------------------
7 tool for inspection and simple manipulation of 5 tool for inspection and simple manipulation of eBPF progs
8 ---------------------------------------------- 6 -------------------------------------------------------------------------------
9 7
10 :Manual section: 8 8 :Manual section: 8
11 9
12 .. include:: substitutions.rst <<
13 <<
14 SYNOPSIS 10 SYNOPSIS
15 ======== 11 ========
16 12
17 **bpftool** [*OPTIONS*] **prog** *COMMAND* !! 13 **bpftool** [*OPTIONS*] **prog** *COMMAND*
18 14
19 *OPTIONS* := { |COMMON_OPTIONS| | !! 15 *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
20 { **-f** | **--bpffs** } | { **-m** | **--mapc !! 16
21 { **-L** | **--use-loader** } } !! 17 *COMMANDS* :=
22 !! 18 { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load**
23 *COMMANDS* := !! 19 | **loadall** | **help** }
24 { **show** | **list** | **dump xlated** | **du <<
25 **loadall** | **help** } <<
26 20
27 PROG COMMANDS 21 PROG COMMANDS
28 ============= 22 =============
29 23
30 | **bpftool** **prog** { **show** | **list** } !! 24 | **bpftool** **prog { show | list }** [*PROG*]
31 | **bpftool** **prog dump xlated** *PROG* [{ * !! 25 | **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual** | **linum**}]
32 | **bpftool** **prog dump jited** *PROG* [{ * !! 26 | **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes** | **linum**}]
33 | **bpftool** **prog pin** *PROG* *FILE* !! 27 | **bpftool** **prog pin** *PROG* *FILE*
34 | **bpftool** **prog** { **load** | **loadall* !! 28 | **bpftool** **prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
35 | **bpftool** **prog attach** *PROG* *ATTACH_T !! 29 | **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
36 | **bpftool** **prog detach** *PROG* *ATTACH_T !! 30 | **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
37 | **bpftool** **prog tracelog** !! 31 | **bpftool** **prog tracelog**
38 | **bpftool** **prog run** *PROG* **data_in** !! 32 | **bpftool** **prog help**
39 | **bpftool** **prog profile** *PROG* [**durat <<
40 | **bpftool** **prog help** <<
41 | 33 |
42 | *MAP* := { **id** *MAP_ID* | **pinned** *FIL !! 34 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
43 | *PROG* := { **id** *PROG_ID* | **pinned** *F !! 35 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
44 | *TYPE* := { !! 36 | *TYPE* := {
45 | **socket** | **kprobe** | **kretprobe** !! 37 | **socket** | **kprobe** | **kretprobe** | **classifier** | **action** |
46 | **tracepoint** | **raw_tracepoint** | ** !! 38 | **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** |
47 | **cgroup/sock** | **cgroup/dev** | **lwt !! 39 | **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** |
48 | **lwt_seg6local** | **sockops** | **sk_s !! 40 | **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** |
49 | **cgroup/bind4** | **cgroup/bind6** | ** !! 41 | **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** |
50 | **cgroup/connect4** | **cgroup/connect6* !! 42 | **cgroup/connect4** | **cgroup/connect6** | **cgroup/sendmsg4** | **cgroup/sendmsg6** |
51 | **cgroup/getpeername4** | **cgroup/getpe !! 43 | **cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/sysctl**
52 | **cgroup/getsockname4** | **cgroup/getso !! 44 | }
53 | **cgroup/sendmsg4** | **cgroup/sendmsg6* !! 45 | *ATTACH_TYPE* := {
54 | **cgroup/recvmsg4** | **cgroup/recvmsg6* !! 46 | **msg_verdict** | **stream_verdict** | **stream_parser** | **flow_dissector**
55 | **cgroup/getsockopt** | **cgroup/setsock !! 47 | }
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 48
67 49
68 DESCRIPTION 50 DESCRIPTION
69 =========== 51 ===========
70 bpftool prog { show | list } [*PROG*] !! 52 **bpftool prog { show | list }** [*PROG*]
71 Show information about loaded programs. I !! 53 Show information about loaded programs. If *PROG* is
72 information only about given programs, oth !! 54 specified show information only about given program, otherwise
73 currently loaded on the system. In case of !! 55 list all programs currently loaded on the system.
74 match several programs which will all be s !! 56
75 !! 57 Output will start with program ID followed by program type and
76 Output will start with program ID followed !! 58 zero or more named attributes (depending on kernel version).
77 named attributes (depending on kernel vers !! 59
78 !! 60 Since Linux 5.1 the kernel can collect statistics on BPF
79 Since Linux 5.1 the kernel can collect sta !! 61 programs (such as the total time spent running the program,
80 the total time spent running the program, !! 62 and the number of times it was run). If available, bpftool
81 run). If available, bpftool shows such sta !! 63 shows such statistics. However, the kernel does not collect
82 not collect them by defaults, as it slight !! 64 them by defaults, as it slightly impacts performance on each
83 program run. Activation or deactivation of !! 65 program run. Activation or deactivation of the feature is
84 **kernel.bpf_stats_enabled** sysctl knob. !! 66 performed via the **kernel.bpf_stats_enabled** sysctl knob.
85 !! 67
86 Since Linux 5.8 bpftool is able to discove !! 68 **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** | **linum** }]
87 that hold open file descriptors (FDs) agai !! 69 Dump eBPF instructions of the program from the kernel. By
88 bpftool will automatically emit this infor !! 70 default, eBPF will be disassembled and printed to standard
89 !! 71 output in human-readable format. In this case, **opcodes**
90 bpftool prog dump xlated *PROG* [{ file *FILE* !! 72 controls if raw opcodes should be printed as well.
91 Dump eBPF instructions of the programs fro !! 73
92 will be disassembled and printed to standa !! 74 If **file** is specified, the binary image will instead be
93 format. In this case, **opcodes** controls !! 75 written to *FILE*.
94 as well. !! 76
95 !! 77 If **visual** is specified, control flow graph (CFG) will be
96 In case of **tag** or **name**, *PROG* may !! 78 built instead, and eBPF instructions will be presented with
97 will all be dumped. However, if **file** !! 79 CFG in DOT format, on standard output.
98 *PROG* must match a single program. !! 80
99 !! 81 If the prog has line_info available, the source line will
100 If **file** is specified, the binary image !! 82 be displayed by default. If **linum** is specified,
101 *FILE*. !! 83 the filename, line number and line column will also be
102 !! 84 displayed on top of the source line.
103 If **visual** is specified, control flow g !! 85
104 and eBPF instructions will be presented wi !! 86 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** | **linum** }]
105 output. !! 87 Dump jited image (host machine code) of the program.
106 !! 88 If *FILE* is specified image will be written to a file,
107 If the programs have line_info available, !! 89 otherwise it will be disassembled and printed to stdout.
108 displayed. If **linum** is specified, the !! 90
109 column will also be displayed. !! 91 **opcodes** controls if raw opcodes will be printed.
110 !! 92
111 bpftool prog dump jited *PROG* [{ file *FILE* !! 93 If the prog has line_info available, the source line will
112 Dump jited image (host machine code) of th !! 94 be displayed by default. If **linum** is specified,
113 !! 95 the filename, line number and line column will also be
114 If *FILE* is specified image will be writt !! 96 displayed on top of the source line.
115 be disassembled and printed to stdout. *PR !! 97
116 when **file** is specified. !! 98 **bpftool prog pin** *PROG* *FILE*
117 !! 99 Pin program *PROG* as *FILE*.
118 **opcodes** controls if raw opcodes will b !! 100
119 !! 101 Note: *FILE* must be located in *bpffs* mount. It must not
120 If the prog has line_info available, the s !! 102 contain a dot character ('.'), which is reserved for future
121 **linum** is specified, the filename, line !! 103 extensions of *bpffs*.
122 be displayed. !! 104
123 !! 105 **bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
124 bpftool prog pin *PROG* *FILE* !! 106 Load bpf program(s) from binary *OBJ* and pin as *PATH*.
125 Pin program *PROG* as *FILE*. !! 107 **bpftool prog load** pins only the first program from the
126 !! 108 *OBJ* as *PATH*. **bpftool prog loadall** pins all programs
127 Note: *FILE* must be located in *bpffs* mo !! 109 from the *OBJ* under *PATH* directory.
128 character ('.'), which is reserved for fut !! 110 **type** is optional, if not specified program type will be
129 !! 111 inferred from section names.
130 bpftool prog { load | loadall } *OBJ* *PATH* [ !! 112 By default bpftool will create new maps as declared in the ELF
131 Load bpf program(s) from binary *OBJ* and !! 113 object being loaded. **map** parameter allows for the reuse
132 load** pins only the first program from th !! 114 of existing maps. It can be specified multiple times, each
133 loadall** pins all programs from the *OBJ* !! 115 time for a different map. *IDX* refers to index of the map
134 is optional, if not specified program type !! 116 to be replaced in the ELF file counting from 0, while *NAME*
135 names. By default bpftool will create new !! 117 allows to replace a map by name. *MAP* specifies the map to
136 object being loaded. **map** parameter al !! 118 use, referring to it by **id** or through a **pinned** file.
137 maps. It can be specified multiple times, !! 119 If **dev** *NAME* is specified program will be loaded onto
138 *IDX* refers to index of the map to be rep !! 120 given networking device (offload).
139 from 0, while *NAME* allows to replace a m !! 121 Optional **pinmaps** argument can be provided to pin all
140 map to use, referring to it by **id** or t !! 122 maps under *MAP_DIR* directory.
141 **offload_dev** *NAME* is specified progra !! 123
142 networking device (offload). If **xdpmeta_ !! 124 Note: *PATH* must be located in *bpffs* mount. It must not
143 will become device-bound without offloadin !! 125 contain a dot character ('.'), which is reserved for future
144 metadata. Optional **pinmaps** argument ca !! 126 extensions of *bpffs*.
145 under *MAP_DIR* directory. !! 127
146 !! 128 **bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
147 If **autoattach** is specified program wil !! 129 Attach bpf program *PROG* (with type specified by
148 case, only the link (representing the prog !! 130 *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
149 pinned, not the program as such, so the pa !! 131 parameter, with the exception of *flow_dissector* which is
150 show -f**, only show in **bpftool link sho !! 132 attached to current networking name space.
151 when bpftool (libbpf) is able to infer all !! 133
152 object file, in particular, it's not suppo !! 134 **bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
153 program does not support autoattach, bpfto !! 135 Detach bpf program *PROG* (with type specified by
154 for that program instead. !! 136 *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
155 !! 137 parameter, with the exception of *flow_dissector* which is
156 Note: *PATH* must be located in *bpffs* mo !! 138 detached from the current networking name space.
157 character ('.'), which is reserved for fut !! 139
158 !! 140 **bpftool prog tracelog**
159 bpftool prog attach *PROG* *ATTACH_TYPE* [*MAP !! 141 Dump the trace pipe of the system to the console (stdout).
160 Attach bpf program *PROG* (with type speci !! 142 Hit <Ctrl+C> to stop printing. BPF programs can write to this
161 *ATTACH_TYPEs* require a *MAP* parameter, !! 143 trace pipe at runtime with the **bpf_trace_printk()** helper.
162 *flow_dissector* which is attached to curr !! 144 This should be used only for debugging purposes. For
163 !! 145 streaming data from BPF programs to user space, one can use
164 bpftool prog detach *PROG* *ATTACH_TYPE* [*MAP !! 146 perf events (see also **bpftool-map**\ (8)).
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 147
209 bpftool prog help !! 148 **bpftool prog help**
210 Print short help message. !! 149 Print short help message.
211 150
212 OPTIONS 151 OPTIONS
213 ======= 152 =======
214 .. include:: common_options.rst !! 153 -h, --help
>> 154 Print short generic help message (similar to **bpftool help**).
>> 155
>> 156 -V, --version
>> 157 Print version number (similar to **bpftool version**).
215 158
216 -f, --bpffs !! 159 -j, --json
217 When showing BPF programs, show file names !! 160 Generate JSON output. For commands that cannot produce JSON, this
>> 161 option has no effect.
218 162
219 -m, --mapcompat !! 163 -p, --pretty
220 Allow loading maps with unknown map defini !! 164 Generate human-readable JSON output. Implies **-j**.
221 165
222 -n, --nomount !! 166 -f, --bpffs
223 Do not automatically attempt to mount any !! 167 When showing BPF programs, show file names of pinned
224 tracefs or BPF virtual file system) when n !! 168 programs.
225 !! 169
226 -L, --use-loader !! 170 -m, --mapcompat
227 Load program as a "loader" program. This i !! 171 Allow loading maps with unknown map definitions.
228 of such programs. When this option is in u !! 172
229 programs from the object file into the ker !! 173 -n, --nomount
230 (therefore, the *PATH* must not be provide !! 174 Do not automatically attempt to mount any virtual file system
231 !! 175 (such as tracefs or BPF virtual file system) when necessary.
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 176
238 EXAMPLES 177 EXAMPLES
239 ======== 178 ========
240 **# bpftool prog show** 179 **# bpftool prog show**
241 180
242 :: 181 ::
243 182
244 10: xdp name some_prog tag 005a3d2123620 183 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
245 loaded_at 2017-09-29T20:11:00+0000 184 loaded_at 2017-09-29T20:11:00+0000 uid 0
246 xlated 528B jited 370B memlock 4 185 xlated 528B jited 370B memlock 4096B map_ids 10
247 pids systemd(1) <<
248 186
249 **# bpftool --json --pretty prog show** 187 **# bpftool --json --pretty prog show**
250 188
251 :: 189 ::
252 190
253 [{ 191 [{
254 "id": 10, 192 "id": 10,
255 "type": "xdp", 193 "type": "xdp",
256 "tag": "005a3d2123620c8b", 194 "tag": "005a3d2123620c8b",
257 "gpl_compatible": true, 195 "gpl_compatible": true,
258 "run_time_ns": 81632, 196 "run_time_ns": 81632,
259 "run_cnt": 10, 197 "run_cnt": 10,
260 "loaded_at": 1506715860, 198 "loaded_at": 1506715860,
261 "uid": 0, 199 "uid": 0,
262 "bytes_xlated": 528, 200 "bytes_xlated": 528,
263 "jited": true, 201 "jited": true,
264 "bytes_jited": 370, 202 "bytes_jited": 370,
265 "bytes_memlock": 4096, 203 "bytes_memlock": 4096,
266 "map_ids": [10 204 "map_ids": [10
267 ], <<
268 "pids": [{ <<
269 "pid": 1, <<
270 "comm": "systemd" <<
271 } <<
272 ] 205 ]
273 } 206 }
274 ] 207 ]
275 208
276 | 209 |
277 | **# bpftool prog dump xlated id 10 file /tmp 210 | **# bpftool prog dump xlated id 10 file /tmp/t**
278 | **$ ls -l /tmp/t** !! 211 | **# ls -l /tmp/t**
279 212
280 :: 213 ::
281 214
282 -rw------- 1 root root 560 Jul 22 01:42 /t 215 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
283 216
284 **# bpftool prog dump jited tag 005a3d2123620c 217 **# bpftool prog dump jited tag 005a3d2123620c8b**
285 218
286 :: 219 ::
287 220
288 0: push %rbp 221 0: push %rbp
289 1: mov %rsp,%rbp 222 1: mov %rsp,%rbp
290 2: sub $0x228,%rsp 223 2: sub $0x228,%rsp
291 3: sub $0x28,%rbp 224 3: sub $0x28,%rbp
292 4: mov %rbx,0x0(%rbp) 225 4: mov %rbx,0x0(%rbp)
293 226
294 | 227 |
295 | **# mount -t bpf none /sys/fs/bpf/** 228 | **# mount -t bpf none /sys/fs/bpf/**
296 | **# bpftool prog pin id 10 /sys/fs/bpf/prog* 229 | **# bpftool prog pin id 10 /sys/fs/bpf/prog**
297 | **# bpftool prog load ./my_prog.o /sys/fs/bp 230 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
298 | **# ls -l /sys/fs/bpf/** 231 | **# ls -l /sys/fs/bpf/**
299 232
300 :: 233 ::
301 234
302 -rw------- 1 root root 0 Jul 22 01:43 prog 235 -rw------- 1 root root 0 Jul 22 01:43 prog
303 -rw------- 1 root root 0 Jul 22 01:44 prog 236 -rw------- 1 root root 0 Jul 22 01:44 prog2
304 237
305 **# bpftool prog dump jited pinned /sys/fs/bpf 238 **# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes**
306 239
307 :: 240 ::
308 241
309 0: push %rbp 242 0: push %rbp
310 55 243 55
311 1: mov %rsp,%rbp 244 1: mov %rsp,%rbp
312 48 89 e5 245 48 89 e5
313 4: sub $0x228,%rsp 246 4: sub $0x228,%rsp
314 48 81 ec 28 02 00 00 247 48 81 ec 28 02 00 00
315 b: sub $0x28,%rbp 248 b: sub $0x28,%rbp
316 48 83 ed 28 249 48 83 ed 28
317 f: mov %rbx,0x0(%rbp) 250 f: mov %rbx,0x0(%rbp)
318 48 89 5d 00 251 48 89 5d 00
319 252
320 | 253 |
321 | **# bpftool prog load xdp1_kern.o /sys/fs/bp 254 | **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7**
322 | **# bpftool prog show pinned /sys/fs/bpf/xdp 255 | **# bpftool prog show pinned /sys/fs/bpf/xdp1**
323 256
324 :: 257 ::
325 258
326 9: xdp name xdp_prog1 tag 539ec6ce11b52f 259 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
327 loaded_at 2018-06-25T16:17:31-0700 260 loaded_at 2018-06-25T16:17:31-0700 uid 0
328 xlated 488B jited 336B memlock 4 261 xlated 488B jited 336B memlock 4096B map_ids 7
329 262
330 **# rm /sys/fs/bpf/xdp1** 263 **# rm /sys/fs/bpf/xdp1**
331 264
332 | !! 265 SEE ALSO
333 | **# bpftool prog profile id 337 duration 10 !! 266 ========
334 !! 267 **bpf**\ (2),
335 :: !! 268 **bpf-helpers**\ (7),
336 !! 269 **bpftool**\ (8),
337 51397 run_cnt !! 270 **bpftool-map**\ (8),
338 40176203 cycles !! 271 **bpftool-cgroup**\ (8),
339 42518139 instructions # 1.06 insns !! 272 **bpftool-feature**\ (8),
340 123 llc_misses # 2.89 LLC mi !! 273 **bpftool-net**\ (8),
341 !! 274 **bpftool-perf**\ (8),
342 | !! 275 **bpftool-btf**\ (8)
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.