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