1BPFTOOL-PROG(8)                                                BPFTOOL-PROG(8)
2
3
4

NAME

6       bpftool-prog  -  tool  for  inspection  and simple manipulation of eBPF
7       progs
8

SYNOPSIS

10          bpftool [OPTIONS] prog COMMAND
11
12          OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug  }
13          | { -l | --legacy } | { -f | --bpffs } | { -m | --mapcompat } | { -n
14          | --nomount } | { -L | --use-loader } }
15
16          COMMANDS := { show | list | dump xlated | dump jited | pin | load  |
17          loadall | help }
18

PROG COMMANDS

20       bpftool prog { show | list } [PROG]
21       bpftool prog dump xlated PROG [{file FILE | opcodes | visual | linum}]
22       bpftool prog dump jited  PROG [{file FILE | opcodes | linum}]
23       bpftool prog pin PROG FILE
24       bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX | name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
25       bpftool prog attach PROG ATTACH_TYPE [MAP]
26       bpftool prog detach PROG ATTACH_TYPE [MAP]
27       bpftool prog tracelog
28       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]
29       bpftool prog profile PROG [duration DURATION] METRICs
30       bpftool prog help
31
32       MAP := { id MAP_ID | pinned FILE }
33       PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
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/getpeername4 | cgroup/getpeername6 |
41         cgroup/getsockname4 | cgroup/getsockname6 | cgroup/sendmsg4 | cgroup/sendmsg6 |
42         cgroup/recvmsg4 | cgroup/recvmsg6 | cgroup/sysctl |
43         cgroup/getsockopt | cgroup/setsockopt | cgroup/sock_release |
44         struct_ops | fentry | fexit | freplace | sk_lookup
45       }
46       ATTACH_TYPE := {
47         msg_verdict | skb_verdict | stream_verdict | stream_parser | flow_dissector
48       }
49       METRICs := {
50         cycles | instructions | l1d_loads | llc_misses |
51         itlb_misses | dtlb_misses
52       }
53
54

DESCRIPTION

