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 }] | { -f | --bpffs }
12          }
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] [dev NAME]
21       bpftool map dump       MAP
22       bpftool map update     MAP [key DATA] [value VALUE] [UPDATE_FLAGS]
23       bpftool map lookup     MAP [key DATA]
24       bpftool map getnext    MAP [key DATA]
25       bpftool map delete     MAP  key DATA
26       bpftool map pin        MAP  FILE
27       bpftool map event_pipe MAP [cpu N index M]
28       bpftool map peek       MAP
29       bpftool map push       MAP value VALUE
30       bpftool map pop        MAP
31       bpftool map enqueue    MAP value VALUE
32       bpftool map dequeue    MAP
33       bpftool map help
34
35       MAP := { id MAP_ID | pinned FILE }
36       DATA := { [hex] BYTES }
37       PROG := { id PROG_ID | pinned FILE | tag PROG_TAG }
38       VALUE := { DATA | MAP | PROG }
39       UPDATE_FLAGS := { any | exist | noexist }
40       TYPE := { hash | array | prog_array | perf_event_array | percpu_hash
41         | percpu_array | stack_trace | cgroup_array | lru_hash
42         | lru_percpu_hash | lpm_trie | array_of_maps | hash_of_maps
43         | devmap | sockmap | cpumap | xskmap | sockhash
44         | cgroup_storage | reuseport_sockarray | percpu_cgroup_storage
45         | queue | stack }
46
47

DESCRIPTION

49          bpftool map { show | list } [MAP]
50                 Show information about loaded maps.  If MAP is specified show
51                 information only about given map,  otherwise  list  all  maps
52                 currently loaded on the system.
53
54                 Output  will  start with map ID followed by map type and zero
55                 or more named attributes (depending on kernel version).
56
57          bpftool map create FILE type  TYPE  key  KEY_SIZE  value  VALUE_SIZE
58          entries MAX_ENTRIES name NAME [flags FLAGS] [dev NAME]
59                 Create a new map with given parameters and pin it to bpffs as
60                 FILE.
61
62          bpftool map dump MAP
63                 Dump all entries in a given MAP.
64
65          bpftool map update MAP [key DATA] [value VALUE] [UPDATE_FLAGS]
66                 Update map entry for a given KEY.
67
68                 UPDATE_FLAGS can be one of: any update existing entry or  add
69                 if  doesn't  exit; exist update only if entry already exists;
70                 noexist update only if entry doesn't exist.
71
72                 If the  hex  keyword  is  provided  in  front  of  the  bytes
73                 sequence, the bytes are parsed as hexadeximal values, even if
74                 no "0x" prefix is added. If the keyword is not provided, then
75                 the  bytes are parsed as decimal values, unless a "0x" prefix
76                 (for hexadecimal) or a "0" prefix (for octal) is provided.
77
78          bpftool map lookup MAP [key DATA]
79                 Lookup key in the map.
80
81          bpftool map getnext MAP [key DATA]
82                 Get next key.  If key is not specified, get first key.
83
84          bpftool map delete MAP key DATA
85                 Remove entry from the map.
86
87          bpftool map pin MAP FILE
88                 Pin map MAP as FILE.
89
90                 Note: FILE must be located in bpffs mount. It must  not  con‐
91                 tain  a  dot  character  ('.'),  which is reserved for future
92                 extensions of bpffs.
93
94          bpftool map event_pipe MAP [cpu N index M]
95                 Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map.
96
97                 Install perf rings into a perf event array map and dump  out‐
98                 put  of  any  bpf_perf_event_output() call in the kernel.  By
99                 default read the number of CPUs on  the  system  and  install
100                 perf  ring  for  each  CPU  in the corresponding index in the
101                 array.
102
103                 If cpu and index are specified, install perf ring  for  given
104                 cpu at index in the array (single ring).
105
106                 Note  that installing a perf ring into an array will silently
107                 replace any existing ring.  Any other application  will  stop
108                 receiving events if it installed its rings earlier.
109
110          bpftool map peek MAP
111                 Peek next value in the queue or stack.
112
113          bpftool map push MAP value VALUE
114                 Push value onto the stack.
115
116          bpftool map pop MAP
117                 Pop and print value from the stack.
118
119          bpftool map enqueue MAP value VALUE
120                 Enqueue value into the queue.
121
122          bpftool map dequeue MAP
123                 Dequeue and print value from the queue.
124
125          bpftool map help
126                 Print short help message.
127

