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** }] | { **-f** | **--bpffs** } }
  16
  17         *COMMANDS* :=
  18         { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load** | **help** }
  19
  20 MAP COMMANDS
  21 =============
  22
  23 |       **bpftool** **prog { show | list }** [*PROG*]
  24 |       **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual**}]
  25 |       **bpftool** **prog dump jited**  *PROG* [{**file** *FILE* | **opcodes**}]
  26 |       **bpftool** **prog pin** *PROG* *FILE*
  27 |       **bpftool** **prog load** *OBJ* *FILE* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*]
  28 |       **bpftool** **prog help**
  29 |
  30 |       *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
  31 |       *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
  32 |       *TYPE* := {
  33 |               **socket** | **kprobe** | **kretprobe** | **classifier** | **action** |
  34 |               **tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** |
  35 |               **cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** |
  36 |               **lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** |
  37 |               **cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** |
  38 |               **cgroup/connect4** | **cgroup/connect6** | **cgroup/sendmsg4** | **cgroup/sendmsg6**
  39 |       }
  40
  41
  42 DESCRIPTION
  43 ===========
  44         **bpftool prog { show | list }** [*PROG*]
  45                   Show information about loaded programs.  If *PROG* is
  46                   specified show information only about given program, otherwise
  47                   list all programs currently loaded on the system.
  48
  49                   Output will start with program ID followed by program type and
  50                   zero or more named attributes (depending on kernel version).
  51
  52         **bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** }]
  53                   Dump eBPF instructions of the program from the kernel. By
  54                   default, eBPF will be disassembled and printed to standard
  55                   output in human-readable format. In this case, **opcodes**
  56                   controls if raw opcodes should be printed as well.
  57
  58                   If **file** is specified, the binary image will instead be
  59                   written to *FILE*.
  60
  61                   If **visual** is specified, control flow graph (CFG) will be
  62                   built instead, and eBPF instructions will be presented with
  63                   CFG in DOT format, on standard output.
  64
  65         **bpftool prog dump jited**  *PROG* [{ **file** *FILE* | **opcodes** }]
  66                   Dump jited image (host machine code) of the program.
  67                   If *FILE* is specified image will be written to a file,
  68                   otherwise it will be disassembled and printed to stdout.
  69
  70                   **opcodes** controls if raw opcodes will be printed.
  71
  72         **bpftool prog pin** *PROG* *FILE*
  73                   Pin program *PROG* as *FILE*.
  74
  75                   Note: *FILE* must be located in *bpffs* mount.
  76
  77         **bpftool prog load** *OBJ* *FILE* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*]
  78                   Load bpf program from binary *OBJ* and pin as *FILE*.
  79                   **type** is optional, if not specified program type will be
  80                   inferred from section names.
  81                   By default bpftool will create new maps as declared in the ELF
  82                   object being loaded.  **map** parameter allows for the reuse
  83                   of existing maps.  It can be specified multiple times, each
  84                   time for a different map.  *IDX* refers to index of the map
  85                   to be replaced in the ELF file counting from 0, while *NAME*
  86                   allows to replace a map by name.  *MAP* specifies the map to
  87                   use, referring to it by **id** or through a **pinned** file.
  88                   If **dev** *NAME* is specified program will be loaded onto
  89                   given networking device (offload).
  90
  91                   Note: *FILE* must be located in *bpffs* mount.
  92
  93         **bpftool prog help**
  94                   Print short help message.
  95
  96 OPTIONS
  97 =======
  98         -h, --help
  99                   Print short generic help message (similar to **bpftool help**).
 100
 101         -v, --version
 102                   Print version number (similar to **bpftool version**).
 103
 104         -j, --json
 105                   Generate JSON output. For commands that cannot produce JSON, this
 106                   option has no effect.
 107
 108         -p, --pretty
 109                   Generate human-readable JSON output. Implies **-j**.
 110
 111         -f, --bpffs
 112                   Show file names of pinned programs.
 113
 114 EXAMPLES
 115 ========
 116 **# bpftool prog show**
 117 ::
 118
 119   10: xdp  name some_prog  tag 005a3d2123620c8b  gpl
 120         loaded_at Sep 29/20:11  uid 0
 121         xlated 528B  jited 370B  memlock 4096B  map_ids 10
 122
 123 **# bpftool --json --pretty prog show**
 124
 125 ::
 126
 127     {
 128         "programs": [{
 129                 "id": 10,
 130                 "type": "xdp",
 131                 "tag": "005a3d2123620c8b",
 132                 "gpl_compatible": true,
 133                 "loaded_at": "Sep 29/20:11",
 134                 "uid": 0,
 135                 "bytes_xlated": 528,
 136                 "jited": true,
 137                 "bytes_jited": 370,
 138                 "bytes_memlock": 4096,
 139                 "map_ids": [10
 140                 ]
 141             }
 142         ]
 143     }
 144
 145 |
 146 | **# bpftool prog dump xlated id 10 file /tmp/t**
 147 | **# ls -l /tmp/t**
 148 |   -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
 149
 150 **# bpftool prog dum jited tag 005a3d2123620c8b**
 151
 152 ::
 153
 154     push   %rbp
 155     mov    %rsp,%rbp
 156     sub    $0x228,%rsp
 157     sub    $0x28,%rbp
 158     mov    %rbx,0x0(%rbp)
 159
 160 |
 161 | **# mount -t bpf none /sys/fs/bpf/**
 162 | **# bpftool prog pin id 10 /sys/fs/bpf/prog**
 163 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
 164 | **# ls -l /sys/fs/bpf/**
 165 |   -rw------- 1 root root 0 Jul 22 01:43 prog
 166 |   -rw------- 1 root root 0 Jul 22 01:44 prog2
 167
 168 **# bpftool prog dum jited pinned /sys/fs/bpf/prog opcodes**
 169
 170 ::
 171
 172     push   %rbp
 173     55
 174     mov    %rsp,%rbp
 175     48 89 e5
 176     sub    $0x228,%rsp
 177     48 81 ec 28 02 00 00
 178     sub    $0x28,%rbp
 179     48 83 ed 28
 180     mov    %rbx,0x0(%rbp)
 181     48 89 5d 00
 182
 183 |
 184 | **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7**
 185 | **# bpftool prog show pinned /sys/fs/bpf/xdp1**
 186 |   9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
 187 |       loaded_at 2018-06-25T16:17:31-0700  uid 0
 188 |       xlated 488B  jited 336B  memlock 4096B  map_ids 7
 189 | **# rm /sys/fs/bpf/xdp1**
 190 |
 191
 192 SEE ALSO
 193 ========
 194         **bpftool**\ (8), **bpftool-map**\ (8), **bpftool-cgroup**\ (8)