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                   When showing BPF programs, show file names of pinned
 128                   programs.
 129
 130 EXAMPLES
 131 ========
 132 **# bpftool prog show**
 133 ::
 134
 135   10: xdp  name some_prog  tag 005a3d2123620c8b  gpl
 136         loaded_at Sep 29/20:11  uid 0
 137         xlated 528B  jited 370B  memlock 4096B  map_ids 10
 138
 139 **# bpftool --json --pretty prog show**
 140
 141 ::
 142
 143     {
 144         "programs": [{
 145                 "id": 10,
 146                 "type": "xdp",
 147                 "tag": "005a3d2123620c8b",
 148                 "gpl_compatible": true,
 149                 "loaded_at": "Sep 29/20:11",
 150                 "uid": 0,
 151                 "bytes_xlated": 528,
 152                 "jited": true,
 153                 "bytes_jited": 370,
 154                 "bytes_memlock": 4096,
 155                 "map_ids": [10
 156                 ]
 157             }
 158         ]
 159     }
 160
 161 |
 162 | **# bpftool prog dump xlated id 10 file /tmp/t**
 163 | **# ls -l /tmp/t**
 164 |   -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
 165
 166 **# bpftool prog dum jited tag 005a3d2123620c8b**
 167
 168 ::
 169
 170     push   %rbp
 171     mov    %rsp,%rbp
 172     sub    $0x228,%rsp
 173     sub    $0x28,%rbp
 174     mov    %rbx,0x0(%rbp)
 175
 176 |
 177 | **# mount -t bpf none /sys/fs/bpf/**
 178 | **# bpftool prog pin id 10 /sys/fs/bpf/prog**
 179 | **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
 180 | **# ls -l /sys/fs/bpf/**
 181 |   -rw------- 1 root root 0 Jul 22 01:43 prog
 182 |   -rw------- 1 root root 0 Jul 22 01:44 prog2
 183
 184 **# bpftool prog dum jited pinned /sys/fs/bpf/prog opcodes**
 185
 186 ::
 187
 188     push   %rbp
 189     55
 190     mov    %rsp,%rbp
 191     48 89 e5
 192     sub    $0x228,%rsp
 193     48 81 ec 28 02 00 00
 194     sub    $0x28,%rbp
 195     48 83 ed 28
 196     mov    %rbx,0x0(%rbp)
 197     48 89 5d 00
 198
 199 |
 200 | **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7**
 201 | **# bpftool prog show pinned /sys/fs/bpf/xdp1**
 202 |   9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
 203 |       loaded_at 2018-06-25T16:17:31-0700  uid 0
 204 |       xlated 488B  jited 336B  memlock 4096B  map_ids 7
 205 | **# rm /sys/fs/bpf/xdp1**
 206 |
 207
 208 SEE ALSO
 209 ========
 210         **bpf**\ (2),
 211         **bpf-helpers**\ (7),
 212         **bpftool**\ (8),
 213         **bpftool-map**\ (8),
 214         **bpftool-cgroup**\ (8),
 215         **bpftool-net**\ (8),
 216         **bpftool-perf**\ (8)