1================
2bpftool-prog
3================
4-------------------------------------------------------------------------------
5tool for inspection and simple manipulation of eBPF progs
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
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**
19	| **loadall** | **help** }
20
21PROG COMMANDS
22=============
23
24|	**bpftool** **prog { show | list }** [*PROG*]
25|	**bpftool** **prog dump xlated** *PROG* [{**file** *FILE* | **opcodes** | **visual** | **linum**}]
26|	**bpftool** **prog dump jited**  *PROG* [{**file** *FILE* | **opcodes** | **linum**}]
27|	**bpftool** **prog pin** *PROG* *FILE*
28|	**bpftool** **prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
29|	**bpftool** **prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
30|	**bpftool** **prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
31|	**bpftool** **prog tracelog**
32|	**bpftool** **prog help**
33|
34|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
35|	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
36|	*TYPE* := {
37|		**socket** | **kprobe** | **kretprobe** | **classifier** | **action** |
38|		**tracepoint** | **raw_tracepoint** | **xdp** | **perf_event** | **cgroup/skb** |
39|		**cgroup/sock** | **cgroup/dev** | **lwt_in** | **lwt_out** | **lwt_xmit** |
40|		**lwt_seg6local** | **sockops** | **sk_skb** | **sk_msg** | **lirc_mode2** |
41|		**cgroup/bind4** | **cgroup/bind6** | **cgroup/post_bind4** | **cgroup/post_bind6** |
42|		**cgroup/connect4** | **cgroup/connect6** | **cgroup/sendmsg4** | **cgroup/sendmsg6** |
43|		**cgroup/recvmsg4** | **cgroup/recvmsg6** | **cgroup/sysctl**
44|	}
45|       *ATTACH_TYPE* := {
46|		**msg_verdict** | **stream_verdict** | **stream_parser** | **flow_dissector**
47|	}
48
49
50DESCRIPTION
51===========
52	**bpftool prog { show | list }** [*PROG*]
53		  Show information about loaded programs.  If *PROG* is
54		  specified show information only about given program, otherwise
55		  list all programs currently loaded on the system.
56
57		  Output will start with program ID followed by program type and
58		  zero or more named attributes (depending on kernel version).
59
60		  Since Linux 5.1 the kernel can collect statistics on BPF
61		  programs (such as the total time spent running the program,
62		  and the number of times it was run). If available, bpftool
63		  shows such statistics. However, the kernel does not collect
64		  them by defaults, as it slightly impacts performance on each
65		  program run. Activation or deactivation of the feature is
66		  performed via the **kernel.bpf_stats_enabled** sysctl knob.
67
68	**bpftool prog dump xlated** *PROG* [{ **file** *FILE* | **opcodes** | **visual** | **linum** }]
69		  Dump eBPF instructions of the program from the kernel. By
70		  default, eBPF will be disassembled and printed to standard
71		  output in human-readable format. In this case, **opcodes**
72		  controls if raw opcodes should be printed as well.
73
74		  If **file** is specified, the binary image will instead be
75		  written to *FILE*.
76
77		  If **visual** is specified, control flow graph (CFG) will be
78		  built instead, and eBPF instructions will be presented with
79		  CFG in DOT format, on standard output.
80
81		  If the prog has line_info available, the source line will
82		  be displayed by default.  If **linum** is specified,
83		  the filename, line number and line column will also be
84		  displayed on top of the source line.
85
86	**bpftool prog dump jited**  *PROG* [{ **file** *FILE* | **opcodes** | **linum** }]
87		  Dump jited image (host machine code) of the program.
88		  If *FILE* is specified image will be written to a file,
89		  otherwise it will be disassembled and printed to stdout.
90
91		  **opcodes** controls if raw opcodes will be printed.
92
93		  If the prog has line_info available, the source line will
94		  be displayed by default.  If **linum** is specified,
95		  the filename, line number and line column will also be
96		  displayed on top of the source line.
97
98	**bpftool prog pin** *PROG* *FILE*
99		  Pin program *PROG* as *FILE*.
100
101		  Note: *FILE* must be located in *bpffs* mount. It must not
102		  contain a dot character ('.'), which is reserved for future
103		  extensions of *bpffs*.
104
105	**bpftool prog { load | loadall }** *OBJ* *PATH* [**type** *TYPE*] [**map** {**idx** *IDX* | **name** *NAME*} *MAP*] [**dev** *NAME*] [**pinmaps** *MAP_DIR*]
106		  Load bpf program(s) from binary *OBJ* and pin as *PATH*.
107		  **bpftool prog load** pins only the first program from the
108		  *OBJ* as *PATH*. **bpftool prog loadall** pins all programs
109		  from the *OBJ* under *PATH* directory.
110		  **type** is optional, if not specified program type will be
111		  inferred from section names.
112		  By default bpftool will create new maps as declared in the ELF
113		  object being loaded.  **map** parameter allows for the reuse
114		  of existing maps.  It can be specified multiple times, each
115		  time for a different map.  *IDX* refers to index of the map
116		  to be replaced in the ELF file counting from 0, while *NAME*
117		  allows to replace a map by name.  *MAP* specifies the map to
118		  use, referring to it by **id** or through a **pinned** file.
119		  If **dev** *NAME* is specified program will be loaded onto
120		  given networking device (offload).
121		  Optional **pinmaps** argument can be provided to pin all
122		  maps under *MAP_DIR* directory.
123
124		  Note: *PATH* must be located in *bpffs* mount. It must not
125		  contain a dot character ('.'), which is reserved for future
126		  extensions of *bpffs*.
127
128	**bpftool prog attach** *PROG* *ATTACH_TYPE* [*MAP*]
129		  Attach bpf program *PROG* (with type specified by
130		  *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
131		  parameter, with the exception of *flow_dissector* which is
132		  attached to current networking name space.
133
134	**bpftool prog detach** *PROG* *ATTACH_TYPE* [*MAP*]
135		  Detach bpf program *PROG* (with type specified by
136		  *ATTACH_TYPE*). Most *ATTACH_TYPEs* require a *MAP*
137		  parameter, with the exception of *flow_dissector* which is
138		  detached from the current networking name space.
139
140	**bpftool prog tracelog**
141		  Dump the trace pipe of the system to the console (stdout).
142		  Hit <Ctrl+C> to stop printing. BPF programs can write to this
143		  trace pipe at runtime with the **bpf_trace_printk()** helper.
144		  This should be used only for debugging purposes. For
145		  streaming data from BPF programs to user space, one can use
146		  perf events (see also **bpftool-map**\ (8)).
147
148	**bpftool prog help**
149		  Print short help message.
150
151OPTIONS
152=======
153	-h, --help
154		  Print short generic help message (similar to **bpftool help**).
155
156	-V, --version
157		  Print version number (similar to **bpftool version**).
158
159	-j, --json
160		  Generate JSON output. For commands that cannot produce JSON, this
161		  option has no effect.
162
163	-p, --pretty
164		  Generate human-readable JSON output. Implies **-j**.
165
166	-f, --bpffs
167		  When showing BPF programs, show file names of pinned
168		  programs.
169
170	-m, --mapcompat
171		  Allow loading maps with unknown map definitions.
172
173	-n, --nomount
174		  Do not automatically attempt to mount any virtual file system
175		  (such as tracefs or BPF virtual file system) when necessary.
176
177EXAMPLES
178========
179**# bpftool prog show**
180
181::
182
183    10: xdp  name some_prog  tag 005a3d2123620c8b  gpl run_time_ns 81632 run_cnt 10
184            loaded_at 2017-09-29T20:11:00+0000  uid 0
185            xlated 528B  jited 370B  memlock 4096B  map_ids 10
186
187**# bpftool --json --pretty prog show**
188
189::
190
191    [{
192            "id": 10,
193            "type": "xdp",
194            "tag": "005a3d2123620c8b",
195            "gpl_compatible": true,
196            "run_time_ns": 81632,
197            "run_cnt": 10,
198            "loaded_at": 1506715860,
199            "uid": 0,
200            "bytes_xlated": 528,
201            "jited": true,
202            "bytes_jited": 370,
203            "bytes_memlock": 4096,
204            "map_ids": [10
205            ]
206        }
207    ]
208
209|
210| **# bpftool prog dump xlated id 10 file /tmp/t**
211| **# ls -l /tmp/t**
212
213::
214
215    -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
216
217**# bpftool prog dump jited tag 005a3d2123620c8b**
218
219::
220
221    0:   push   %rbp
222    1:   mov    %rsp,%rbp
223    2:   sub    $0x228,%rsp
224    3:   sub    $0x28,%rbp
225    4:   mov    %rbx,0x0(%rbp)
226
227|
228| **# mount -t bpf none /sys/fs/bpf/**
229| **# bpftool prog pin id 10 /sys/fs/bpf/prog**
230| **# bpftool prog load ./my_prog.o /sys/fs/bpf/prog2**
231| **# ls -l /sys/fs/bpf/**
232
233::
234
235    -rw------- 1 root root 0 Jul 22 01:43 prog
236    -rw------- 1 root root 0 Jul 22 01:44 prog2
237
238**# bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes**
239
240::
241
242   0:   push   %rbp
243        55
244   1:   mov    %rsp,%rbp
245        48 89 e5
246   4:   sub    $0x228,%rsp
247        48 81 ec 28 02 00 00
248   b:   sub    $0x28,%rbp
249        48 83 ed 28
250   f:   mov    %rbx,0x0(%rbp)
251        48 89 5d 00
252
253|
254| **# bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7**
255| **# bpftool prog show pinned /sys/fs/bpf/xdp1**
256
257::
258
259    9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
260            loaded_at 2018-06-25T16:17:31-0700  uid 0
261            xlated 488B  jited 336B  memlock 4096B  map_ids 7
262
263**# rm /sys/fs/bpf/xdp1**
264
265SEE ALSO
266========
267	**bpf**\ (2),
268	**bpf-helpers**\ (7),
269	**bpftool**\ (8),
270	**bpftool-map**\ (8),
271	**bpftool-cgroup**\ (8),
272	**bpftool-feature**\ (8),
273	**bpftool-net**\ (8),
274	**bpftool-perf**\ (8),
275	**bpftool-btf**\ (8)
276