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**}] 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** }] 79 Since Linux 5.1 the kernel can collect sta !! 43 Dump eBPF instructions of the program from the kernel. 80 the total time spent running the program, !! 44 If *FILE* is specified image will be written to a file, 81 run). If available, bpftool shows such sta !! 45 otherwise it will be disassembled and printed to stdout. 82 not collect them by defaults, as it slight !! 46 83 program run. Activation or deactivation of !! 47 **opcodes** controls if raw opcodes will be printed. 84 **kernel.bpf_stats_enabled** sysctl knob. !! 48 85 !! 49 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** }] 86 Since Linux 5.8 bpftool is able to discove !! 50 Dump jited image (host machine code) of the program. 87 that hold open file descriptors (FDs) agai !! 51 If *FILE* is specified image will be written to a file, 88 bpftool will automatically emit this infor !! 52 otherwise it will be disassembled and printed to stdout. 89 !! 53 90 bpftool prog dump xlated *PROG* [{ file *FILE* !! 54 **opcodes** controls if raw opcodes will be printed. 91 Dump eBPF instructions of the programs fro !! 55 92 will be disassembled and printed to standa !! 56 **bpftool prog pin** *PROG* *FILE* 93 format. In this case, **opcodes** controls !! 57 Pin program *PROG* as *FILE*. 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 58 209 bpftool prog help !! 59 Note: *FILE* must be located in *bpffs* mount. 210 Print short help message. !! 60 >> 61 **bpftool prog load** *OBJ* *FILE* >> 62 Load bpf program from binary *OBJ* and pin as *FILE*. >> 63 >> 64 Note: *FILE* must be located in *bpffs* mount. >> 65 >> 66 **bpftool prog help** >> 67 Print short help message. 211 68 212 OPTIONS 69 OPTIONS 213 ======= 70 ======= 214 .. include:: common_options.rst !! 71 -h, --help >> 72 Print short generic help message (similar to **bpftool help**). 215 73 216 -f, --bpffs !! 74 -v, --version 217 When showing BPF programs, show file names !! 75 Print version number (similar to **bpftool version**). 218 76 219 -m, --mapcompat !! 77 -j, --json 220 Allow loading maps with unknown map defini !! 78 Generate JSON output. For commands that cannot produce JSON, this >> 79 option has no effect. 221 80 222 -n, --nomount !! 81 -p, --pretty 223 Do not automatically attempt to mount any !! 82 Generate human-readable JSON output. Implies **-j**. 224 tracefs or BPF virtual file system) when n !! 83 225 !! 84 -f, --bpffs 226 -L, --use-loader !! 85 Show file names of pinned programs. 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 86 238 EXAMPLES 87 EXAMPLES 239 ======== 88 ======== 240 **# bpftool prog show** 89 **# bpftool prog show** 241 << 242 :: 90 :: 243 91 244 10: xdp name some_prog tag 005a3d2123620 !! 92 10: xdp name some_prog tag 005a3d2123620c8b 245 loaded_at 2017-09-29T20:11:00+0000 !! 93 loaded_at Sep 29/20:11 uid 0 246 xlated 528B jited 370B memlock 4 !! 94 xlated 528B jited 370B memlock 4096B map_ids 10 247 pids systemd(1) << 248 95 249 **# bpftool --json --pretty prog show** 96 **# bpftool --json --pretty prog show** 250 97 251 :: 98 :: 252 99 253 [{ !! 100 { 254 "id": 10, !! 101 "programs": [{ 255 "type": "xdp", !! 102 "id": 10, 256 "tag": "005a3d2123620c8b", !! 103 "type": "xdp", 257 "gpl_compatible": true, !! 104 "tag": "005a3d2123620c8b", 258 "run_time_ns": 81632, !! 105 "loaded_at": "Sep 29/20:11", 259 "run_cnt": 10, !! 106 "uid": 0, 260 "loaded_at": 1506715860, !! 107 "bytes_xlated": 528, 261 "uid": 0, !! 108 "jited": true, 262 "bytes_xlated": 528, !! 109 "bytes_jited": 370, 263 "jited": true, !! 110 "bytes_memlock": 4096, 264 "bytes_jited": 370, !! 111 "map_ids": [10 265 "bytes_memlock": 4096, !! 112 ] 266 "map_ids": [10 !! 113 } 267 ], !! 114 ] 268 "pids": [{ !! 115 } 269 "pid": 1, << 270 "comm": "systemd" << 271 } << 272 ] << 273 } << 274 ] << 275 116 276 | 117 | 277 | **# bpftool prog dump xlated id 10 file /tmp 118 | **# bpftool prog dump xlated id 10 file /tmp/t** 278 | **$ ls -l /tmp/t** !! 119 | **# ls -l /tmp/t** >> 120 | -rw------- 1 root root 560 Jul 22 01:42 /tmp/t 279 121 280 :: !! 122 **# bpftool prog dum jited tag 005a3d2123620c8b** 281 << 282 -rw------- 1 root root 560 Jul 22 01:42 /t << 283 << 284 **# bpftool prog dump jited tag 005a3d2123620c << 285 123 286 :: 124 :: 287 125 288 0: push %rbp !! 126 push %rbp 289 1: mov %rsp,%rbp !! 127 mov %rsp,%rbp 290 2: sub $0x228,%rsp !! 128 sub $0x228,%rsp 291 3: sub $0x28,%rbp !! 129 sub $0x28,%rbp 292 4: mov %rbx,0x0(%rbp) !! 130 mov %rbx,0x0(%rbp) 293 131 294 | 132 | 295 | **# mount -t bpf none /sys/fs/bpf/** 133 | **# mount -t bpf none /sys/fs/bpf/** 296 | **# bpftool prog pin id 10 /sys/fs/bpf/prog* 134 | **# bpftool prog pin id 10 /sys/fs/bpf/prog** 297 | **# bpftool prog load ./my_prog.o /sys/fs/bp 135 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2** 298 | **# ls -l /sys/fs/bpf/** 136 | **# ls -l /sys/fs/bpf/** >> 137 | -rw------- 1 root root 0 Jul 22 01:43 prog >> 138 | -rw------- 1 root root 0 Jul 22 01:44 prog2 299 139 300 :: !! 140 **# 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 141 307 :: 142 :: 308 143 309 0: push %rbp !! 144 push %rbp 310 55 !! 145 55 311 1: mov %rsp,%rbp !! 146 mov %rsp,%rbp 312 48 89 e5 !! 147 48 89 e5 313 4: sub $0x228,%rsp !! 148 sub $0x228,%rsp 314 48 81 ec 28 02 00 00 !! 149 48 81 ec 28 02 00 00 315 b: sub $0x28,%rbp !! 150 sub $0x28,%rbp 316 48 83 ed 28 !! 151 48 83 ed 28 317 f: mov %rbx,0x0(%rbp) !! 152 mov %rbx,0x0(%rbp) 318 48 89 5d 00 !! 153 48 89 5d 00 319 154 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 155 335 :: !! 156 SEE ALSO 336 !! 157 ======== 337 51397 run_cnt !! 158 **bpftool**\ (8), **bpftool-map**\ (8), **bpftool-cgroup**\ (8) 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.

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.16.18)

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.16.18)

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