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 <<
21 { **-L** | **--use-loader** } } <<
22 16
23 *COMMANDS* := !! 17 *COMMANDS* :=
24 { **show** | **list** | **dump xlated** | **du !! 18 { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load** | **help** }
25 **loadall** | **help** } <<
26 19
27 PROG COMMANDS !! 20 MAP COMMANDS
28 ============= 21 =============
29 22
30 | **bpftool** **prog** { **show** | **list** } !! 23 | **bpftool** **prog { show | list }** [*PROG*]
31 | **bpftool** **prog dump xlated** *PROG* [{ * !! 24 | **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual**}]
32 | **bpftool** **prog dump jited** *PROG* [{ * !! 25 | **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes**}]
33 | **bpftool** **prog pin** *PROG* *FILE* !! 26 | **bpftool** **prog pin** *PROG* *FILE*
34 | **bpftool** **prog** { **load** | **loadall* !! 27 | **bpftool** **prog load** *OBJ* *FILE* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*]
35 | **bpftool** **prog attach** *PROG* *ATTACH_T !! 28 | **bpftool** **prog attach** *PROG* *ATTACH_TYPE* *MAP*
36 | **bpftool** **prog detach** *PROG* *ATTACH_T !! 29 | **bpftool** **prog detach** *PROG* *ATTACH_TYPE* *MAP*
37 | **bpftool** **prog tracelog** !! 30 | **bpftool** **prog help**
38 | **bpftool** **prog run** *PROG* **data_in** !! 31 |
39 | **bpftool** **prog profile** *PROG* [**durat !! 32 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
40 | **bpftool** **prog help** !! 33 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
41 | !! 34 | *TYPE* := {
42 | *MAP* := { **id** *MAP_ID* | **pinned** *FIL !! 35 | **socket** | **kprobe** | **kretprobe** | **classifier** | **action** |
43 | *PROG* := { **id** *PROG_ID* | **pinned** *F !! 36 | **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** |
44 | *TYPE* := { !! 37 | **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** |
45 | **socket** | **kprobe** | **kretprobe** !! 38 | **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** |
46 | **tracepoint** | **raw_tracepoint** | ** !! 39 | **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** |
47 | **cgroup/sock** | **cgroup/dev** | **lwt !! 40 | **cgroup/connect4** | **cgroup/connect6** | **cgroup/sendmsg4** | **cgroup/sendmsg6**
48 | **lwt_seg6local** | **sockops** | **sk_s !! 41 | }
49 | **cgroup/bind4** | **cgroup/bind6** | ** !! 42 | *ATTACH_TYPE* := { **msg_verdict** | **skb_verdict** | **skb_parse** }
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 43
67 44
68 DESCRIPTION 45 DESCRIPTION
69 =========== 46 ===========
70 bpftool prog { show | list } [*PROG*] !! 47 **bpftool prog { show | list }** [*PROG*]
71 Show information about loaded programs. I !! 48 Show information about loaded programs. If *PROG* is
72 information only about given programs, oth !! 49 specified show information only about given program, otherwise
73 currently loaded on the system. In case of !! 50 list all programs currently loaded on the system.
74 match several programs which will all be s !! 51
75 !! 52 Output will start with program ID followed by program type and
76 Output will start with program ID followed !! 53 zero or more named attributes (depending on kernel version).
77 named attributes (depending on kernel vers !! 54
78 !! 55 **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** }]
79 Since Linux 5.1 the kernel can collect sta !! 56 Dump eBPF instructions of the program from the kernel. By
80 the total time spent running the program, !! 57 default, eBPF will be disassembled and printed to standard
81 run). If available, bpftool shows such sta !! 58 output in human-readable format. In this case, **opcodes**
82 not collect them by defaults, as it slight !! 59 controls if raw opcodes should be printed as well.
83 program run. Activation or deactivation of !! 60
84 **kernel.bpf_stats_enabled** sysctl knob. !! 61 If **file** is specified, the binary image will instead be
85 !! 62 written to *FILE*.
86 Since Linux 5.8 bpftool is able to discove !! 63
87 that hold open file descriptors (FDs) agai !! 64 If **visual** is specified, control flow graph (CFG) will be
88 bpftool will automatically emit this infor !! 65 built instead, and eBPF instructions will be presented with
89 !! 66 CFG in DOT format, on standard output.
90 bpftool prog dump xlated *PROG* [{ file *FILE* !! 67
91 Dump eBPF instructions of the programs fro !! 68 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** }]
92 will be disassembled and printed to standa !! 69 Dump jited image (host machine code) of the program.
93 format. In this case, **opcodes** controls !! 70 If *FILE* is specified image will be written to a file,
94 as well. !! 71 otherwise it will be disassembled and printed to stdout.
95 !! 72
96 In case of **tag** or **name**, *PROG* may !! 73 **opcodes** controls if raw opcodes will be printed.
97 will all be dumped. However, if **file** !! 74
98 *PROG* must match a single program. !! 75 **bpftool prog pin** *PROG* *FILE*
99 !! 76 Pin program *PROG* as *FILE*.
100 If **file** is specified, the binary image !! 77
101 *FILE*. !! 78 Note: *FILE* must be located in *bpffs* mount. It must not
102 !! 79 contain a dot character ('.'), which is reserved for future
103 If **visual** is specified, control flow g !! 80 extensions of *bpffs*.
104 and eBPF instructions will be presented wi !! 81
105 output. !! 82 **bpftool prog load** *OBJ* *FILE* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*]
106 !! 83 Load bpf program from binary *OBJ* and pin as *FILE*.
107 If the programs have line_info available, !! 84 **type** is optional, if not specified program type will be
108 displayed. If **linum** is specified, the !! 85 inferred from section names.
109 column will also be displayed. !! 86 By default bpftool will create new maps as declared in the ELF
110 !! 87 object being loaded. **map** parameter allows for the reuse
111 bpftool prog dump jited *PROG* [{ file *FILE* !! 88 of existing maps. It can be specified multiple times, each
112 Dump jited image (host machine code) of th !! 89 time for a different map. *IDX* refers to index of the map
113 !! 90 to be replaced in the ELF file counting from 0, while *NAME*
114 If *FILE* is specified image will be writt !! 91 allows to replace a map by name. *MAP* specifies the map to
115 be disassembled and printed to stdout. *PR !! 92 use, referring to it by **id** or through a **pinned** file.
116 when **file** is specified. !! 93 If **dev** *NAME* is specified program will be loaded onto
117 !! 94 given networking device (offload).
118 **opcodes** controls if raw opcodes will b !! 95
119 !! 96 Note: *FILE* must be located in *bpffs* mount. It must not
120 If the prog has line_info available, the s !! 97 contain a dot character ('.'), which is reserved for future
121 **linum** is specified, the filename, line !! 98 extensions of *bpffs*.
122 be displayed. !! 99
123 !! 100 **bpftool prog attach** *PROG* *ATTACH_TYPE* *MAP*
124 bpftool prog pin *PROG* *FILE* !! 101 Attach bpf program *PROG* (with type specified by *ATTACH_TYPE*)
125 Pin program *PROG* as *FILE*. !! 102 to the map *MAP*.
126 !! 103
127 Note: *FILE* must be located in *bpffs* mo !! 104 **bpftool prog detach** *PROG* *ATTACH_TYPE* *MAP*
128 character ('.'), which is reserved for fut !! 105 Detach bpf program *PROG* (with type specified by *ATTACH_TYPE*)
129 !! 106 from the map *MAP*.
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 107
209 bpftool prog help !! 108 **bpftool prog help**
210 Print short help message. !! 109 Print short help message.
211 110
212 OPTIONS 111 OPTIONS
213 ======= 112 =======
214 .. include:: common_options.rst !! 113 -h, --help
>> 114 Print short generic help message (similar to **bpftool help**).
215 115
216 -f, --bpffs !! 116 -v, --version
217 When showing BPF programs, show file names !! 117 Print version number (similar to **bpftool version**).
218 118
219 -m, --mapcompat !! 119 -j, --json
220 Allow loading maps with unknown map defini !! 120 Generate JSON output. For commands that cannot produce JSON, this
221 !! 121 option has no effect.
222 -n, --nomount !! 122
223 Do not automatically attempt to mount any !! 123 -p, --pretty
224 tracefs or BPF virtual file system) when n !! 124 Generate human-readable JSON output. Implies **-j**.
225 !! 125
226 -L, --use-loader !! 126 -f, --bpffs
227 Load program as a "loader" program. This i !! 127 When showing BPF programs, show file names of pinned
228 of such programs. When this option is in u !! 128 programs.
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 129
238 EXAMPLES 130 EXAMPLES
239 ======== 131 ========
240 **# bpftool prog show** 132 **# bpftool prog show**
241 <<
242 :: 133 ::
243 134
244 10: xdp name some_prog tag 005a3d2123620 !! 135 10: xdp name some_prog tag 005a3d2123620c8b gpl
245 loaded_at 2017-09-29T20:11:00+0000 !! 136 loaded_at Sep 29/20:11 uid 0
246 xlated 528B jited 370B memlock 4 !! 137 xlated 528B jited 370B memlock 4096B map_ids 10
247 pids systemd(1) <<
248 138
249 **# bpftool --json --pretty prog show** 139 **# bpftool --json --pretty prog show**
250 140
251 :: 141 ::
252 142
253 [{ !! 143 {
254 "id": 10, !! 144 "programs": [{
255 "type": "xdp", !! 145 "id": 10,
256 "tag": "005a3d2123620c8b", !! 146 "type": "xdp",
257 "gpl_compatible": true, !! 147 "tag": "005a3d2123620c8b",
258 "run_time_ns": 81632, !! 148 "gpl_compatible": true,
259 "run_cnt": 10, !! 149 "loaded_at": "Sep 29/20:11",
260 "loaded_at": 1506715860, !! 150 "uid": 0,
261 "uid": 0, !! 151 "bytes_xlated": 528,
262 "bytes_xlated": 528, !! 152 "jited": true,
263 "jited": true, !! 153 "bytes_jited": 370,
264 "bytes_jited": 370, !! 154 "bytes_memlock": 4096,
265 "bytes_memlock": 4096, !! 155 "map_ids": [10
266 "map_ids": [10 !! 156 ]
267 ], !! 157 }
268 "pids": [{ !! 158 ]
269 "pid": 1, !! 159 }
270 "comm": "systemd" <<
271 } <<
272 ] <<
273 } <<
274 ] <<
275 160
276 | 161 |
277 | **# bpftool prog dump xlated id 10 file /tmp 162 | **# bpftool prog dump xlated id 10 file /tmp/t**
278 | **$ ls -l /tmp/t** !! 163 | **# ls -l /tmp/t**
279 !! 164 | -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
280 :: <<
281 <<
282 -rw------- 1 root root 560 Jul 22 01:42 /t <<
283 165
284 **# bpftool prog dump jited tag 005a3d2123620c !! 166 **# bpftool prog dum jited tag 005a3d2123620c8b**
285 167
286 :: 168 ::
287 169
288 0: push %rbp !! 170 push %rbp
289 1: mov %rsp,%rbp !! 171 mov %rsp,%rbp
290 2: sub $0x228,%rsp !! 172 sub $0x228,%rsp
291 3: sub $0x28,%rbp !! 173 sub $0x28,%rbp
292 4: mov %rbx,0x0(%rbp) !! 174 mov %rbx,0x0(%rbp)
293 175
294 | 176 |
295 | **# mount -t bpf none /sys/fs/bpf/** 177 | **# mount -t bpf none /sys/fs/bpf/**
296 | **# bpftool prog pin id 10 /sys/fs/bpf/prog* 178 | **# bpftool prog pin id 10 /sys/fs/bpf/prog**
297 | **# bpftool prog load ./my_prog.o /sys/fs/bp 179 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
298 | **# ls -l /sys/fs/bpf/** 180 | **# ls -l /sys/fs/bpf/**
>> 181 | -rw------- 1 root root 0 Jul 22 01:43 prog
>> 182 | -rw------- 1 root root 0 Jul 22 01:44 prog2
299 183
300 :: !! 184 **# bpftool prog dum jited pinned /sys/fs/bpf/prog opcodes**
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 185
307 :: 186 ::
308 187
309 0: push %rbp !! 188 push %rbp
310 55 !! 189 55
311 1: mov %rsp,%rbp !! 190 mov %rsp,%rbp
312 48 89 e5 !! 191 48 89 e5
313 4: sub $0x228,%rsp !! 192 sub $0x228,%rsp
314 48 81 ec 28 02 00 00 !! 193 48 81 ec 28 02 00 00
315 b: sub $0x28,%rbp !! 194 sub $0x28,%rbp
316 48 83 ed 28 !! 195 48 83 ed 28
317 f: mov %rbx,0x0(%rbp) !! 196 mov %rbx,0x0(%rbp)
318 48 89 5d 00 !! 197 48 89 5d 00
319 198
320 | 199 |
321 | **# bpftool prog load xdp1_kern.o /sys/fs/bp 200 | **# 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 201 | **# bpftool prog show pinned /sys/fs/bpf/xdp1**
323 !! 202 | 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
324 :: !! 203 | loaded_at 2018-06-25T16:17:31-0700 uid 0
325 !! 204 | xlated 488B jited 336B memlock 4096B map_ids 7
326 9: xdp name xdp_prog1 tag 539ec6ce11b52f !! 205 | **# rm /sys/fs/bpf/xdp1**
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 | 206 |
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 207
348 :: !! 208 SEE ALSO
349 !! 209 ========
350 bpftool-620059 [004] d... 2634685.517903: !! 210 **bpf**\ (2),
351 bpftool-620059 [004] d... 2634685.517912: !! 211 **bpf-helpers**\ (7),
352 bpftool-620059 [004] d... 2634685.517997: !! 212 **bpftool**\ (8),
353 bpftool-620059 [004] d... 2634685.517999: !! 213 **bpftool-map**\ (8),
>> 214 **bpftool-cgroup**\ (8),
>> 215 **bpftool-net**\ (8),
>> 216 **bpftool-perf**\ (8)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.