1================ 2bpftool-prog 3================ 4------------------------------------------------------------------------------- 5tool for inspection and simple manipulation of eBPF progs 6------------------------------------------------------------------------------- 7 8:Manual section: 8 9 10SYNOPSIS 11======== 12 13 **bpftool** [*OPTIONS*] **prog** *COMMAND* 14 15 *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } } 16 17 *COMMANDS* := 18 { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load** 19 | **loadall** | **help** } 20 21PROG COMMANDS 22============= 23 24| **bpftool** **prog { show | list }** [*PROG*] 25| **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual** | **linum**}] 26| **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes** | **linum**}] 27| **bpftool** **prog pin** *PROG* *FILE* 28| **bpftool** **prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*] 29| **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*] 30| **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*] 31| **bpftool** **prog tracelog** 32| **bpftool** **prog run** *PROG* **data_in** *FILE* [**data_out** *FILE* [**data_size_out** *L*]] [**ctx_in** *FILE* [**ctx_out** *FILE* [**ctx_size_out** *M*]]] [**repeat** *N*] 33| **bpftool** **prog help** 34| 35| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 36| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 37| *TYPE* := { 38| **socket** | **kprobe** | **kretprobe** | **classifier** | **action** | 39| **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** | 40| **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** | 41| **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** | 42| **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** | 43| **cgroup/connect4** | **cgroup/connect6** | **cgroup/sendmsg4** | **cgroup/sendmsg6** | 44| **cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/sysctl** | 45| **cgroup/getsockopt** | **cgroup/setsockopt** 46| } 47| *ATTACH_TYPE* := { 48| **msg_verdict** | **stream_verdict** | **stream_parser** | **flow_dissector** 49| } 50 51 52DESCRIPTION 53=========== 54 **bpftool prog { show | list }** [*PROG*] 55 Show information about loaded programs. If *PROG* is 56 specified show information only about given program, otherwise 57 list all programs currently loaded on the system. 58 59 Output will start with program ID followed by program type and 60 zero or more named attributes (depending on kernel version). 61 62 Since Linux 5.1 the kernel can collect statistics on BPF 63 programs (such as the total time spent running the program, 64 and the number of times it was run). If available, bpftool 65 shows such statistics. However, the kernel does not collect 66 them by defaults, as it slightly impacts performance on each 67 program run. Activation or deactivation of the feature is 68 performed via the **kernel.bpf_stats_enabled** sysctl knob. 69 70 **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** | **linum** }] 71 Dump eBPF instructions of the program from the kernel. By 72 default, eBPF will be disassembled and printed to standard 73 output in human-readable format. In this case, **opcodes** 74 controls if raw opcodes should be printed as well. 75 76 If **file** is specified, the binary image will instead be 77 written to *FILE*. 78 79 If **visual** is specified, control flow graph (CFG) will be 80 built instead, and eBPF instructions will be presented with 81 CFG in DOT format, on standard output. 82 83 If the prog has line_info available, the source line will 84 be displayed by default. If **linum** is specified, 85 the filename, line number and line column will also be 86 displayed on top of the source line. 87 88 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** | **linum** }] 89 Dump jited image (host machine code) of the program. 90 If *FILE* is specified image will be written to a file, 91 otherwise it will be disassembled and printed to stdout. 92 93 **opcodes** controls if raw opcodes will be printed. 94 95 If the prog has line_info available, the source line will 96 be displayed by default. If **linum** is specified, 97 the filename, line number and line column will also be 98 displayed on top of the source line. 99 100 **bpftool prog pin** *PROG* *FILE* 101 Pin program *PROG* as *FILE*. 102 103 Note: *FILE* must be located in *bpffs* mount. It must not 104 contain a dot character ('.'), which is reserved for future 105 extensions of *bpffs*. 106 107 **bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*] 108 Load bpf program(s) from binary *OBJ* and pin as *PATH*. 109 **bpftool prog load** pins only the first program from the 110 *OBJ* as *PATH*. **bpftool prog loadall** pins all programs 111 from the *OBJ* under *PATH* directory. 112 **type** is optional, if not specified program type will be 113 inferred from section names. 114 By default bpftool will create new maps as declared in the ELF 115 object being loaded. **map** parameter allows for the reuse 116 of existing maps. It can be specified multiple times, each 117 time for a different map. *IDX* refers to index of the map 118 to be replaced in the ELF file counting from 0, while *NAME* 119 allows to replace a map by name. *MAP* specifies the map to 120 use, referring to it by **id** or through a **pinned** file. 121 If **dev** *NAME* is specified program will be loaded onto 122 given networking device (offload). 123 Optional **pinmaps** argument can be provided to pin all 124 maps under *MAP_DIR* directory. 125 126 Note: *PATH* must be located in *bpffs* mount. It must not 127 contain a dot character ('.'), which is reserved for future 128 extensions of *bpffs*. 129 130 **bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*] 131 Attach bpf program *PROG* (with type specified by 132 *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP* 133 parameter, with the exception of *flow_dissector* which is 134 attached to current networking name space. 135 136 **bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*] 137 Detach bpf program *PROG* (with type specified by 138 *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP* 139 parameter, with the exception of *flow_dissector* which is 140 detached from the current networking name space. 141 142 **bpftool prog tracelog** 143 Dump the trace pipe of the system to the console (stdout). 144 Hit <Ctrl+C> to stop printing. BPF programs can write to this 145 trace pipe at runtime with the **bpf_trace_printk()** helper. 146 This should be used only for debugging purposes. For 147 streaming data from BPF programs to user space, one can use 148 perf events (see also **bpftool-map**\ (8)). 149 150 **bpftool prog run** *PROG* **data_in** *FILE* [**data_out** *FILE* [**data_size_out** *L*]] [**ctx_in** *FILE* [**ctx_out** *FILE* [**ctx_size_out** *M*]]] [**repeat** *N*] 151 Run BPF program *PROG* in the kernel testing infrastructure 152 for BPF, meaning that the program works on the data and 153 context provided by the user, and not on actual packets or 154 monitored functions etc. Return value and duration for the 155 test run are printed out to the console. 156 157 Input data is read from the *FILE* passed with **data_in**. 158 If this *FILE* is "**-**", input data is read from standard 159 input. Input context, if any, is read from *FILE* passed with 160 **ctx_in**. Again, "**-**" can be used to read from standard 161 input, but only if standard input is not already in use for 162 input data. If a *FILE* is passed with **data_out**, output 163 data is written to that file. Similarly, output context is 164 written to the *FILE* passed with **ctx_out**. For both 165 output flows, "**-**" can be used to print to the standard 166 output (as plain text, or JSON if relevant option was 167 passed). If output keywords are omitted, output data and 168 context are discarded. Keywords **data_size_out** and 169 **ctx_size_out** are used to pass the size (in bytes) for the 170 output buffers to the kernel, although the default of 32 kB 171 should be more than enough for most cases. 172 173 Keyword **repeat** is used to indicate the number of 174 consecutive runs to perform. Note that output data and 175 context printed to files correspond to the last of those 176 runs. The duration printed out at the end of the runs is an 177 average over all runs performed by the command. 178 179 Not all program types support test run. Among those which do, 180 not all of them can take the **ctx_in**/**ctx_out** 181 arguments. bpftool does not perform checks on program types. 182 183 **bpftool prog help** 184 Print short help message. 185 186OPTIONS 187======= 188 -h, --help 189 Print short generic help message (similar to **bpftool help**). 190 191 -V, --version 192 Print version number (similar to **bpftool version**). 193 194 -j, --json 195 Generate JSON output. For commands that cannot produce JSON, this 196 option has no effect. 197 198 -p, --pretty 199 Generate human-readable JSON output. Implies **-j**. 200 201 -f, --bpffs 202 When showing BPF programs, show file names of pinned 203 programs. 204 205 -m, --mapcompat 206 Allow loading maps with unknown map definitions. 207 208 -n, --nomount 209 Do not automatically attempt to mount any virtual file system 210 (such as tracefs or BPF virtual file system) when necessary. 211 212 -d, --debug 213 Print all logs available, even debug-level information. This 214 includes logs from libbpf as well as from the verifier, when 215 attempting to load programs. 216 217EXAMPLES 218======== 219**# bpftool prog show** 220 221:: 222 223 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10 224 loaded_at 2017-09-29T20:11:00+0000 uid 0 225 xlated 528B jited 370B memlock 4096B map_ids 10 226 227**# bpftool --json --pretty prog show** 228 229:: 230 231 [{ 232 "id": 10, 233 "type": "xdp", 234 "tag": "005a3d2123620c8b", 235 "gpl_compatible": true, 236 "run_time_ns": 81632, 237 "run_cnt": 10, 238 "loaded_at": 1506715860, 239 "uid": 0, 240 "bytes_xlated": 528, 241 "jited": true, 242 "bytes_jited": 370, 243 "bytes_memlock": 4096, 244 "map_ids": [10 245 ] 246 } 247 ] 248 249| 250| **# bpftool prog dump xlated id 10 file /tmp/t** 251| **# ls -l /tmp/t** 252 253:: 254 255 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t 256 257**# bpftool prog dump jited tag 005a3d2123620c8b** 258 259:: 260 261 0: push %rbp 262 1: mov %rsp,%rbp 263 2: sub $0x228,%rsp 264 3: sub $0x28,%rbp 265 4: mov %rbx,0x0(%rbp) 266 267| 268| **# mount -t bpf none /sys/fs/bpf/** 269| **# bpftool prog pin id 10 /sys/fs/bpf/prog** 270| **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2** 271| **# ls -l /sys/fs/bpf/** 272 273:: 274 275 -rw------- 1 root root 0 Jul 22 01:43 prog 276 -rw------- 1 root root 0 Jul 22 01:44 prog2 277 278**# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes** 279 280:: 281 282 0: push %rbp 283 55 284 1: mov %rsp,%rbp 285 48 89 e5 286 4: sub $0x228,%rsp 287 48 81 ec 28 02 00 00 288 b: sub $0x28,%rbp 289 48 83 ed 28 290 f: mov %rbx,0x0(%rbp) 291 48 89 5d 00 292 293| 294| **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7** 295| **# bpftool prog show pinned /sys/fs/bpf/xdp1** 296 297:: 298 299 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl 300 loaded_at 2018-06-25T16:17:31-0700 uid 0 301 xlated 488B jited 336B memlock 4096B map_ids 7 302 303**# rm /sys/fs/bpf/xdp1** 304 305SEE ALSO 306======== 307 **bpf**\ (2), 308 **bpf-helpers**\ (7), 309 **bpftool**\ (8), 310 **bpftool-map**\ (8), 311 **bpftool-cgroup**\ (8), 312 **bpftool-feature**\ (8), 313 **bpftool-net**\ (8), 314 **bpftool-perf**\ (8), 315 **bpftool-btf**\ (8) 316