1BPFTOOL-MAP(8) BPFTOOL-MAP(8)
2
6 bpftool-map - tool for inspection and simple manipulation of eBPF maps
7
9 bpftool [OPTIONS] map COMMAND
10 OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug }
12 | { -l | --legacy } | { -f | --bpffs } | { -n | --nomount } }
13 COMMANDS := { show | list | create | dump | update | lookup | get‐
15 next | delete | pin | help }
16
18 bpftool map { show | list } [MAP]
19 bpftool map create FILE type TYPE key KEY_SIZE value VALUE_SIZE
20 entries MAX_ENTRIES name NAME [flags FLAGS] [inner_map MAP]
21 [dev NAME]
22 bpftool map dump MAP
23 bpftool map update MAP [key DATA] [value VALUE] [UPDATE_FLAGS]
24 bpftool map lookup MAP [key DATA]
25 bpftool map getnext MAP [key DATA]
26 bpftool map delete MAP key DATA
27 bpftool map pin MAP FILE
28 bpftool map event_pipe MAP [cpu N index M]
29 bpftool map peek MAP
30 bpftool map push MAP value VALUE
31 bpftool map pop MAP
32 bpftool map enqueue MAP value VALUE
33 bpftool map dequeue MAP
34 bpftool map freeze MAP
35 bpftool map help
36 MAP := { id MAP_ID | pinned FILE | name MAP_NAME }
38 DATA := { [hex] BYTES }
39 PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
40 VALUE := { DATA | MAP | PROG }
41 UPDATE_FLAGS := { any | exist | noexist }
42 TYPE := { hash | array | prog_array | perf_event_array | percpu_hash
43 | percpu_array | stack_trace | cgroup_array | lru_hash
44 | lru_percpu_hash | lpm_trie | array_of_maps | hash_of_maps
45 | devmap | devmap_hash | sockmap | cpumap | xskmap | sockhash
46 | cgroup_storage | reuseport_sockarray | percpu_cgroup_storage
47 | queue | stack | sk_storage | struct_ops | ringbuf | inode_storage
48 | task_storage | bloom_filter | user_ringbuf }
49
52 bpftool map { show | list } [MAP]
53 Show information about loaded maps. If MAP is specified show
54 information only about given maps, otherwise list all maps
55 currently loaded on the system. In case of name, MAP may
56 match several maps which will all be shown.
57 Output will start with map ID followed by map type and zero
59 or more named attributes (depending on kernel version).
60 Since Linux 5.8 bpftool is able to discover information about
62 processes that hold open file descriptors (FDs) against BPF
63 maps. On such kernels bpftool will automatically emit this
64 information as well.
65 bpftool map create FILE type TYPE key KEY_SIZE value VALUE_SIZE en‐
67 tries MAX_ENTRIES name NAME [flags FLAGS] [inner_map MAP] [dev NAME]
68 Create a new map with given parameters and pin it to bpffs as
69 FILE.
70 FLAGS should be an integer which is the combination of de‐
72 sired flags, e.g. 1024 for BPF_F_MMAPABLE (see bpf.h UAPI
73 header for existing flags).
74 To create maps of type array-of-maps or hash-of-maps, the in‐
76 ner_map keyword must be used to pass an inner map. The kernel
77 needs it to collect metadata related to the inner maps that
78 the new map will work with.
79 Keyword dev expects a network interface name, and is used to
81 request hardware offload for the map.
82 bpftool map dump MAP
84 Dump all entries in a given MAP. In case of name, MAP may
85 match several maps which will all be dumped.
86 bpftool map update MAP [key DATA] [value VALUE] [UPDATE_FLAGS]
88 Update map entry for a given KEY.
89 UPDATE_FLAGS can be one of: any update existing entry or add
91 if doesn't exit; exist update only if entry already exists;
92 noexist update only if entry doesn't exist.
93 If the hex keyword is provided in front of the bytes se‐
95 quence, the bytes are parsed as hexadecimal values, even if
96 no "0x" prefix is added. If the keyword is not provided, then
97 the bytes are parsed as decimal values, unless a "0x" prefix
98 (for hexadecimal) or a "0" prefix (for octal) is provided.
99 bpftool map lookup MAP [key DATA]
101 Lookup key in the map.
102 bpftool map getnext MAP [key DATA]
104 Get next key. If key is not specified, get first key.
105 bpftool map delete MAP key DATA
107 Remove entry from the map.
108 bpftool map pin MAP FILE
110 Pin map MAP as FILE.
111 Note: FILE must be located in bpffs mount. It must not con‐
113 tain a dot character ('.'), which is reserved for future ex‐
114 tensions of bpffs.
115 bpftool map event_pipe MAP [cpu N index M]
117 Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map.
118 Install perf rings into a perf event array map and dump out‐
120 put of any bpf_perf_event_output() call in the kernel. By
121 default read the number of CPUs on the system and install
122 perf ring for each CPU in the corresponding index in the ar‐
123 ray.
124 If cpu and index are specified, install perf ring for given
126 cpu at index in the array (single ring).
127 Note that installing a perf ring into an array will silently
129 replace any existing ring. Any other application will stop
130 receiving events if it installed its rings earlier.
131 bpftool map peek MAP
133 Peek next value in the queue or stack.
134 bpftool map push MAP value VALUE
136 Push VALUE onto the stack.
137 bpftool map pop MAP
139 Pop and print value from the stack.
140 bpftool map enqueue MAP value VALUE
142 Enqueue VALUE into the queue.
143 bpftool map dequeue MAP
145 Dequeue and print value from the queue.
146 bpftool map freeze MAP
148 Freeze the map as read-only from user space. Entries from a
149 frozen map can not longer be updated or deleted with the
150 bpf() system call. This operation is not reversible, and the
151 map remains immutable from user space until its destruction.
152 However, read and write permissions for BPF programs to the
153 map remain unchanged.
154 bpftool map help
156 Print short help message.
157
159 -h, --help
160 Print short help message (similar to bpftool help).
161 -V, --version
163 Print bpftool's version number (similar to bpftool version),
164 the number of the libbpf version in use, and optional fea‐
165 tures that were included when bpftool was compiled. Optional
166 features include linking against libbfd to provide the disas‐
167 sembler for JIT-ted programs (bpftool prog dump jited) and
168 usage of BPF skeletons (some features like bpftool prog pro‐
169 file or showing pids associated to BPF objects may rely on
170 it).
171 -j, --json
173 Generate JSON output. For commands that cannot produce JSON,
174 this option has no effect.
175 -p, --pretty
177 Generate human-readable JSON output. Implies -j.
178 -d, --debug
180 Print all logs available, even debug-level information. This
181 includes logs from libbpf as well as from the verifier, when
182 attempting to load programs.
183 -l, --legacy
185 Use legacy libbpf mode which has more relaxed BPF program re‐
186 quirements. By default, bpftool has more strict requirements
187 about section names, changes pinning logic and doesn't sup‐
188 port some of the older non-BTF map declarations.
189 See
191 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
192 for details.
193 -f, --bpffs
195 Show file names of pinned maps.
196 -n, --nomount
198 Do not automatically attempt to mount any virtual file system
199 (such as tracefs or BPF virtual file system) when necessary.
200
202 # bpftool map show
203 10: hash name some_map flags 0x0
205 key 4B value 8B max_entries 2048 memlock 167936B
206 pids systemd(1)
207 The following three commands are equivalent:
209 # bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c
211 # bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c
212 # bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76
213 # bpftool map lookup id 10 key 0 1 2 3
216 key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
218 # bpftool map dump id 10
220 key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
222 key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04
223 Found 2 elements
224 # bpftool map getnext id 10 key 0 1 2 3
226 key:
228 00 01 02 03
229 next key:
230 0d 00 07 00
231 # mount -t bpf none /sys/fs/bpf/
233 # bpftool map pin id 10 /sys/fs/bpf/map
234 # bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00
235 Note that map update can also be used in order to change the program
238 references hold by a program array map. This can be used, for example,
239 to change the programs used for tail-call jumps at runtime, without
240 having to reload the entry-point program. Below is an example for this
241 use case: we load a program defining a prog array map, and with a main
242 function that contains a tail call to other programs that can be used
243 either to "process" packets or to "debug" processing. Note that the
244 prog array map MUST be pinned into the BPF virtual file system for the
245 map update to work successfully, as kernel flushes prog array maps when
246 they have no more references from user space (and the update would be
247 lost as soon as bpftool exits).
248 # bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp
250 # bpftool prog --bpffs
251 545: xdp name main_func tag 674b4b5597193dc3 gpl
254 loaded_at 2018-12-12T15:02:58+0000 uid 0
255 xlated 240B jited 257B memlock 4096B map_ids 294
256 pinned /sys/fs/bpf/foo/xdp
257 546: xdp name bpf_func_process tag e369a529024751fc gpl
258 loaded_at 2018-12-12T15:02:58+0000 uid 0
259 xlated 200B jited 164B memlock 4096B
260 pinned /sys/fs/bpf/foo/process
261 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl
262 loaded_at 2018-12-12T15:02:58+0000 uid 0
263 xlated 200B jited 164B memlock 4096B
264 pinned /sys/fs/bpf/foo/debug
265 # bpftool map
267 294: prog_array name jmp_table flags 0x0
269 key 4B value 4B max_entries 1 memlock 4096B
270 owner_prog_type xdp owner jited
271 # bpftool map pin id 294 /sys/fs/bpf/bar
273 # bpftool map dump pinned /sys/fs/bpf/bar
274 Found 0 elements
277 # bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug
279 # bpftool map dump pinned /sys/fs/bpf/bar
280 key: 00 00 00 00 value: 22 02 00 00
283 Found 1 element
284
286 bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8),
287 bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8),
288 bpftool-iter(8), bpftool-link(8), bpftool-net(8), bpftool-perf(8),
289 bpftool-prog(8), bpftool-struct_ops(8)
290 BPFTOOL-MAP(8)