0001 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002
0003 ================
0004 bpftool-prog
0005 ================
0006 -------------------------------------------------------------------------------
0007 tool for inspection and simple manipulation of eBPF progs
0008 -------------------------------------------------------------------------------
0009
0010 :Manual section: 8
0011
0012 .. include:: substitutions.rst
0013
0014 SYNOPSIS
0015 ========
0016
0017 **bpftool** [*OPTIONS*] **prog** *COMMAND*
0018
0019 *OPTIONS* := { |COMMON_OPTIONS| |
0020 { **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } |
0021 { **-L** | **--use-loader** } }
0022
0023 *COMMANDS* :=
0024 { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load** |
0025 **loadall** | **help** }
0026
0027 PROG COMMANDS
0028 =============
0029
0030 | **bpftool** **prog** { **show** | **list** } [*PROG*]
0031 | **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual** | **linum**}]
0032 | **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes** | **linum**}]
0033 | **bpftool** **prog pin** *PROG* *FILE*
0034 | **bpftool** **prog** { **load** | **loadall** } *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
0035 | **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
0036 | **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
0037 | **bpftool** **prog tracelog**
0038 | **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*]
0039 | **bpftool** **prog profile** *PROG* [**duration** *DURATION*] *METRICs*
0040 | **bpftool** **prog help**
0041 |
0042 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
0043 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* }
0044 | *TYPE* := {
0045 | **socket** | **kprobe** | **kretprobe** | **classifier** | **action** |
0046 | **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** |
0047 | **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** |
0048 | **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** |
0049 | **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** |
0050 | **cgroup/connect4** | **cgroup/connect6** | **cgroup/getpeername4** | **cgroup/getpeername6** |
0051 | **cgroup/getsockname4** | **cgroup/getsockname6** | **cgroup/sendmsg4** | **cgroup/sendmsg6** |
0052 | **cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/sysctl** |
0053 | **cgroup/getsockopt** | **cgroup/setsockopt** | **cgroup/sock_release** |
0054 | **struct_ops** | **fentry** | **fexit** | **freplace** | **sk_lookup**
0055 | }
0056 | *ATTACH_TYPE* := {
0057 | **sk_msg_verdict** | **sk_skb_verdict** | **sk_skb_stream_verdict** |
0058 | **sk_skb_stream_parser** | **flow_dissector**
0059 | }
0060 | *METRICs* := {
0061 | **cycles** | **instructions** | **l1d_loads** | **llc_misses** |
0062 | **itlb_misses** | **dtlb_misses**
0063 | }
0064
0065
0066 DESCRIPTION
0067 ===========
0068 **bpftool prog { show | list }** [*PROG*]
0069 Show information about loaded programs. If *PROG* is
0070 specified show information only about given programs,
0071 otherwise list all programs currently loaded on the system.
0072 In case of **tag** or **name**, *PROG* may match several
0073 programs which will all be shown.
0074
0075 Output will start with program ID followed by program type and
0076 zero or more named attributes (depending on kernel version).
0077
0078 Since Linux 5.1 the kernel can collect statistics on BPF
0079 programs (such as the total time spent running the program,
0080 and the number of times it was run). If available, bpftool
0081 shows such statistics. However, the kernel does not collect
0082 them by defaults, as it slightly impacts performance on each
0083 program run. Activation or deactivation of the feature is
0084 performed via the **kernel.bpf_stats_enabled** sysctl knob.
0085
0086 Since Linux 5.8 bpftool is able to discover information about
0087 processes that hold open file descriptors (FDs) against BPF
0088 programs. On such kernels bpftool will automatically emit this
0089 information as well.
0090
0091 **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** | **linum** }]
0092 Dump eBPF instructions of the programs from the kernel. By
0093 default, eBPF will be disassembled and printed to standard
0094 output in human-readable format. In this case, **opcodes**
0095 controls if raw opcodes should be printed as well.
0096
0097 In case of **tag** or **name**, *PROG* may match several
0098 programs which will all be dumped. However, if **file** or
0099 **visual** is specified, *PROG* must match a single program.
0100
0101 If **file** is specified, the binary image will instead be
0102 written to *FILE*.
0103
0104 If **visual** is specified, control flow graph (CFG) will be
0105 built instead, and eBPF instructions will be presented with
0106 CFG in DOT format, on standard output.
0107
0108 If the programs have line_info available, the source line will
0109 be displayed by default. If **linum** is specified,
0110 the filename, line number and line column will also be
0111 displayed on top of the source line.
0112
0113 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** | **linum** }]
0114 Dump jited image (host machine code) of the program.
0115
0116 If *FILE* is specified image will be written to a file,
0117 otherwise it will be disassembled and printed to stdout.
0118 *PROG* must match a single program when **file** is specified.
0119
0120 **opcodes** controls if raw opcodes will be printed.
0121
0122 If the prog has line_info available, the source line will
0123 be displayed by default. If **linum** is specified,
0124 the filename, line number and line column will also be
0125 displayed on top of the source line.
0126
0127 **bpftool prog pin** *PROG* *FILE*
0128 Pin program *PROG* as *FILE*.
0129
0130 Note: *FILE* must be located in *bpffs* mount. It must not
0131 contain a dot character ('.'), which is reserved for future
0132 extensions of *bpffs*.
0133
0134 **bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
0135 Load bpf program(s) from binary *OBJ* and pin as *PATH*.
0136 **bpftool prog load** pins only the first program from the
0137 *OBJ* as *PATH*. **bpftool prog loadall** pins all programs
0138 from the *OBJ* under *PATH* directory.
0139 **type** is optional, if not specified program type will be
0140 inferred from section names.
0141 By default bpftool will create new maps as declared in the ELF
0142 object being loaded. **map** parameter allows for the reuse
0143 of existing maps. It can be specified multiple times, each
0144 time for a different map. *IDX* refers to index of the map
0145 to be replaced in the ELF file counting from 0, while *NAME*
0146 allows to replace a map by name. *MAP* specifies the map to
0147 use, referring to it by **id** or through a **pinned** file.
0148 If **dev** *NAME* is specified program will be loaded onto
0149 given networking device (offload).
0150 Optional **pinmaps** argument can be provided to pin all
0151 maps under *MAP_DIR* directory.
0152
0153 Note: *PATH* must be located in *bpffs* mount. It must not
0154 contain a dot character ('.'), which is reserved for future
0155 extensions of *bpffs*.
0156
0157 **bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
0158 Attach bpf program *PROG* (with type specified by
0159 *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
0160 parameter, with the exception of *flow_dissector* which is
0161 attached to current networking name space.
0162
0163 **bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
0164 Detach bpf program *PROG* (with type specified by
0165 *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
0166 parameter, with the exception of *flow_dissector* which is
0167 detached from the current networking name space.
0168
0169 **bpftool prog tracelog**
0170 Dump the trace pipe of the system to the console (stdout).
0171 Hit <Ctrl+C> to stop printing. BPF programs can write to this
0172 trace pipe at runtime with the **bpf_trace_printk**\ () helper.
0173 This should be used only for debugging purposes. For
0174 streaming data from BPF programs to user space, one can use
0175 perf events (see also **bpftool-map**\ (8)).
0176
0177 **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*]
0178 Run BPF program *PROG* in the kernel testing infrastructure
0179 for BPF, meaning that the program works on the data and
0180 context provided by the user, and not on actual packets or
0181 monitored functions etc. Return value and duration for the
0182 test run are printed out to the console.
0183
0184 Input data is read from the *FILE* passed with **data_in**.
0185 If this *FILE* is "**-**", input data is read from standard
0186 input. Input context, if any, is read from *FILE* passed with
0187 **ctx_in**. Again, "**-**" can be used to read from standard
0188 input, but only if standard input is not already in use for
0189 input data. If a *FILE* is passed with **data_out**, output
0190 data is written to that file. Similarly, output context is
0191 written to the *FILE* passed with **ctx_out**. For both
0192 output flows, "**-**" can be used to print to the standard
0193 output (as plain text, or JSON if relevant option was
0194 passed). If output keywords are omitted, output data and
0195 context are discarded. Keywords **data_size_out** and
0196 **ctx_size_out** are used to pass the size (in bytes) for the
0197 output buffers to the kernel, although the default of 32 kB
0198 should be more than enough for most cases.
0199
0200 Keyword **repeat** is used to indicate the number of
0201 consecutive runs to perform. Note that output data and
0202 context printed to files correspond to the last of those
0203 runs. The duration printed out at the end of the runs is an
0204 average over all runs performed by the command.
0205
0206 Not all program types support test run. Among those which do,
0207 not all of them can take the **ctx_in**/**ctx_out**
0208 arguments. bpftool does not perform checks on program types.
0209
0210 **bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs*
0211 Profile *METRICs* for bpf program *PROG* for *DURATION*
0212 seconds or until user hits <Ctrl+C>. *DURATION* is optional.
0213 If *DURATION* is not specified, the profiling will run up to
0214 **UINT_MAX** seconds.
0215
0216 **bpftool prog help**
0217 Print short help message.
0218
0219 OPTIONS
0220 =======
0221 .. include:: common_options.rst
0222
0223 -f, --bpffs
0224 When showing BPF programs, show file names of pinned
0225 programs.
0226
0227 -m, --mapcompat
0228 Allow loading maps with unknown map definitions.
0229
0230 -n, --nomount
0231 Do not automatically attempt to mount any virtual file system
0232 (such as tracefs or BPF virtual file system) when necessary.
0233
0234 -L, --use-loader
0235 Load program as a "loader" program. This is useful to debug
0236 the generation of such programs. When this option is in
0237 use, bpftool attempts to load the programs from the object
0238 file into the kernel, but does not pin them (therefore, the
0239 *PATH* must not be provided).
0240
0241 When combined with the **-d**\ \|\ **--debug** option,
0242 additional debug messages are generated, and the execution
0243 of the loader program will use the **bpf_trace_printk**\ ()
0244 helper to log each step of loading BTF, creating the maps,
0245 and loading the programs (see **bpftool prog tracelog** as
0246 a way to dump those messages).
0247
0248 EXAMPLES
0249 ========
0250 **# bpftool prog show**
0251
0252 ::
0253
0254 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
0255 loaded_at 2017-09-29T20:11:00+0000 uid 0
0256 xlated 528B jited 370B memlock 4096B map_ids 10
0257 pids systemd(1)
0258
0259 **# bpftool --json --pretty prog show**
0260
0261 ::
0262
0263 [{
0264 "id": 10,
0265 "type": "xdp",
0266 "tag": "005a3d2123620c8b",
0267 "gpl_compatible": true,
0268 "run_time_ns": 81632,
0269 "run_cnt": 10,
0270 "loaded_at": 1506715860,
0271 "uid": 0,
0272 "bytes_xlated": 528,
0273 "jited": true,
0274 "bytes_jited": 370,
0275 "bytes_memlock": 4096,
0276 "map_ids": [10
0277 ],
0278 "pids": [{
0279 "pid": 1,
0280 "comm": "systemd"
0281 }
0282 ]
0283 }
0284 ]
0285
0286 |
0287 | **# bpftool prog dump xlated id 10 file /tmp/t**
0288 | **$ ls -l /tmp/t**
0289
0290 ::
0291
0292 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
0293
0294 **# bpftool prog dump jited tag 005a3d2123620c8b**
0295
0296 ::
0297
0298 0: push %rbp
0299 1: mov %rsp,%rbp
0300 2: sub $0x228,%rsp
0301 3: sub $0x28,%rbp
0302 4: mov %rbx,0x0(%rbp)
0303
0304 |
0305 | **# mount -t bpf none /sys/fs/bpf/**
0306 | **# bpftool prog pin id 10 /sys/fs/bpf/prog**
0307 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
0308 | **# ls -l /sys/fs/bpf/**
0309
0310 ::
0311
0312 -rw------- 1 root root 0 Jul 22 01:43 prog
0313 -rw------- 1 root root 0 Jul 22 01:44 prog2
0314
0315 **# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes**
0316
0317 ::
0318
0319 0: push %rbp
0320 55
0321 1: mov %rsp,%rbp
0322 48 89 e5
0323 4: sub $0x228,%rsp
0324 48 81 ec 28 02 00 00
0325 b: sub $0x28,%rbp
0326 48 83 ed 28
0327 f: mov %rbx,0x0(%rbp)
0328 48 89 5d 00
0329
0330 |
0331 | **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7**
0332 | **# bpftool prog show pinned /sys/fs/bpf/xdp1**
0333
0334 ::
0335
0336 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
0337 loaded_at 2018-06-25T16:17:31-0700 uid 0
0338 xlated 488B jited 336B memlock 4096B map_ids 7
0339
0340 **# rm /sys/fs/bpf/xdp1**
0341
0342 |
0343 | **# bpftool prog profile id 337 duration 10 cycles instructions llc_misses**
0344
0345 ::
0346
0347 51397 run_cnt
0348 40176203 cycles (83.05%)
0349 42518139 instructions # 1.06 insns per cycle (83.39%)
0350 123 llc_misses # 2.89 LLC misses per million insns (83.15%)
0351
0352 |
0353 | Output below is for the trace logs.
0354 | Run in separate terminals:
0355 | **# bpftool prog tracelog**
0356 | **# bpftool prog load -L -d file.o**
0357
0358 ::
0359
0360 bpftool-620059 [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
0361 bpftool-620059 [004] d... 2634685.517912: bpf_trace_printk: map_create sample_map idx 0 type 2 value_size 4 value_btf_id 0 r=6
0362 bpftool-620059 [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
0363 bpftool-620059 [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0
