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