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