56          bpftool prog { show | list } [PROG]
57                 Show information about loaded programs.  If PROG is specified
58                 show information only about given  programs,  otherwise  list
59                 all  programs currently loaded on the system.  In case of tag
60                 or name, PROG may match several programs which  will  all  be
61                 shown.
62
63                 Output  will  start  with program ID followed by program type
64                 and zero or more named attributes (depending on  kernel  ver‐
65                 sion).
66
67                 Since Linux 5.1 the kernel can collect statistics on BPF pro‐
68                 grams (such as the total time spent running the program,  and
69                 the  number of times it was run). If available, bpftool shows
70                 such statistics. However, the kernel does not collect them by
71                 defaults,  as it slightly impacts performance on each program
72                 run. Activation or deactivation of the feature  is  performed
73                 via the kernel.bpf_stats_enabled sysctl knob.
74
75                 Since Linux 5.8 bpftool is able to discover information about
76                 processes that hold open file descriptors (FDs)  against  BPF
77                 programs.  On  such  kernels  bpftool will automatically emit
78                 this information as well.
79
80          bpftool prog dump xlated PROG [{ file FILE  |  opcodes  |  visual  |
81          linum }]
82                 Dump  eBPF  instructions  of the programs from the kernel. By
83                 default, eBPF will be disassembled and  printed  to  standard
84                 output  in  human-readable format. In this case, opcodes con‐
85                 trols if raw opcodes should be printed as well.
86
87                 In case of tag or name, PROG may match several programs which
88                 will all be dumped.  However, if file or visual is specified,
89                 PROG must match a single program.
90
91                 If file is specified, the binary image will instead be  writ‐
92                 ten to FILE.
93
94                 If  visual  is  specified,  control  flow graph (CFG) will be
95                 built instead, and eBPF instructions will be  presented  with
96                 CFG in DOT format, on standard output.
97
98                 If  the  programs  have  line_info available, the source line
99                 will be displayed by default.  If  linum  is  specified,  the
100                 filename,  line number and line column will also be displayed
101                 on top of the source line.
102
103          bpftool prog dump jited PROG [{ file FILE | opcodes | linum }]
104                 Dump jited image (host machine code) of the program.
105
106                 If FILE is specified image will be written to a file,  other‐
107                 wise  it  will  be  disassembled and printed to stdout.  PROG
108                 must match a single program when file is specified.
109
110                 opcodes controls if raw opcodes will be printed.
111
112                 If the prog has line_info available, the source line will  be
113                 displayed  by  default.  If linum is specified, the filename,
114                 line number and line column will also be displayed on top  of
115                 the source line.
116
117          bpftool prog pin PROG FILE
118                 Pin program PROG as FILE.
119
120                 Note:  FILE  must be located in bpffs mount. It must not con‐
121                 tain a dot character ('.'), which is reserved for future  ex‐
122                 tensions of bpffs.
123
124          bpftool prog { load | loadall } OBJ PATH [type TYPE] [map {idx IDX |
125          name NAME} MAP] [dev NAME] [pinmaps MAP_DIR]
126                 Load bpf program(s) from binary OBJ and pin as PATH.  bpftool
127                 prog  load  pins only the first program from the OBJ as PATH.
128                 bpftool prog loadall pins all programs  from  the  OBJ  under
129                 PATH  directory.   type is optional, if not specified program
130                 type will be inferred from section names.  By default bpftool
131                 will  create  new  maps  as  declared in the ELF object being
132                 loaded.  map parameter allows for the reuse of existing maps.
133                 It can be specified multiple times, each time for a different
134                 map.  IDX refers to index of the map to be  replaced  in  the
135                 ELF  file counting from 0, while NAME allows to replace a map
136                 by name.  MAP specifies the map to use, referring to it by id
137                 or  through  a pinned file.  If dev NAME is specified program
138                 will be loaded onto given networking device  (offload).   Op‐
139                 tional pinmaps argument can be provided to pin all maps under
140                 MAP_DIR directory.
141
142                 Note: PATH must be located in bpffs mount. It must  not  con‐
143                 tain  a dot character ('.'), which is reserved for future ex‐
144                 tensions of bpffs.
145
146          bpftool prog attach PROG ATTACH_TYPE [MAP]
147                 Attach bpf program PROG (with type specified by ATTACH_TYPE).
148                 Most ATTACH_TYPEs require a MAP parameter, with the exception
149                 of flow_dissector which is  attached  to  current  networking
150                 name space.
151
152          bpftool prog detach PROG ATTACH_TYPE [MAP]
153                 Detach bpf program PROG (with type specified by ATTACH_TYPE).
154                 Most ATTACH_TYPEs require a MAP parameter, with the exception
155                 of flow_dissector which is detached from the current network‐
156                 ing name space.
157
158          bpftool prog tracelog
159                 Dump the trace pipe of the system to  the  console  (stdout).
160                 Hit <Ctrl+C> to stop printing. BPF programs can write to this
161                 trace pipe at runtime  with  the  bpf_trace_printk()  helper.
162                 This  should be used only for debugging purposes. For stream‐
163                 ing data from BPF programs to user space, one  can  use  perf
164                 events (see also bpftool-map(8)).
165
166          bpftool prog run PROG data_in FILE [data_out FILE [data_size_out L]]
167          [ctx_in FILE [ctx_out FILE [ctx_size_out M]]] [repeat N]
168                 Run BPF program PROG in the kernel testing infrastructure for
169                 BPF,  meaning  that the program works on the data and context
170                 provided by the user, and not on actual packets or  monitored
171                 functions etc. Return value and duration for the test run are
172                 printed out to the console.
173
174                 Input data is read from the FILE  passed  with  data_in.   If
175                 this FILE is "-", input data is read from standard input. In‐
176                 put context, if any, is read from FILE  passed  with  ctx_in.
177                 Again,  "-" can be used to read from standard input, but only
178                 if standard input is not already in use for input data. If  a
179                 FILE  is passed with data_out, output data is written to that
180                 file. Similarly, output context is written to the FILE passed
181                 with ctx_out. For both output flows, "-" can be used to print
182                 to the standard output (as plain text, or  JSON  if  relevant
183                 option  was  passed).  If output keywords are omitted, output
184                 data and context are discarded.  Keywords  data_size_out  and
185                 ctx_size_out  are  used  to  pass the size (in bytes) for the
186                 output buffers to the kernel, although the default of  32  kB
187                 should be more than enough for most cases.
188
189                 Keyword  repeat is used to indicate the number of consecutive
190                 runs to perform. Note that output data and context printed to
191                 files  correspond  to  the  last  of those runs. The duration
192                 printed out at the end of the runs is  an  average  over  all
193                 runs performed by the command.
194
195                 Not all program types support test run. Among those which do,
196                 not all  of  them  can  take  the  ctx_in/ctx_out  arguments.
197                 bpftool does not perform checks on program types.
198
199          bpftool prog profile PROG [duration DURATION] METRICs
200                 Profile  METRICs for bpf program PROG for DURATION seconds or
201                 until user hits <Ctrl+C>. DURATION is optional.  If  DURATION
202                 is  not specified, the profiling will run up to UINT_MAX sec‐
203                 onds.
204
205          bpftool prog help
206                 Print short help message.
207

