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          |
13                 { -f | --bpffs } | { -n | --nomount } }
14
15          COMMANDS := { show | list | create | dump | update | lookup  |  get‐
16          next | delete | pin | help }
17

MAP COMMANDS

19       bpftool map { show | list }   [MAP]
20       bpftool map create     FILE type TYPE key KEY_SIZE value VALUE_SIZE
21         entries MAX_ENTRIES name NAME [flags FLAGS] [inner_map MAP]
22         [dev NAME]
23       bpftool map dump       MAP
24       bpftool map update     MAP [key DATA] [value VALUE] [UPDATE_FLAGS]
25       bpftool map lookup     MAP [key DATA]
26       bpftool map getnext    MAP [key DATA]
27       bpftool map delete     MAP  key DATA
28       bpftool map pin        MAP  FILE
29       bpftool map event_pipe MAP [cpu N index M]
30       bpftool map peek       MAP
31       bpftool map push       MAP value VALUE
32       bpftool map pop        MAP
33       bpftool map enqueue    MAP value VALUE
34       bpftool map dequeue    MAP
35       bpftool map freeze     MAP
36       bpftool map help
37
38       MAP := { id MAP_ID | pinned FILE | name MAP_NAME }
39       DATA := { [hex] BYTES }
40       PROG := { id PROG_ID | pinned FILE | tag PROG_TAG | name PROG_NAME }
41       VALUE := { DATA | MAP | PROG }
42       UPDATE_FLAGS := { any | exist | noexist }
43       TYPE := { hash | array | prog_array | perf_event_array | percpu_hash
44         | percpu_array | stack_trace | cgroup_array | lru_hash
45         | lru_percpu_hash | lpm_trie | array_of_maps | hash_of_maps
46         | devmap | devmap_hash | sockmap | cpumap | xskmap | sockhash
47         | cgroup_storage | reuseport_sockarray | percpu_cgroup_storage
48         | queue | stack | sk_storage | struct_ops | ringbuf | inode_storage
49         | task_storage }
50
51

DESCRIPTION

53          bpftool map { show | list } [MAP]
54                 Show information about loaded maps.  If MAP is specified show
55                 information only about given maps, otherwise  list  all  maps
56                 currently  loaded  on  the  system.  In case of name, MAP may
57                 match several maps which will all be shown.
58
59                 Output will start with map ID followed by map type  and  zero
60                 or more named attributes (depending on kernel version).
61
62                 Since Linux 5.8 bpftool is able to discover information about
63                 processes that hold open file descriptors (FDs)  against  BPF
64                 maps.  On  such  kernels bpftool will automatically emit this
65                 information as well.
66
67          bpftool map create FILE type TYPE key KEY_SIZE value VALUE_SIZE  en‐
68          tries MAX_ENTRIES name NAME [flags FLAGS] [inner_map MAP] [dev NAME]
69                 Create a new map with given parameters and pin it to bpffs as
70                 FILE.
71
72                 FLAGS should be an integer which is the  combination  of  de‐
73                 sired  flags,  e.g.  1024  for BPF_F_MMAPABLE (see bpf.h UAPI
74                 header for existing flags).
75
76                 To create maps of type array-of-maps or hash-of-maps, the in‐
77                 ner_map keyword must be used to pass an inner map. The kernel
78                 needs it to collect metadata related to the inner  maps  that
79                 the new map will work with.
80
81                 Keyword  dev expects a network interface name, and is used to
82                 request hardware offload for the map.
83
84          bpftool map dump MAP
85                 Dump all entries in a given MAP.  In case of  name,  MAP  may
86                 match several maps which will all be dumped.
87
88          bpftool map update MAP [key DATA] [value VALUE] [UPDATE_FLAGS]
89                 Update map entry for a given KEY.
90
91                 UPDATE_FLAGS  can be one of: any update existing entry or add
92                 if doesn't exit; exist update only if entry  already  exists;
93                 noexist update only if entry doesn't exist.
94
95                 If  the  hex  keyword  is  provided in front of the bytes se‐
96                 quence, the bytes are parsed as hexadecimal values,  even  if
97                 no "0x" prefix is added. If the keyword is not provided, then
98                 the bytes are parsed as decimal values, unless a "0x"  prefix
99                 (for hexadecimal) or a "0" prefix (for octal) is provided.
100
101          bpftool map lookup MAP [key DATA]
102                 Lookup key in the map.
103
104          bpftool map getnext MAP [key DATA]
105                 Get next key.  If key is not specified, get first key.
106
107          bpftool map delete MAP key DATA
108                 Remove entry from the map.
109
110          bpftool map pin MAP FILE
111                 Pin map MAP as FILE.
112
113                 Note:  FILE  must be located in bpffs mount. It must not con‐
114                 tain a dot character ('.'), which is reserved for future  ex‐
115                 tensions of bpffs.
116
117          bpftool map event_pipe MAP [cpu N index M]
118                 Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map.
119
120                 Install  perf rings into a perf event array map and dump out‐
121                 put of any bpf_perf_event_output() call in  the  kernel.   By
122                 default  read  the  number  of CPUs on the system and install
123                 perf ring for each CPU in the corresponding index in the  ar‐
124                 ray.
125
126                 If  cpu  and index are specified, install perf ring for given
127                 cpu at index in the array (single ring).
128
129                 Note that installing a perf ring into an array will  silently
130                 replace  any  existing ring.  Any other application will stop
131                 receiving events if it installed its rings earlier.
132
133          bpftool map peek MAP
134                 Peek next value in the queue or stack.
135
136          bpftool map push MAP value VALUE
137                 Push VALUE onto the stack.
138
139          bpftool map pop MAP
140                 Pop and print value from the stack.
141
142          bpftool map enqueue MAP value VALUE
143                 Enqueue VALUE into the queue.
144
145          bpftool map dequeue MAP
146                 Dequeue and print value from the queue.
147
148          bpftool map freeze MAP
149                 Freeze the map as read-only from user space. Entries  from  a
150                 frozen  map  can  not  longer  be updated or deleted with the
151                 bpf() system call. This operation is not reversible, and  the
152                 map  remains immutable from user space until its destruction.
153                 However, read and write permissions for BPF programs  to  the
154                 map remain unchanged.
155
156          bpftool map help
157                 Print short help message.
158

