Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

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* 35 | **bpftool** **prog attach** *PROG* *ATTACH_T !! 28 | **bpftool** **prog help** 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 | 29 | 42 | *MAP* := { **id** *MAP_ID* | **pinned** *FIL !! 30 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 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 31 68 DESCRIPTION 32 DESCRIPTION 69 =========== 33 =========== 70 bpftool prog { show | list } [*PROG*] !! 34 **bpftool prog { show | list }** [*PROG*] 71 Show information about loaded programs. I !! 35 Show information about loaded programs. If *PROG* is 72 information only about given programs, oth !! 36 specified show information only about given program, otherwise 73 currently loaded on the system. In case of !! 37 list all programs currently loaded on the system. 74 match several programs which will all be s !! 38 75 !! 39 Output will start with program ID followed by program type and 76 Output will start with program ID followed !! 40 zero or more named attributes (depending on kernel version). 77 named attributes (depending on kernel vers !! 41 78 !! 42 **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** }] 79 Since Linux 5.1 the kernel can collect sta !! 43 Dump eBPF instructions of the program from the kernel. By 80 the total time spent running the program, !! 44 default, eBPF will be disassembled and printed to standard 81 run). If available, bpftool shows such sta !! 45 output in human-readable format. In this case, **opcodes** 82 not collect them by defaults, as it slight !! 46 controls if raw opcodes should be printed as well. 83 program run. Activation or deactivation of !! 47 84 **kernel.bpf_stats_enabled** sysctl knob. !! 48 If **file** is specified, the binary image will instead be 85 !! 49 written to *FILE*. 86 Since Linux 5.8 bpftool is able to discove !! 50 87 that hold open file descriptors (FDs) agai !! 51 If **visual** is specified, control flow graph (CFG) will be 88 bpftool will automatically emit this infor !! 52 built instead, and eBPF instructions will be presented with 89 !! 53 CFG in DOT format, on standard output. 90 bpftool prog dump xlated *PROG* [{ file *FILE* !! 54 91 Dump eBPF instructions of the programs fro !! 55 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** }] 92 will be disassembled and printed to standa !! 56 Dump jited image (host machine code) of the program. 93 format. In this case, **opcodes** controls !! 57 If *FILE* is specified image will be written to a file, 94 as well. !! 58 otherwise it will be disassembled and printed to stdout. 95 !! 59 96 In case of **tag** or **name**, *PROG* may !! 60 **opcodes** controls if raw opcodes will be printed. 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 61 209 bpftool prog help !! 62 **bpftool prog pin** *PROG* *FILE* 210 Print short help message. !! 63 Pin program *PROG* as *FILE*. >> 64 >> 65 Note: *FILE* must be located in *bpffs* mount. >> 66 >> 67 **bpftool prog load** *OBJ* *FILE* >> 68 Load bpf program from binary *OBJ* and pin as *FILE*. >> 69 >> 70 Note: *FILE* must be located in *bpffs* mount. >> 71 >> 72 **bpftool prog help** >> 73 Print short help message. 211 74 212 OPTIONS 75 OPTIONS 213 ======= 76 ======= 214 .. include:: common_options.rst !! 77 -h, --help >> 78 Print short generic help message (similar to **bpftool help**). >> 79 >> 80 -v, --version >> 81 Print version number (similar to **bpftool version**). 215 82 216 -f, --bpffs !! 83 -j, --json 217 When showing BPF programs, show file names !! 84 Generate JSON output. For commands that cannot produce JSON, this >> 85 option has no effect. 218 86 219 -m, --mapcompat !! 87 -p, --pretty 220 Allow loading maps with unknown map defini !! 88 Generate human-readable JSON output. Implies **-j**. 221 89 222 -n, --nomount !! 90 -f, --bpffs 223 Do not automatically attempt to mount any !! 91 Show file names of pinned programs. 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 92 238 EXAMPLES 93 EXAMPLES 239 ======== 94 ======== 240 **# bpftool prog show** 95 **# bpftool prog show** 241 << 242 :: 96 :: 243 97 244 10: xdp name some_prog tag 005a3d2123620 !! 98 10: xdp name some_prog tag 005a3d2123620c8b 245 loaded_at 2017-09-29T20:11:00+0000 !! 99 loaded_at Sep 29/20:11 uid 0 246 xlated 528B jited 370B memlock 4 !! 100 xlated 528B jited 370B memlock 4096B map_ids 10 247 pids systemd(1) << 248 101 249 **# bpftool --json --pretty prog show** 102 **# bpftool --json --pretty prog show** 250 103 251 :: 104 :: 252 105 253 [{ !! 106 { 254 "id": 10, !! 107 "programs": [{ 255 "type": "xdp", !! 108 "id": 10, 256 "tag": "005a3d2123620c8b", !! 109 "type": "xdp", 257 "gpl_compatible": true, !! 110 "tag": "005a3d2123620c8b", 258 "run_time_ns": 81632, !! 111 "loaded_at": "Sep 29/20:11", 259 "run_cnt": 10, !! 112 "uid": 0, 260 "loaded_at": 1506715860, !! 113 "bytes_xlated": 528, 261 "uid": 0, !! 114 "jited": true, 262 "bytes_xlated": 528, !! 115 "bytes_jited": 370, 263 "jited": true, !! 116 "bytes_memlock": 4096, 264 "bytes_jited": 370, !! 117 "map_ids": [10 265 "bytes_memlock": 4096, !! 118 ] 266 "map_ids": [10 !! 119 } 267 ], !! 120 ] 268 "pids": [{ !! 121 } 269 "pid": 1, << 270 "comm": "systemd" << 271 } << 272 ] << 273 } << 274 ] << 275 122 276 | 123 | 277 | **# bpftool prog dump xlated id 10 file /tmp 124 | **# bpftool prog dump xlated id 10 file /tmp/t** 278 | **$ ls -l /tmp/t** !! 125 | **# ls -l /tmp/t** 279 !! 126 | -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 127 284 **# bpftool prog dump jited tag 005a3d2123620c !! 128 **# bpftool prog dum jited tag 005a3d2123620c8b** 285 129 286 :: 130 :: 287 131 288 0: push %rbp !! 132 push %rbp 289 1: mov %rsp,%rbp !! 133 mov %rsp,%rbp 290 2: sub $0x228,%rsp !! 134 sub $0x228,%rsp 291 3: sub $0x28,%rbp !! 135 sub $0x28,%rbp 292 4: mov %rbx,0x0(%rbp) !! 136 mov %rbx,0x0(%rbp) 293 137 294 | 138 | 295 | **# mount -t bpf none /sys/fs/bpf/** 139 | **# mount -t bpf none /sys/fs/bpf/** 296 | **# bpftool prog pin id 10 /sys/fs/bpf/prog* 140 | **# bpftool prog pin id 10 /sys/fs/bpf/prog** 297 | **# bpftool prog load ./my_prog.o /sys/fs/bp 141 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2** 298 | **# ls -l /sys/fs/bpf/** 142 | **# ls -l /sys/fs/bpf/** >> 143 | -rw------- 1 root root 0 Jul 22 01:43 prog >> 144 | -rw------- 1 root root 0 Jul 22 01:44 prog2 299 145 300 :: !! 146 **# 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 << 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 147 335 :: 148 :: 336 149 337 51397 run_cnt !! 150 push %rbp 338 40176203 cycles !! 151 55 339 42518139 instructions # 1.06 insns !! 152 mov %rsp,%rbp 340 123 llc_misses # 2.89 LLC mi !! 153 48 89 e5 >> 154 sub $0x228,%rsp >> 155 48 81 ec 28 02 00 00 >> 156 sub $0x28,%rbp >> 157 48 83 ed 28 >> 158 mov %rbx,0x0(%rbp) >> 159 48 89 5d 00 341 160 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 161 350 bpftool-620059 [004] d... 2634685.517903: !! 162 SEE ALSO 351 bpftool-620059 [004] d... 2634685.517912: !! 163 ======== 352 bpftool-620059 [004] d... 2634685.517997: !! 164 **bpftool**\ (8), **bpftool-map**\ (8), **bpftool-cgroup**\ (8) 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.

TOMOYO Linux Cross Reference
Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst

Diff markup

Differences between /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-6.12-rc7) and /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-4.17.19)

TOMOYO Linux Cross Reference Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst

Diff markup

Differences between /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-6.12-rc7) and /tools/bpf/bpftool/Documentation/bpftool-prog.rst (Version linux-4.17.19)

TOMOYO Linux Cross Reference
Linux/tools/bpf/bpftool/Documentation/bpftool-prog.rst