OPTIONS

209          -h, --help
210                 Print short help message (similar to bpftool help).
211
212          -V, --version
213                 Print bpftool's version number (similar to bpftool  version),
214                 the  number  of  the libbpf version in use, and optional fea‐
215                 tures that were included when bpftool was compiled.  Optional
216                 features include linking against libbfd to provide the disas‐
217                 sembler for JIT-ted programs (bpftool prog  dump  jited)  and
218                 usage  of BPF skeletons (some features like bpftool prog pro‐
219                 file or showing pids associated to BPF objects  may  rely  on
220                 it).
221
222          -j, --json
223                 Generate  JSON output. For commands that cannot produce JSON,
224                 this option has no effect.
225
226          -p, --pretty
227                 Generate human-readable JSON output. Implies -j.
228
229          -d, --debug
230                 Print all logs available, even debug-level information.  This
231                 includes  logs from libbpf as well as from the verifier, when
232                 attempting to load programs.
233
234          -l, --legacy
235                 Use legacy libbpf mode which has more relaxed BPF program re‐
236                 quirements.  By default, bpftool has more strict requirements
237                 about section names, changes pinning logic and  doesn't  sup‐
238                 port some of the older non-BTF map declarations.
239
240                 See
241                 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
242                 for details.
243
244          -f, --bpffs
245                 When  showing  BPF  programs,  show file names of pinned pro‐
246                 grams.
247
248          -m, --mapcompat
249                 Allow loading maps with unknown map definitions.
250
251          -n, --nomount
252                 Do not automatically attempt to mount any virtual file system
253                 (such as tracefs or BPF virtual file system) when necessary.
254
255          -L, --use-loader
256                 Load  program  as a "loader" program. This is useful to debug
257                 the generation of such programs. When this option is in  use,
258                 bpftool  attempts  to  load the programs from the object file
259                 into the kernel, but does not pin them (therefore,  the  PATH
260                 must not be provided).
261
262                 When  combined  with  the -d|--debug option, additional debug
263                 messages are generated, and the execution of the loader  pro‐
264                 gram  will use the bpf_trace_printk() helper to log each step
265                 of loading BTF, creating the maps, and loading  the  programs
266                 (see bpftool prog tracelog as a way to dump those messages).
267

EXAMPLES

