blob: 15e9172f7e55d015a96028a02504a83141c368c4 [file] [log] [blame]
Jakub Kicinskiff69c212017-10-04 20:10:05 -07001================
2bpftool-prog
3================
4-------------------------------------------------------------------------------
5tool for inspection and simple manipulation of eBPF progs
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
11========
12
Quentin Monnet0641c3c2017-10-23 09:24:16 -070013 **bpftool** [*OPTIONS*] **prog** *COMMAND*
14
Prashant Bholec541b732017-11-08 13:55:49 +090015 *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
Quentin Monnet0641c3c2017-10-23 09:24:16 -070016
17 *COMMANDS* :=
Stanislav Fomichev77380992018-11-09 08:21:44 -080018 { **show** | **list** | **dump xlated** | **dump jited** | **pin** | **load**
19 | **loadall** | **help** }
Quentin Monnet0641c3c2017-10-23 09:24:16 -070020
21MAP COMMANDS
22=============
23
Jakub Kicinski6ebe6db2018-01-02 14:48:36 -080024| **bpftool** **prog { show | list }** [*PROG*]
Jiong Wangb6c1ced2018-03-01 18:01:22 -080025| **bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual**}]
Quentin Monnet47ff7ac2017-10-23 09:24:15 -070026| **bpftool** **prog dump jited** *PROG* [{**file** *FILE* | **opcodes**}]
27| **bpftool** **prog pin** *PROG* *FILE*
Stanislav Fomichev77380992018-11-09 08:21:44 -080028| **bpftool** **prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*]
John Fastabendb7d38262018-10-15 11:19:50 -070029| **bpftool** **prog attach** *PROG* *ATTACH_TYPE* *MAP*
30| **bpftool** **prog detach** *PROG* *ATTACH_TYPE* *MAP*
Quentin Monnet47ff7ac2017-10-23 09:24:15 -070031| **bpftool** **prog help**
Jakub Kicinskiff69c212017-10-04 20:10:05 -070032|
Jakub Kicinski3ff5a4d2018-07-10 14:43:07 -070033| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
Quentin Monnet47ff7ac2017-10-23 09:24:15 -070034| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
Jakub Kicinski49f2cba2018-07-10 14:43:00 -070035| *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 Fastabendb7d38262018-10-15 11:19:50 -070043| *ATTACH_TYPE* := { **msg_verdict** | **skb_verdict** | **skb_parse** }
Jakub Kicinski49f2cba2018-07-10 14:43:00 -070044
Jakub Kicinskiff69c212017-10-04 20:10:05 -070045
46DESCRIPTION
47===========
Jakub Kicinski6ebe6db2018-01-02 14:48:36 -080048 **bpftool prog { show | list }** [*PROG*]
Jakub Kicinskiff69c212017-10-04 20:10:05 -070049 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 Wangb6c1ced2018-03-01 18:01:22 -080056 **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 Kicinskic9c35992017-10-09 10:30:13 -070061
Jiong Wangb6c1ced2018-03-01 18:01:22 -080062 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 Kicinskiff69c212017-10-04 20:10:05 -070068
Quentin Monnet8dfbc6d2017-10-19 15:46:25 -070069 **bpftool prog dump jited** *PROG* [{ **file** *FILE* | **opcodes** }]
Jakub Kicinskiff69c212017-10-04 20:10:05 -070070 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 Monnet882731e2018-10-20 23:01:48 +010079 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 Kicinskiff69c212017-10-04 20:10:05 -070082
Stanislav Fomichev3767a942018-11-09 08:21:45 -080083 **bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
Stanislav Fomichev77380992018-11-09 08:21:44 -080084 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 Kicinski49f2cba2018-07-10 14:43:00 -070088 **type** is optional, if not specified program type will be
89 inferred from section names.
Jakub Kicinski3ff5a4d2018-07-10 14:43:07 -070090 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 Kicinskiba6dd672018-07-10 14:42:58 -070097 If **dev** *NAME* is specified program will be loaded onto
98 given networking device (offload).
Stanislav Fomichev3767a942018-11-09 08:21:45 -080099 Optional **pinmaps** argument can be provided to pin all
100 maps under *MAP_DIR* directory.
Roman Gushchin49a086c2017-12-13 15:18:53 +0000101
Stanislav Fomichev77380992018-11-09 08:21:44 -0800102 Note: *PATH* must be located in *bpffs* mount. It must not
Quentin Monnet882731e2018-10-20 23:01:48 +0100103 contain a dot character ('.'), which is reserved for future
104 extensions of *bpffs*.
Roman Gushchin49a086c2017-12-13 15:18:53 +0000105
John Fastabendb7d38262018-10-15 11:19:50 -0700106 **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 Kicinskiff69c212017-10-04 20:10:05 -0700114 **bpftool prog help**
115 Print short help message.
116
Quentin Monneta2bc2e52017-10-23 09:24:06 -0700117OPTIONS
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 Monnet0641c3c2017-10-23 09:24:16 -0700125 -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 Bholec541b732017-11-08 13:55:49 +0900132 -f, --bpffs
133 Show file names of pinned programs.
134
Jakub Kicinskiff69c212017-10-04 20:10:05 -0700135EXAMPLES
136========
137**# bpftool prog show**
138::
139
Jiri Olsa9b984a22018-04-26 10:18:01 +0200140 10: xdp name some_prog tag 005a3d2123620c8b gpl
Jakub Kicinskiff69c212017-10-04 20:10:05 -0700141 loaded_at Sep 29/20:11 uid 0
142 xlated 528B jited 370B memlock 4096B map_ids 10
143
Quentin Monnet0641c3c2017-10-23 09:24:16 -0700144**# bpftool --json --pretty prog show**
145
146::
147
148 {
149 "programs": [{
150 "id": 10,
151 "type": "xdp",
152 "tag": "005a3d2123620c8b",
Jiri Olsa9b984a22018-04-26 10:18:01 +0200153 "gpl_compatible": true,
Quentin Monnet0641c3c2017-10-23 09:24:16 -0700154 "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 Kicinskiff69c212017-10-04 20:10:05 -0700166|
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 Monnet0641c3c2017-10-23 09:24:16 -0700171**# bpftool prog dum jited tag 005a3d2123620c8b**
Jakub Kicinskiff69c212017-10-04 20:10:05 -0700172
173::
174
175 push %rbp
176 mov %rsp,%rbp
177 sub $0x228,%rsp
178 sub $0x28,%rbp
179 mov %rbx,0x0(%rbp)
180
Quentin Monnet0641c3c2017-10-23 09:24:16 -0700181|
182| **# mount -t bpf none /sys/fs/bpf/**
183| **# bpftool prog pin id 10 /sys/fs/bpf/prog**
Roman Gushchin49a086c2017-12-13 15:18:53 +0000184| **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
Quentin Monnet0641c3c2017-10-23 09:24:16 -0700185| **# ls -l /sys/fs/bpf/**
186| -rw------- 1 root root 0 Jul 22 01:43 prog
Roman Gushchin49a086c2017-12-13 15:18:53 +0000187| -rw------- 1 root root 0 Jul 22 01:44 prog2
Quentin Monnet0641c3c2017-10-23 09:24:16 -0700188
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 Kicinskiff69c212017-10-04 20:10:05 -0700203
Jakub Kicinski3ff5a4d2018-07-10 14:43:07 -0700204|
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 Kicinskiff69c212017-10-04 20:10:05 -0700212
213SEE ALSO
214========
Roman Gushchin5ccda642017-12-13 15:18:54 +0000215 **bpftool**\ (8), **bpftool-map**\ (8), **bpftool-cgroup**\ (8)