OPTIONS

160          -h, --help
161                 Print short help message (similar to bpftool help).
162
163          -V, --version
164                 Print  version  number  (similar to bpftool version), and op‐
165                 tional features that were included when bpftool was compiled.
166                 Optional  features  include linking against libbfd to provide
167                 the disassembler for  JIT-ted  programs  (bpftool  prog  dump
168                 jited) and usage of BPF skeletons (some features like bpftool
169                 prog profile or showing pids associated to  BPF  objects  may
170                 rely on 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          -f, --bpffs
185                 Show file names of pinned maps.
186
187          -n, --nomount
188                 Do not automatically attempt to mount any virtual file system
189                 (such as tracefs or BPF virtual file system) when necessary.
190

EXAMPLES

192       # bpftool map show
193
194          10: hash  name some_map  flags 0x0
195                key 4B  value 8B  max_entries 2048  memlock 167936B
196                pids systemd(1)
197
198       The following three commands are equivalent:
199
200       # bpftool map update id 10 key hex   20   c4   b7   00 value hex   0f   ff   ff   ab   01   02   03   4c
201       # bpftool map update id 10 key     0x20 0xc4 0xb7 0x00 value     0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c
202       # bpftool map update id 10 key       32  196  183    0 value       15  255  255  171    1    2    3   76
203
204
205       # bpftool map lookup id 10 key 0 1 2 3
206
207          key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
208
209       # bpftool map dump id 10
210
211          key: 00 01 02 03  value: 00 01 02 03 04 05 06 07
212          key: 0d 00 07 00  value: 02 00 00 00 01 02 03 04
213          Found 2 elements
214
215       # bpftool map getnext id 10 key 0 1 2 3
216
217          key:
218          00 01 02 03
219          next key:
220          0d 00 07 00
221
222       # mount -t bpf none /sys/fs/bpf/
223       # bpftool map pin id 10 /sys/fs/bpf/map
224       # bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00
225
226
227       Note  that  map  update can also be used in order to change the program
228       references hold by a program array map. This can be used, for  example,
229       to  change  the  programs  used for tail-call jumps at runtime, without
230       having to reload the entry-point program. Below is an example for  this
231       use  case: we load a program defining a prog array map, and with a main
232       function that contains a tail call to other programs that can  be  used
233       either  to  "process"  packets  or to "debug" processing. Note that the
234       prog array map MUST be pinned into the BPF virtual file system for  the
235       map update to work successfully, as kernel flushes prog array maps when
236       they have no more references from user space (and the update  would  be
237       lost as soon as bpftool exits).
238
239       # bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp
240       # bpftool prog --bpffs
241
242
243          545: xdp  name main_func  tag 674b4b5597193dc3  gpl
244                  loaded_at 2018-12-12T15:02:58+0000  uid 0
245                  xlated 240B  jited 257B  memlock 4096B  map_ids 294
246                  pinned /sys/fs/bpf/foo/xdp
247          546: xdp  name bpf_func_process  tag e369a529024751fc  gpl
248                  loaded_at 2018-12-12T15:02:58+0000  uid 0
249                  xlated 200B  jited 164B  memlock 4096B
250                  pinned /sys/fs/bpf/foo/process
251          547: xdp  name bpf_func_debug  tag 0b597868bc7f0976  gpl
252                  loaded_at 2018-12-12T15:02:58+0000  uid 0
253                  xlated 200B  jited 164B  memlock 4096B
254                  pinned /sys/fs/bpf/foo/debug
255
256       # bpftool map
257
258          294: prog_array  name jmp_table  flags 0x0
259                  key 4B  value 4B  max_entries 1  memlock 4096B
260                  owner_prog_type xdp  owner jited
261
262       # bpftool map pin id 294 /sys/fs/bpf/bar
263       # bpftool map dump pinned /sys/fs/bpf/bar
264
265
266          Found 0 elements
267
268       # bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug
269       # bpftool map dump pinned /sys/fs/bpf/bar
270
271
272          key: 00 00 00 00  value: 22 02 00 00
273          Found 1 element
274

SEE ALSO

276          bpf(2),       bpf-helpers(7),       bpftool(8),      bpftool-btf(8),
277          bpftool-cgroup(8),        bpftool-feature(8),        bpftool-gen(8),
278          bpftool-iter(8),  bpftool-link(8),  bpftool-net(8), bpftool-perf(8),
279          bpftool-prog(8), bpftool-struct_ops(8)
280
281
282
283
284                                                                BPFTOOL-MAP(8)
Impressum