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