269       # bpftool prog show
270
271          10: xdp  name some_prog  tag 005a3d2123620c8b  gpl run_time_ns 81632 run_cnt 10
272                  loaded_at 2017-09-29T20:11:00+0000  uid 0
273                  xlated 528B  jited 370B  memlock 4096B  map_ids 10
274                  pids systemd(1)
275
276       # bpftool --json --pretty prog show
277
278          [{
279                  "id": 10,
280                  "type": "xdp",
281                  "tag": "005a3d2123620c8b",
282                  "gpl_compatible": true,
283                  "run_time_ns": 81632,
284                  "run_cnt": 10,
285                  "loaded_at": 1506715860,
286                  "uid": 0,
287                  "bytes_xlated": 528,
288                  "jited": true,
289                  "bytes_jited": 370,
290                  "bytes_memlock": 4096,
291                  "map_ids": [10
292                  ],
293                  "pids": [{
294                          "pid": 1,
295                          "comm": "systemd"
296                      }
297                  ]
298              }
299          ]
300
301       # bpftool prog dump xlated id 10 file /tmp/t
302       $ ls -l /tmp/t
303
304
305          -rw------- 1 root root 560 Jul 22 01:42 /tmp/t
306
307       # bpftool prog dump jited tag 005a3d2123620c8b
308
309          0:   push   %rbp
310          1:   mov    %rsp,%rbp
311          2:   sub    $0x228,%rsp
312          3:   sub    $0x28,%rbp
313          4:   mov    %rbx,0x0(%rbp)
314
315       # mount -t bpf none /sys/fs/bpf/
316       # bpftool prog pin id 10 /sys/fs/bpf/prog
317       # bpftool prog load ./my_prog.o /sys/fs/bpf/prog2
318       # ls -l /sys/fs/bpf/
319
320
321          -rw------- 1 root root 0 Jul 22 01:43 prog
322          -rw------- 1 root root 0 Jul 22 01:44 prog2
323
324       # bpftool prog dump jited pinned /sys/fs/bpf/prog opcodes
325
326          0:   push   %rbp
327               55
328          1:   mov    %rsp,%rbp
329               48 89 e5
330          4:   sub    $0x228,%rsp
331               48 81 ec 28 02 00 00
332          b:   sub    $0x28,%rbp
333               48 83 ed 28
334          f:   mov    %rbx,0x0(%rbp)
335               48 89 5d 00
336
337       # bpftool prog load xdp1_kern.o /sys/fs/bpf/xdp1 type xdp map name rxcnt id 7
338       # bpftool prog show pinned /sys/fs/bpf/xdp1
339
340
341          9: xdp  name xdp_prog1  tag 539ec6ce11b52f98  gpl
342                  loaded_at 2018-06-25T16:17:31-0700  uid 0
343                  xlated 488B  jited 336B  memlock 4096B  map_ids 7
344
345       # rm /sys/fs/bpf/xdp1
346
347       # bpftool prog profile id 337 duration 10 cycles instructions llc_misses
348
349
350             51397 run_cnt
351          40176203 cycles                                                 (83.05%)
352          42518139 instructions    #   1.06 insns per cycle               (83.39%)
353               123 llc_misses      #   2.89 LLC misses per million insns  (83.15%)
354
355       Output below is for the trace logs.
356       Run in separate terminals:
357       # bpftool prog tracelog
358       # bpftool prog load -L -d file.o
359
360
361          bpftool-620059  [004] d... 2634685.517903: bpf_trace_printk: btf_load size 665 r=5
362          bpftool-620059  [004] d... 2634685.517912: bpf_trace_printk: map_create sample_map idx 0 type 2 value_size 4 value_btf_id 0 r=6
363          bpftool-620059  [004] d... 2634685.517997: bpf_trace_printk: prog_load sample insn_cnt 13 r=7
364          bpftool-620059  [004] d... 2634685.517999: bpf_trace_printk: close(5) = 0
365

SEE ALSO

367          bpf(2),       bpf-helpers(7),       bpftool(8),      bpftool-btf(8),
368          bpftool-cgroup(8),        bpftool-feature(8),        bpftool-gen(8),
369          bpftool-iter(8),  bpftool-link(8),  bpftool-map(8),  bpftool-net(8),
370          bpftool-perf(8), bpftool-struct_ops(8)
371
372
373
374
375                                                               BPFTOOL-PROG(8)
Impressum