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

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