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

NAME

6       bpftool-iter - tool to create BPF iterators
7

SYNOPSIS

9          bpftool [OPTIONS] iter COMMAND
10
11          OPTIONS  := { { -j | --json } [{ -p | --pretty }] | { -d | --debug }
12          | { -l | --legacy } }
13
14          COMMANDS := { pin | help }
15

ITER COMMANDS

17       bpftool iter pin OBJ PATH [map MAP]
18       bpftool iter help
19
20       OBJ := /a/file/of/bpf_iter_target.o
21       MAP := { id MAP_ID | pinned FILE }
22
23

DESCRIPTION

25          bpftool iter pin OBJ PATH [map MAP]
26                 A bpf iterator combines a kernel iterating of particular ker‐
27                 nel  data  (e.g.,  tasks,  bpf_maps, etc.)  and a bpf program
28                 called for each kernel  data  object  (e.g.,  one  task,  one
29                 bpf_map,  etc.).  User  space can read kernel iterator output
30                 through read() syscall.
31
32                 The pin command creates a bpf iterator from OBJ, and  pin  it
33                 to  PATH.  The PATH should be located in bpffs mount. It must
34                 not contain a dot character ('.'), which is reserved for  fu‐
35                 ture extensions of bpffs.
36
37                 Map element bpf iterator requires an additional parameter MAP
38                 so bpf program can iterate over map elements  for  that  map.
39                 User  can  have  a bpf program in kernel to run with each map
40                 element, do checking, filtering,  aggregation,  etc.  without
41                 copying data to user space.
42
43                 User can then cat PATH to see the bpf iterator output.
44
45          bpftool iter help
46                 Print short help message.
47

OPTIONS

49          -h, --help
50                 Print short help message (similar to bpftool help).
51
52          -V, --version
53                 Print  bpftool's version number (similar to bpftool version),
54                 the number of the libbpf version in use,  and  optional  fea‐
55                 tures  that were included when bpftool was compiled. Optional
56                 features include linking against libbfd to provide the disas‐
57                 sembler  for  JIT-ted  programs (bpftool prog dump jited) and
58                 usage of BPF skeletons (some features like bpftool prog  pro‐
59                 file  or  showing  pids associated to BPF objects may rely on
60                 it).
61
62          -j, --json
63                 Generate JSON output. For commands that cannot produce  JSON,
64                 this option has no effect.
65
66          -p, --pretty
67                 Generate human-readable JSON output. Implies -j.
68
69          -d, --debug
70                 Print  all logs available, even debug-level information. This
71                 includes logs from libbpf as well as from the verifier,  when
72                 attempting to load programs.
73
74          -l, --legacy
75                 Use legacy libbpf mode which has more relaxed BPF program re‐
76                 quirements. By default, bpftool has more strict  requirements
77                 about  section  names, changes pinning logic and doesn't sup‐
78                 port some of the older non-BTF map declarations.
79
80                 See
81                 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
82                 for details.
83

EXAMPLES

85       # bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink
86
87          Create a file-based bpf iterator from bpf_iter_netlink.o and pin it
88          to /sys/fs/bpf/my_netlink
89
90       # bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20
91
92          Create a file-based bpf iterator from bpf_iter_hashmap.o and map with
93          id 20, and pin it to /sys/fs/bpf/my_hashmap
94

SEE ALSO

96          bpf(2),      bpf-helpers(7),       bpftool(8),       bpftool-btf(8),
97          bpftool-cgroup(8),        bpftool-feature(8),        bpftool-gen(8),
98          bpftool-link(8),  bpftool-map(8),  bpftool-net(8),  bpftool-perf(8),
99          bpftool-prog(8), bpftool-struct_ops(8)
100
101
102
103
104                                                               BPFTOOL-ITER(8)
Impressum