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

NAME

6       bpftool-map - tool for inspection and simple manipulation of eBPF maps
7

SYNOPSIS

9          bpftool [OPTIONS] map COMMAND
10
11          OPTIONS  := { { -j | --json } [{ -p | --pretty }] | { -d | --debug }
12          | { -l | --legacy } | { -f | --bpffs } | { -n | --nomount } }
13
14          COMMANDS := { show | list | create | dump | update | lookup  |  get‐
15          next | delete | pin | help }
16

MAP COMMANDS

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
37       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 }
49
50

DESCRIPTION

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
58                 Output will start with map ID followed by map type  and  zero
59                 or more named attributes (depending on kernel version).
60
61                 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
66          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
71                 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
75                 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
80                 Keyword  dev expects a network interface name, and is used to
81                 request hardware offload for the map.
82
83          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
87          bpftool map update MAP [key DATA] [value VALUE] [UPDATE_FLAGS]
88                 Update map entry for a given KEY.
89
90                 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
94                 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
100          bpftool map lookup MAP [key DATA]
101                 Lookup key in the map.
102
103          bpftool map getnext MAP [key DATA]
104                 Get next key.  If key is not specified, get first key.
105
106          bpftool map delete MAP key DATA
107                 Remove entry from the map.
108
109          bpftool map pin MAP FILE
110                 Pin map MAP as FILE.
111
112                 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
116          bpftool map event_pipe MAP [cpu N index M]
117                 Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map.
118
119                 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
125                 If  cpu  and index are specified, install perf ring for given
126                 cpu at index in the array (single ring).
127
128                 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
132          bpftool map peek MAP
133                 Peek next value in the queue or stack.
134
135          bpftool map push MAP value VALUE
136                 Push VALUE onto the stack.
137
138          bpftool map pop MAP
139                 Pop and print value from the stack.
140
141          bpftool map enqueue MAP value VALUE
142                 Enqueue VALUE into the queue.
143
144          bpftool map dequeue MAP
145                 Dequeue and print value from the queue.
146
147          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
155          bpftool map help
156                 Print short help message.
157

OPTIONS

159          -h, --help
160                 Print short help message (similar to bpftool help).
161
162          -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
172          -j, --json
173                 Generate JSON output. For commands that cannot produce  JSON,
174                 this option has no effect.
175
176          -p, --pretty
177                 Generate human-readable JSON output. Implies -j.
178
179          -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
184          -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
190                 See
191                 https://github.com/libbpf/libbpf/wiki/Libbpf:-the-road-to-v1.0
192                 for details.
193
194          -f, --bpffs
195                 Show file names of pinned maps.
196
197          -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

EXAMPLES

202       # bpftool map show
203
204          10: hash  name some_map  flags 0x0
205                key 4B  value 8B  max_entries 2048  memlock 167936B
206                pids systemd(1)
207
208       The following three commands are equivalent:
209
210       # 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
214
215       # bpftool map lookup id 10 key 0 1 2 3
216
217          key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
218
219       # bpftool map dump id 10
220
221          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
225       # bpftool map getnext id 10 key 0 1 2 3
226
227          key:
228          00 01 02 03
229          next key:
230          0d 00 07 00
231
232       # 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
236
237       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
249       # bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp
250       # bpftool prog --bpffs
251
252
253          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
266       # bpftool map
267
268          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
272       # bpftool map pin id 294 /sys/fs/bpf/bar
273       # bpftool map dump pinned /sys/fs/bpf/bar
274
275
276          Found 0 elements
277
278       # 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
281
282          key: 00 00 00 00  value: 22 02 00 00
283          Found 1 element
284

SEE ALSO

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
291
292
293
294                                                                BPFTOOL-MAP(8)
Impressum