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