1BPFTOOL-PROG(8) BPFTOOL-PROG(8)
2
6 bpftool-prog - tool for inspection and simple manipulation of eBPF
7 progs
8
10 bpftool [OPTIONS] prog COMMAND
11 OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -f | --bpffs }
13 }
14 COMMANDS := { show | list | dump xlated | dump jited | pin | load |
16 loadall | help }
17
19 bpftool prog { show | list } [PROG]
20 bpftool prog dump xlated PROG [{file FILE | opcodes | visual | linum}]
21 bpftool prog dump jited PROG [{file FILE | opcodes | linum}]
22 bpftool prog pin PROG FILE
23 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX | name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
24 bpftool prog attach PROG ATTACH_TYPE [MAP]
25 bpftool prog detach PROG ATTACH_TYPE [MAP]
26 bpftool prog tracelog
27 bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]] [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
28 bpftool prog help
29 MAP := { id MAP_ID | pinned FILE }
31 PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
32 TYPE := {
33 socket | kprobe | kretprobe | classifier | action |
34 tracepoint | raw_tracepoint | xdp | perf_event | cgroup/skb |
35 cgroup/sock | cgroup/dev | lwt_in | lwt_out | lwt_xmit |
36 lwt_seg6local | sockops | sk_skb | sk_msg | lirc_mode2 |
37 cgroup/bind4 | cgroup/bind6 | cgroup/post_bind4 | cgroup/post_bind6 |
38 cgroup/connect4 | cgroup/connect6 | cgroup/sendmsg4 | cgroup/sendmsg6 |
39 cgroup/recvmsg4 | cgroup/recvmsg6 | cgroup/sysctl |
40 cgroup/getsockopt | cgroup/setsockopt
41 }
42 ATTACH_TYPE := {
43 msg_verdict | stream_verdict | stream_parser | flow_dissector
44 }
45
48 bpftool prog { show | list } [PROG]
49 Show information about loaded programs. If PROG is specified
50 show information only about given programs, otherwise list
51 all programs currently loaded on the system. In case of tag
52 or name, PROG may match several programs which will all be
53 shown.
54 Output will start with program ID followed by program type
56 and zero or more named attributes (depending on kernel ver‐
57 sion).
58 Since Linux 5.1 the kernel can collect statistics on BPF pro‐
60 grams (such as the total time spent running the program, and
61 the number of times it was run). If available, bpftool shows
62 such statistics. However, the kernel does not collect them by
63 defaults, as it slightly impacts performance on each program
64 run. Activation or deactivation of the feature is performed
65 via the kernel.bpf_stats_enabled sysctl knob.
66 bpftool prog dump xlated PROG [{ file FILE | opcodes | visual |
68 linum }]
69 Dump eBPF instructions of the programs from the kernel. By
70 default, eBPF will be disassembled and printed to standard
71 output in human-readable format. In this case, opcodes con‐
72 trols if raw opcodes should be printed as well.
73 In case of tag or name, PROG may match several programs which
75 will all be dumped. However, if file or visual is specified,
76 PROG must match a single program.
77 If file is specified, the binary image will instead be writ‐
79 ten to FILE.
80 If visual is specified, control flow graph (CFG) will be
82 built instead, and eBPF instructions will be presented with
83 CFG in DOT format, on standard output.
84 If the programs have line_info available, the source line
86 will be displayed by default. If linum is specified, the
87 filename, line number and line column will also be displayed
88 on top of the source line.
89 bpftool prog dump jited PROG [{ file FILE | opcodes | linum }]
91 Dump jited image (host machine code) of the program.
92 If FILE is specified image will be written to a file, other‐
94 wise it will be disassembled and printed to stdout. PROG
95 must match a single program when file is specified.
96 opcodes controls if raw opcodes will be printed.
98 If the prog has line_info available, the source line will be
100 displayed by default. If linum is specified, the filename,
101 line number and line column will also be displayed on top of
102 the source line.
103 bpftool prog pin PROG FILE
105 Pin program PROG as FILE.
106 Note: FILE must be located in bpffs mount. It must not con‐
108 tain a dot character ('.'), which is reserved for future
109 extensions of bpffs.
110 bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX |
112 name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
113 Load bpf program(s) from binary OBJ and pin as PATH. bpftool
114 prog load pins only the first program from the OBJ as PATH.
115 bpftool prog loadall pins all programs from the OBJ under
116 PATH directory. type is optional, if not specified program
117 type will be inferred from section names. By default bpftool
118 will create new maps as declared in the ELF object being
119 loaded. map parameter allows for the reuse of existing maps.
120 It can be specified multiple times, each time for a different
121 map. IDX refers to index of the map to be replaced in the
122 ELF file counting from 0, while NAME allows to replace a map
123 by name. MAP specifies the map to use, referring to it by id
124 or through a pinned file. If dev NAME is specified program
125 will be loaded onto given networking device (offload).
126 Optional pinmaps argument can be provided to pin all maps
127 under MAP_DIR directory.
128 Note: PATH must be located in bpffs mount. It must not con‐
130 tain a dot character ('.'), which is reserved for future
131 extensions of bpffs.
132 bpftool prog attach PROG ATTACH_TYPE [MAP]
134 Attach bpf program PROG (with type specified by ATTACH_TYPE).
135 Most ATTACH_TYPEs require a MAP parameter, with the exception
136 of flow_dissector which is attached to current networking
137 name space.
138 bpftool prog detach PROG ATTACH_TYPE [MAP]
140 Detach bpf program PROG (with type specified by ATTACH_TYPE).
141 Most ATTACH_TYPEs require a MAP parameter, with the exception
142 of flow_dissector which is detached from the current network‐
143 ing name space.
144 bpftool prog tracelog
146 Dump the trace pipe of the system to the console (stdout).
147 Hit <Ctrl+C> to stop printing. BPF programs can write to this
148 trace pipe at runtime with the bpf_trace_printk() helper.
149 This should be used only for debugging purposes. For stream‐
150 ing data from BPF programs to user space, one can use perf
151 events (see also bpftool-map(8)).
152 bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]]
154 [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
155 Run BPF program PROG in the kernel testing infrastructure for
156 BPF, meaning that the program works on the data and context
157 provided by the user, and not on actual packets or monitored
158 functions etc. Return value and duration for the test run are
159 printed out to the console.
160 Input data is read from the FILE passed with data_in. If
162 this FILE is "-", input data is read from standard input.
163 Input context, if any, is read from FILE passed with ctx_in.
164 Again, "-" can be used to read from standard input, but only
165 if standard input is not already in use for input data. If a
166 FILE is passed with data_out, output data is written to that
167 file. Similarly, output context is written to the FILE passed
168 with ctx_out. For both output flows, "-" can be used to print
169 to the standard output (as plain text, or JSON if relevant
170 option was passed). If output keywords are omitted, output
171 data and context are discarded. Keywords data_size_out and
172 ctx_size_out are used to pass the size (in bytes) for the
173 output buffers to the kernel, although the default of 32 kB
174 should be more than enough for most cases.
175 Keyword repeat is used to indicate the number of consecutive
177 runs to perform. Note that output data and context printed to
178 files correspond to the last of those runs. The duration
179 printed out at the end of the runs is an average over all
180 runs performed by the command.
181 Not all program types support test run. Among those which do,
183 not all of them can take the ctx_in/ctx_out arguments.
184 bpftool does not perform checks on program types.
185 bpftool prog help
187 Print short help message.
188
190 -h, --help
191 Print short generic help message (similar to bpftool help).
192 -V, --version
194 Print version number (similar to bpftool version).
195 -j, --json
197 Generate JSON output. For commands that cannot produce JSON,
198 this option has no effect.
199 -p, --pretty
201 Generate human-readable JSON output. Implies -j.
202 -f, --bpffs
204 When showing BPF programs, show file names of pinned pro‐
205 grams.
206 -m, --mapcompat
208 Allow loading maps with unknown map definitions.
209 -n, --nomount
211 Do not automatically attempt to mount any virtual file system
212 (such as tracefs or BPF virtual file system) when necessary.
213 -d, --debug
215 Print all logs available, even debug-level information. This
216 includes logs from libbpf as well as from the verifier, when
217 attempting to load programs.
218
220 # bpftool prog show
221 10: xdp name some_prog tag 005a3d2123620c8b gpl run_time_ns 81632 run_cnt 10
223 loaded_at 2017-09-29T20:11:00+0000 uid 0
224 xlated 528B jited 370B memlock 4096B map_ids 10
225 # bpftool --json --pretty prog show
227 [{
229 "id": 10,
230 "type": "xdp",
231 "tag": "005a3d2123620c8b",
232 "gpl_compatible": true,
233 "run_time_ns": 81632,
234 "run_cnt": 10,
235 "loaded_at": 1506715860,
236 "uid": 0,
237 "bytes_xlated": 528,
238 "jited": true,
239 "bytes_jited": 370,
240 "bytes_memlock": 4096,
241 "map_ids": [10
242 ]
243 }
244 ]
245 # bpftool prog dump xlated id 10 file /tmp/t
247 # ls -l /tmp/t
248 -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
251 # bpftool prog dump jited tag 005a3d2123620c8b
253 0: push %rbp
255 1: mov %rsp,%rbp
256 2: sub $0x228,%rsp
257 3: sub $0x28,%rbp
258 4: mov %rbx,0x0(%rbp)
259 # mount -t bpf none /sys/fs/bpf/
261 # bpftool prog pin id 10 /sys/fs/bpf/prog
262 # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
263 # ls -l /sys/fs/bpf/
264 -rw------- 1 root root 0 Jul 22 01:43 prog
267 -rw------- 1 root root 0 Jul 22 01:44 prog2
268 # bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
270 0: push %rbp
272 55
273 1: mov %rsp,%rbp
274 48 89 e5
275 4: sub $0x228,%rsp
276 48 81 ec 28 02 00 00
277 b: sub $0x28,%rbp
278 48 83 ed 28
279 f: mov %rbx,0x0(%rbp)
280 48 89 5d 00
281 # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
283 # bpftool prog show pinned /sys/fs/bpf/xdp1
284 9: xdp name xdp_prog1 tag 539ec6ce11b52f98 gpl
287 loaded_at 2018-06-25T16:17:31-0700 uid 0
288 xlated 488B jited 336B memlock 4096B map_ids 7
289 # rm /sys/fs/bpf/xdp1
291
293 bpf(2), bpf-helpers(7), bpftool(8), bpftool-map(8),
294 bpftool-cgroup(8), bpftool-feature(8), bpftool-net(8),
295 bpftool-perf(8), bpftool-btf(8)
296 BPFTOOL-PROG(8)