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/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*] [{ **offload_dev** | **xdpmeta_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 **offload_dev** *NAME* is specified program will be loaded
 147                   onto given networking device (offload).
 148                   If **xdpmeta_dev** *NAME* is specified program will become
 149                   device-bound without offloading, this facilitates access
 150                   to XDP metadata.
 151                   Optional **pinmaps** argument can be provided to pin all
 152                   maps under *MAP_DIR* directory.
 153
 154                   If **autoattach** is specified program will be attached
 155                   before pin. In that case, only the link (representing the
 156                   program attached to its hook) is pinned, not the program as
 157                   such, so the path won't show in **bpftool prog show -f**,
 158                   only show in **bpftool link show -f**. Also, this only works
 159                   when bpftool (libbpf) is able to infer all necessary
 160                   information from the object file, in particular, it's not
 161                   supported for all program types. If a program does not
 162                   support autoattach, bpftool falls back to regular pinning
 163                   for that program instead.
 164
 165                   Note: *PATH* must be located in *bpffs* mount. It must not
 166                   contain a dot character ('.'), which is reserved for future
 167                   extensions of *bpffs*.
 168
 169         **bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
 170                   Attach bpf program *PROG* (with type specified by
 171                   *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
 172                   parameter, with the exception of *flow_dissector* which is
 173                   attached to current networking name space.
 174
 175         **bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
 176                   Detach bpf program *PROG* (with type specified by
 177                   *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
 178                   parameter, with the exception of *flow_dissector* which is
 179                   detached from the current networking name space.
 180
 181         **bpftool prog tracelog**
 182                   Dump the trace pipe of the system to the console (stdout).
 183                   Hit <Ctrl+C> to stop printing. BPF programs can write to this
 184                   trace pipe at runtime with the **bpf_trace_printk**\ () helper.
 185                   This should be used only for debugging purposes. For
 186                   streaming data from BPF programs to user space, one can use
 187                   perf events (see also **bpftool-map**\ (8)).
 188
 189         **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*]
 190                   Run BPF program *PROG* in the kernel testing infrastructure
 191                   for BPF, meaning that the program works on the data and
 192                   context provided by the user, and not on actual packets or
 193                   monitored functions etc. Return value and duration for the
 194                   test run are printed out to the console.
 195
 196                   Input data is read from the *FILE* passed with **data_in**.
 197                   If this *FILE* is "**-**", input data is read from standard
 198                   input. Input context, if any, is read from *FILE* passed with
 199                   **ctx_in**. Again, "**-**" can be used to read from standard
 200                   input, but only if standard input is not already in use for
 201                   input data. If a *FILE* is passed with **data_out**, output
 202                   data is written to that file. Similarly, output context is
 203                   written to the *FILE* passed with **ctx_out**. For both
 204                   output flows, "**-**" can be used to print to the standard
 205                   output (as plain text, or JSON if relevant option was
 206                   passed). If output keywords are omitted, output data and
 207                   context are discarded. Keywords **data_size_out** and
 208                   **ctx_size_out** are used to pass the size (in bytes) for the
 209                   output buffers to the kernel, although the default of 32 kB
 210                   should be more than enough for most cases.
 211
 212                   Keyword **repeat** is used to indicate the number of
 213                   consecutive runs to perform. Note that output data and
 214                   context printed to files correspond to the last of those
 215                   runs. The duration printed out at the end of the runs is an
 216                   average over all runs performed by the command.
 217
 218                   Not all program types support test run. Among those which do,
 219                   not all of them can take the **ctx_in**/**ctx_out**
 220                   arguments. bpftool does not perform checks on program types.
 221
 222         **bpftool prog profile** *PROG* [**duration** *DURATION*] *METRICs*
 223                   Profile *METRICs* for bpf program *PROG* for *DURATION*
 224                   seconds or until user hits <Ctrl+C>. *DURATION* is optional.
 225                   If *DURATION* is not specified, the profiling will run up to
 226                   **UINT_MAX** seconds.
 227
 228         **bpftool prog help**
 229                   Print short help message.
 230
 231 OPTIONS
 232 =======
 233         .. include:: common_options.rst
 234
 235         -f, --bpffs
 236                   When showing BPF programs, show file names of pinned
 237                   programs.
 238
 239         -m, --mapcompat
 240                   Allow loading maps with unknown map definitions.
 241
 242         -n, --nomount
 243                   Do not automatically attempt to mount any virtual file system
 244                   (such as tracefs or BPF virtual file system) when necessary.
 245
 246         -L, --use-loader
 247                   Load program as a "loader" program. This is useful to debug
 248                   the generation of such programs. When this option is in
 249                   use, bpftool attempts to load the programs from the object
 250                   file into the kernel, but does not pin them (therefore, the
 251                   *PATH* must not be provided).
 252
 253                   When combined with the **-d**\ \|\ **--debug** option,
 254                   additional debug messages are generated, and the execution
 255                   of the loader program will use the **bpf_trace_printk**\ ()
 256                   helper to log each step of loading BTF, creating the maps,
 257                   and loading the programs (see **bpftool prog tracelog** as
 258                   a way to dump those messages).
 259
 260 EXAMPLES
 261 ========
 262 **# bpftool prog show**
 263
 264 ::
 265
 266     10: xdp  name some_prog  tag 005a3d2123620c8b  gpl run_time_ns 81632 run_cnt 10
 267             loaded_at 2017-09-29T20:11:00+0000  uid 0
 268             xlated 528B  jited 370B  memlock 4096B  map_ids 10
 269             pids systemd(1)
 270
 271 **# bpftool --json --pretty prog show**
 272
 273 ::
 274
 275     [{
 276             "id": 10,
 277             "type": "xdp",
 278             "tag": "005a3d2123620c8b",
 279             "gpl_compatible": true,
 280             "run_time_ns": 81632,
 281             "run_cnt": 10,
 282             "loaded_at": 1506715860,
 283             "uid": 0,
 284             "bytes_xlated": 528,
 285             "jited": true,
 286             "bytes_jited": 370,
 287             "bytes_memlock": 4096,
 288             "map_ids": [10
 289             ],
 290             "pids": [{
 291                     "pid": 1,
 292                     "comm": "systemd"
 293                 }
 294             ]
 295         }
 296     ]
 297
 298 |
 299 | **# bpftool prog dump xlated id 10 file /tmp/t**
 300 | **$ ls -l /tmp/t**
 301
 302 ::
 303
 304     -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
 305
 306 **# bpftool prog dump jited tag 005a3d2123620c8b**
 307
 308 ::
 309
 310     0:   push   %rbp
 311     1:   mov    %rsp,%rbp
 312     2:   sub    $0x228,%rsp
 313     3:   sub    $0x28,%rbp
 314     4:   mov    %rbx,0x0(%rbp)
 315
 316 |
 317 | **# mount -t bpf none /sys/fs/bpf/**
 318 | **# bpftool prog pin id 10 /sys/fs/bpf/prog**
 319 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
 320 | **# ls -l /sys/fs/bpf/**
 321
 322 ::
 323
 324     -rw------- 1 root root 0 Jul 22 01:43 prog
 325     -rw------- 1 root root 0 Jul 22 01:44 prog2
 326
 327 **# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes**
 328
 329 ::
 330
 331    0:   push   %rbp
 332         55
 333    1:   mov    %rsp,%rbp
 334         48 89 e5
 335    4:   sub    $0x228,%rsp
 336         48 81 ec 28 02 00 00
 337    b:   sub    $0x28,%rbp
 338         48 83 ed 28
 339    f:   mov    %rbx,0x0(%rbp)
 340         48 89 5d 00
 341
 342 |
 343 | **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7**
 344 | **# bpftool prog show pinned /sys/fs/bpf/xdp1**
 345
 346 ::
 347
 348     9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
 349             loaded_at 2018-06-25T16:17:31-0700  uid 0
 350             xlated 488B  jited 336B  memlock 4096B  map_ids 7
 351
 352 **# rm /sys/fs/bpf/xdp1**
 353
 354 |
 355 | **# bpftool prog profile id 337 duration 10 cycles instructions llc_misses**
 356
 357 ::
 358
 359          51397 run_cnt
 360       40176203 cycles                                                 (83.05%)
 361       42518139 instructions    #   1.06 insns per cycle               (83.39%)
 362            123 llc_misses      #   2.89 LLC misses per million insns  (83.15%)
 363
 364 |
 365 | Output below is for the trace logs.
 366 | Run in separate terminals:
 367 | **# bpftool prog tracelog**
 368 | **# bpftool prog load -L -d file.o**
 369
 370 ::
 371
 372     bpftool-620059  [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
 373     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
 374     bpftool-620059  [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
 375     bpftool-620059  [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0