OPTIONS

129          -h, --help
130                 Print short generic help message (similar to bpftool help).
131
132          -V, --version
133                 Print version number (similar to bpftool version).
134
135          -j, --json
136                 Generate  JSON output. For commands that cannot produce JSON,
137                 this option has no effect.
138
139          -p, --pretty
140                 Generate human-readable JSON output. Implies -j.
141
142          -f, --bpffs
143                 Show file names of pinned maps.
144
145          -n, --nomount
146                 Do not automatically attempt to mount any virtual file system
147                 (such as tracefs or BPF virtual file system) when necessary.
148
149          -d, --debug
150                 Print  all  logs available from libbpf, including debug-level
151                 information.
152

EXAMPLES

154       # bpftool map show
155
156          10: hash  name some_map  flags 0x0
157                key 4B  value 8B  max_entries 2048  memlock 167936B
158
159       The following three commands are equivalent:
160
161       # bpftool map update id 10 key hex   20   c4   b7   00 value hex   0f   ff   ff   ab   01   02   03   4c
162       # bpftool map update id 10 key     0x20 0xc4 0xb7 0x00 value     0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c
163       # bpftool map update id 10 key       32  196  183    0 value       15  255  255  171    1    2    3   76
164
165
166       # bpftool map lookup id 10 key 0 1 2 3
167
168          key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
169
170       # bpftool map dump id 10
171
172          key: 00 01 02 03  value: 00 01 02 03 04 05 06 07
173          key: 0d 00 07 00  value: 02 00 00 00 01 02 03 04
174          Found 2 elements
175
176       # bpftool map getnext id 10 key 0 1 2 3
177
178          key:
179          00 01 02 03
180          next key:
181          0d 00 07 00
182
183       # mount -t bpf none /sys/fs/bpf/
184       # bpftool map pin id 10 /sys/fs/bpf/map
185       # bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00
186
187
188       Note that map update can also be used in order to  change  the  program
189       references  hold by a program array map. This can be used, for example,
190       to change the programs used for tail-call  jumps  at  runtime,  without
191       having  to reload the entry-point program. Below is an example for this
192       use case: we load a program defining a prog array map, and with a  main
193       function  that  contains a tail call to other programs that can be used
194       either to "process" packets or to "debug"  processing.  Note  that  the
195       prog  array map MUST be pinned into the BPF virtual file system for the
196       map update to work successfully, as kernel flushes prog array maps when
197       they  have  no more references from user space (and the update would be
198       lost as soon as bpftool exits).
199
200       # bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp
201       # bpftool prog --bpffs
202
203
204          545: xdp  name main_func  tag 674b4b5597193dc3  gpl
205                  loaded_at 2018-12-12T15:02:58+0000  uid 0
206                  xlated 240B  jited 257B  memlock 4096B  map_ids 294
207                  pinned /sys/fs/bpf/foo/xdp
208          546: xdp  name bpf_func_process  tag e369a529024751fc  gpl
209                  loaded_at 2018-12-12T15:02:58+0000  uid 0
210                  xlated 200B  jited 164B  memlock 4096B
211                  pinned /sys/fs/bpf/foo/process
212          547: xdp  name bpf_func_debug  tag 0b597868bc7f0976  gpl
213                  loaded_at 2018-12-12T15:02:58+0000  uid 0
214                  xlated 200B  jited 164B  memlock 4096B
215                  pinned /sys/fs/bpf/foo/debug
216
217       # bpftool map
218
219          294: prog_array  name jmp_table  flags 0x0
220                  key 4B  value 4B  max_entries 1  memlock 4096B
221                  owner_prog_type xdp  owner jited
222
223       # bpftool map pin id 294 /sys/fs/bpf/bar
224       # bpftool map dump pinned /sys/fs/bpf/bar
225
226
227          Found 0 elements
228
229       # bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug
230       # bpftool map dump pinned /sys/fs/bpf/bar
231
232
233          key: 00 00 00 00  value: 22 02 00 00
234          Found 1 element
235

SEE ALSO

237          bpf(2),      bpf-helpers(7),      bpftool(8),       bpftool-prog(8),
238          bpftool-cgroup(8),        bpftool-feature(8),        bpftool-net(8),
239          bpftool-perf(8), bpftool-btf(8)
240
241
242
243
244                                                                BPFTOOL-MAP(8)
Impressum