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

   1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2
   3 ================
   4 bpftool-prog
   5 ================
   6 -------------------------------------------------------------------------------
   7 tool for inspection and simple manipulation of eBPF progs
   8 -------------------------------------------------------------------------------
   9
  10 :Manual section: 8
  11
  12 .. include:: substitutions.rst
  13
  14 SYNOPSIS
  15 ========
  16
  17 **bpftool** [*OPTIONS*] **prog** *COMMAND*
  18
  19 *OPTIONS* := { |COMMON_OPTIONS| |
  20 { **-f** | **--bpffs** } | { **-m** | **--mapcompat** } | { **-n** | **--nomount** } |
  21 { **-L** | **--use-loader** } }
  22
  23 *COMMANDS* :=
  24 { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load** |
  25 **loadall** | **help** }
  26
  27 PROG COMMANDS
  28 =============
  29
  30 | **bpftool** **prog** { **show** | **list** } [*PROG*]
  31 | **bpftool** **prog dump xlated** *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] [**visual**] }]
  32 | **bpftool** **prog dump jited**  *PROG* [{ **file** *FILE* | [**opcodes**] [**linum**] }]
  33 | **bpftool** **prog pin** *PROG* *FILE*
  34 | **bpftool** **prog** { **load** | **loadall** } *OBJ* *PATH* [**type** *TYPE*] [**map** { **idx** *IDX* | **name** *NAME* } *MAP*] [{ **offload_dev** | **xdpmeta_dev** } *NAME*] [**pinmaps** *MAP_DIR*] [**autoattach**]
  35 | **bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
  36 | **bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
  37 | **bpftool** **prog tracelog**
  38 | **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*]
  39 | **bpftool** **prog profile** *PROG* [**duration** *DURATION*] *METRICs*
  40 | **bpftool** **prog help**
  41 |
  42 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* }
  43 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* }
  44 | *TYPE* := {
  45 |     **socket** | **kprobe** | **kretprobe** | **classifier** | **action** |
  46 |     **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** |
  47 |     **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** |
  48 |     **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** |
  49 |     **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** |
  50 |     **cgroup/connect4** | **cgroup/connect6** | **cgroup/connect_unix** |
  51 |     **cgroup/getpeername4** | **cgroup/getpeername6** | **cgroup/getpeername_unix** |
  52 |     **cgroup/getsockname4** | **cgroup/getsockname6** | **cgroup/getsockname_unix** |
  53 |     **cgroup/sendmsg4** | **cgroup/sendmsg6** | **cgroup/sendmsg_unix** |
  54 |     **cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/recvmsg_unix** | **cgroup/sysctl** |
  55 |     **cgroup/getsockopt** | **cgroup/setsockopt** | **cgroup/sock_release** |
  56 |     **struct_ops** | **fentry** | **fexit** | **freplace** | **sk_lookup**
  57 | }
  58 | *ATTACH_TYPE* := {
  59 |     **sk_msg_verdict** | **sk_skb_verdict** | **sk_skb_stream_verdict** |
  60 |     **sk_skb_stream_parser** | **flow_dissector**
  61 | }
  62 | *METRICs* := {
  63 |     **cycles** | **instructions** | **l1d_loads** | **llc_misses** |
  64 |     **itlb_misses** | **dtlb_misses**
  65 | }
  66
  67
  68 DESCRIPTION
  69 ===========
  70 bpftool prog { show | list } [*PROG*]
  71     Show information about loaded programs.  If *PROG* is specified show
  72     information only about given programs, otherwise list all programs
  73     currently loaded on the system. In case of **tag** or **name**, *PROG* may
  74     match several programs which will all be shown.
  75
  76     Output will start with program ID followed by program type and zero or more
  77     named attributes (depending on kernel version).
  78
  79     Since Linux 5.1 the kernel can collect statistics on BPF programs (such as
  80     the total time spent running the program, and the number of times it was
  81     run). If available, bpftool shows such statistics. However, the kernel does
  82     not collect them by defaults, as it slightly impacts performance on each
  83     program run. Activation or deactivation of the feature is performed via the
  84     **kernel.bpf_stats_enabled** sysctl knob.
  85
  86     Since Linux 5.8 bpftool is able to discover information about processes
  87     that hold open file descriptors (FDs) against BPF programs. On such kernels
  88     bpftool will automatically emit this information as well.
  89
  90 bpftool prog dump xlated *PROG* [{ file *FILE* | [opcodes] [linum] [visual] }]
  91     Dump eBPF instructions of the programs from the kernel. By default, eBPF
  92     will be disassembled and printed to standard output in human-readable
  93     format. In this case, **opcodes** controls if raw opcodes should be printed
  94     as well.
  95
  96     In case of **tag** or **name**, *PROG* may match several programs which
  97     will all be dumped.  However, if **file** or **visual** is specified,
  98     *PROG* must match a single program.
  99
 100     If **file** is specified, the binary image will instead be written to
 101     *FILE*.
 102
 103     If **visual** is specified, control flow graph (CFG) will be built instead,
 104     and eBPF instructions will be presented with CFG in DOT format, on standard
 105     output.
 106
 107     If the programs have line_info available, the source line will be
 108     displayed.  If **linum** is specified, the filename, line number and line
 109     column will also be displayed.
 110
 111 bpftool prog dump jited  *PROG* [{ file *FILE* | [opcodes] [linum] }]
 112     Dump jited image (host machine code) of the program.
 113
 114     If *FILE* is specified image will be written to a file, otherwise it will
 115     be disassembled and printed to stdout. *PROG* must match a single program
 116     when **file** is specified.
 117
 118     **opcodes** controls if raw opcodes will be printed.
 119
 120     If the prog has line_info available, the source line will be displayed. If
 121     **linum** is specified, the filename, line number and line column will also
 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* mount. It must not contain a dot
 128     character ('.'), which is reserved for future extensions of *bpffs*.
 129
 130 bpftool prog { load | loadall } *OBJ* *PATH* [type *TYPE*] [map { idx *IDX* | name *NAME* } *MAP*] [{ offload_dev | xdpmeta_dev } *NAME*] [pinmaps *MAP_DIR*] [autoattach]
 131     Load bpf program(s) from binary *OBJ* and pin as *PATH*. **bpftool prog
 132     load** pins only the first program from the *OBJ* as *PATH*. **bpftool prog
 133     loadall** pins all programs from the *OBJ* under *PATH* directory. **type**
 134     is optional, if not specified program type will be inferred from section
 135     names. By default bpftool will create new maps as declared in the ELF
 136     object being loaded.  **map** parameter allows for the reuse of existing
 137     maps. It can be specified multiple times, each time for a different map.
 138     *IDX* refers to index of the map to be replaced in the ELF file counting
 139     from 0, while *NAME* allows to replace a map by name. *MAP* specifies the
 140     map to use, referring to it by **id** or through a **pinned** file. If
 141     **offload_dev** *NAME* is specified program will be loaded onto given
 142     networking device (offload). If **xdpmeta_dev** *NAME* is specified program
 143     will become device-bound without offloading, this facilitates access to XDP
 144     metadata. Optional **pinmaps** argument can be provided to pin all maps
 145     under *MAP_DIR* directory.
 146
 147     If **autoattach** is specified program will be attached before pin. In that
 148     case, only the link (representing the program attached to its hook) is
 149     pinned, not the program as such, so the path won't show in **bpftool prog
 150     show -f**, only show in **bpftool link show -f**. Also, this only works
 151     when bpftool (libbpf) is able to infer all necessary information from the
 152     object file, in particular, it's not supported for all program types. If a
 153     program does not support autoattach, bpftool falls back to regular pinning
 154     for that program instead.
 155
 156     Note: *PATH* must be located in *bpffs* mount. It must not contain a dot
 157     character ('.'), which is reserved for future extensions of *bpffs*.
 158
 159 bpftool prog attach *PROG* *ATTACH_TYPE* [*MAP*]
 160     Attach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most
 161     *ATTACH_TYPEs* require a *MAP* parameter, with the exception of
 162     *flow_dissector* which is attached to current networking name space.
 163
 164 bpftool prog detach *PROG* *ATTACH_TYPE* [*MAP*]
 165     Detach bpf program *PROG* (with type specified by *ATTACH_TYPE*). Most
 166     *ATTACH_TYPEs* require a *MAP* parameter, with the exception of
 167     *flow_dissector* which is detached from the current networking name space.
 168
 169 bpftool prog tracelog
 170     Dump the trace pipe of the system to the console (stdout). Hit <Ctrl+C> to
 171     stop printing. BPF programs can write to this trace pipe at runtime with
 172     the **bpf_trace_printk**\ () helper. This should be used only for debugging
 173     purposes. For streaming data from BPF programs to user space, one can use
 174     perf events (see also **bpftool-map**\ (8)).
 175
 176 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*]
 177     Run BPF program *PROG* in the kernel testing infrastructure for BPF,
 178     meaning that the program works on the data and context provided by the
 179     user, and not on actual packets or monitored functions etc. Return value
 180     and duration for the test run are printed out to the console.
 181
 182     Input data is read from the *FILE* passed with **data_in**. If this *FILE*
 183     is "**-**", input data is read from standard input. Input context, if any,
 184     is read from *FILE* passed with **ctx_in**. Again, "**-**" can be used to
 185     read from standard input, but only if standard input is not already in use
 186     for input data. If a *FILE* is passed with **data_out**, output data is
 187     written to that file. Similarly, output context is written to the *FILE*
 188     passed with **ctx_out**. For both output flows, "**-**" can be used to
 189     print to the standard output (as plain text, or JSON if relevant option was
 190     passed). If output keywords are omitted, output data and context are
 191     discarded. Keywords **data_size_out** and **ctx_size_out** are used to pass
 192     the size (in bytes) for the output buffers to the kernel, although the
 193     default of 32 kB should be more than enough for most cases.
 194
 195     Keyword **repeat** is used to indicate the number of consecutive runs to
 196     perform. Note that output data and context printed to files correspond to
 197     the last of those runs. The duration printed out at the end of the runs is
 198     an average over all runs performed by the command.
 199
 200     Not all program types support test run. Among those which do, not all of
 201     them can take the **ctx_in**/**ctx_out** arguments. bpftool does not
 202     perform checks on program types.
 203
 204 bpftool prog profile *PROG* [duration *DURATION*] *METRICs*
 205     Profile *METRICs* for bpf program *PROG* for *DURATION* seconds or until
 206     user hits <Ctrl+C>. *DURATION* is optional. If *DURATION* is not specified,
 207     the profiling will run up to **UINT_MAX** seconds.
 208
 209 bpftool prog help
 210     Print short help message.
 211
 212 OPTIONS
 213 =======
 214 .. include:: common_options.rst
 215
 216 -f, --bpffs
 217     When showing BPF programs, show file names of pinned programs.
 218
 219 -m, --mapcompat
 220     Allow loading maps with unknown map definitions.
 221
 222 -n, --nomount
 223     Do not automatically attempt to mount any virtual file system (such as
 224     tracefs or BPF virtual file system) when necessary.
 225
 226 -L, --use-loader
 227     Load program as a "loader" program. This is useful to debug the generation
 228     of such programs. When this option is in use, bpftool attempts to load the
 229     programs from the object file into the kernel, but does not pin them
 230     (therefore, the *PATH* must not be provided).
 231
 232     When combined with the **-d**\ \|\ **--debug** option, additional debug
 233     messages are generated, and the execution of the loader program will use
 234     the **bpf_trace_printk**\ () helper to log each step of loading BTF,
 235     creating the maps, and loading the programs (see **bpftool prog tracelog**
 236     as a way to dump those messages).
 237
 238 EXAMPLES
 239 ========
 240 **# bpftool prog show**
 241
 242 ::
 243
 244     10: xdp  name some_prog  tag 005a3d2123620c8b  gpl run_time_ns 81632 run_cnt 10
 245             loaded_at 2017-09-29T20:11:00+0000  uid 0
 246             xlated 528B  jited 370B  memlock 4096B  map_ids 10
 247             pids systemd(1)
 248
 249 **# bpftool --json --pretty prog show**
 250
 251 ::
 252
 253     [{
 254             "id": 10,
 255             "type": "xdp",
 256             "tag": "005a3d2123620c8b",
 257             "gpl_compatible": true,
 258             "run_time_ns": 81632,
 259             "run_cnt": 10,
 260             "loaded_at": 1506715860,
 261             "uid": 0,
 262             "bytes_xlated": 528,
 263             "jited": true,
 264             "bytes_jited": 370,
 265             "bytes_memlock": 4096,
 266             "map_ids": [10
 267             ],
 268             "pids": [{
 269                     "pid": 1,
 270                     "comm": "systemd"
 271                 }
 272             ]
 273         }
 274     ]
 275
 276 |
 277 | **# bpftool prog dump xlated id 10 file /tmp/t**
 278 | **$ ls -l /tmp/t**
 279
 280 ::
 281
 282     -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
 283
 284 **# bpftool prog dump jited tag 005a3d2123620c8b**
 285
 286 ::
 287
 288     0:   push   %rbp
 289     1:   mov    %rsp,%rbp
 290     2:   sub    $0x228,%rsp
 291     3:   sub    $0x28,%rbp
 292     4:   mov    %rbx,0x0(%rbp)
 293
 294 |
 295 | **# mount -t bpf none /sys/fs/bpf/**
 296 | **# bpftool prog pin id 10 /sys/fs/bpf/prog**
 297 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
 298 | **# ls -l /sys/fs/bpf/**
 299
 300 ::
 301
 302     -rw------- 1 root root 0 Jul 22 01:43 prog
 303     -rw------- 1 root root 0 Jul 22 01:44 prog2
 304
 305 **# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes**
 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/bpf/xdp1 type xdp map name rxcnt id 7**
 322 | **# bpftool prog show pinned /sys/fs/bpf/xdp1**
 323
 324 ::
 325
 326     9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
 327             loaded_at 2018-06-25T16:17:31-0700  uid 0
 328             xlated 488B  jited 336B  memlock 4096B  map_ids 7
 329
 330 **# rm /sys/fs/bpf/xdp1**
 331
 332 |
 333 | **# bpftool prog profile id 337 duration 10 cycles instructions llc_misses**
 334
 335 ::
 336
 337          51397 run_cnt
 338       40176203 cycles                                                 (83.05%)
 339       42518139 instructions    #   1.06 insns per cycle               (83.39%)
 340            123 llc_misses      #   2.89 LLC misses per million insns  (83.15%)
 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: bpf_trace_printk: btf_load size 665 r=5
 351     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
 352     bpftool-620059  [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
 353     bpftool-620059  [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0