1================
2bpftool-map
3================
4-------------------------------------------------------------------------------
5tool for inspection and simple manipulation of eBPF maps
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
11========
12
13	**bpftool** [*OPTIONS*] **map** *COMMAND*
14
15	*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
16
17	*COMMANDS* :=
18	{ **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext**
19	| **delete** | **pin** | **help** }
20
21MAP COMMANDS
22=============
23
24|	**bpftool** **map { show | list }**   [*MAP*]
25|	**bpftool** **map create**     *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \
26|		**entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*]
27|	**bpftool** **map dump**       *MAP*
28|	**bpftool** **map update**     *MAP*  **key** *DATA*   **value** *VALUE* [*UPDATE_FLAGS*]
29|	**bpftool** **map lookup**     *MAP*  **key** *DATA*
30|	**bpftool** **map getnext**    *MAP* [**key** *DATA*]
31|	**bpftool** **map delete**     *MAP*  **key** *DATA*
32|	**bpftool** **map pin**        *MAP*  *FILE*
33|	**bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
34|	**bpftool** **map help**
35|
36|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
37|	*DATA* := { [**hex**] *BYTES* }
38|	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
39|	*VALUE* := { *DATA* | *MAP* | *PROG* }
40|	*UPDATE_FLAGS* := { **any** | **exist** | **noexist** }
41|	*TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash**
42|		| **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash**
43|		| **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps**
44|		| **devmap** | **sockmap** | **cpumap** | **xskmap** | **sockhash**
45|		| **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage**
46|		| **queue** | **stack** }
47
48DESCRIPTION
49===========
50	**bpftool map { show | list }**   [*MAP*]
51		  Show information about loaded maps.  If *MAP* is specified
52		  show information only about given map, otherwise list all
53		  maps currently loaded on the system.
54
55		  Output will start with map ID followed by map type and
56		  zero or more named attributes (depending on kernel version).
57
58	**bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE*  **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*]
59		  Create a new map with given parameters and pin it to *bpffs*
60		  as *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
69		  or add if doesn't exit; **exist** update only if entry already
70		  exists; **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
91		  contain 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
98		  output of any bpf_perf_event_output() call in the kernel.
99		  By default read the number of CPUs on the system and
100		  install perf ring for each CPU in the corresponding index
101		  in the array.
102
103		  If **cpu** and **index** are specified, install perf ring
104		  for given **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 help**
111		  Print short help message.
112
113OPTIONS
114=======
115	-h, --help
116		  Print short generic help message (similar to **bpftool help**).
117
118	-v, --version
119		  Print version number (similar to **bpftool version**).
120
121	-j, --json
122		  Generate JSON output. For commands that cannot produce JSON, this
123		  option has no effect.
124
125	-p, --pretty
126		  Generate human-readable JSON output. Implies **-j**.
127
128	-f, --bpffs
129		  Show file names of pinned maps.
130
131	-n, --nomount
132		  Do not automatically attempt to mount any virtual file system
133		  (such as tracefs or BPF virtual file system) when necessary.
134
135EXAMPLES
136========
137**# bpftool map show**
138::
139
140  10: hash  name some_map  flags 0x0
141	key 4B  value 8B  max_entries 2048  memlock 167936B
142
143The following three commands are equivalent:
144
145|
146| **# bpftool map update id 10 key hex   20   c4   b7   00 value hex   0f   ff   ff   ab   01   02   03   4c**
147| **# bpftool map update id 10 key     0x20 0xc4 0xb7 0x00 value     0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c**
148| **# bpftool map update id 10 key       32  196  183    0 value       15  255  255  171    1    2    3   76**
149
150**# bpftool map lookup id 10 key 0 1 2 3**
151
152::
153
154  key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
155
156
157**# bpftool map dump id 10**
158::
159
160  key: 00 01 02 03  value: 00 01 02 03 04 05 06 07
161  key: 0d 00 07 00  value: 02 00 00 00 01 02 03 04
162  Found 2 elements
163
164**# bpftool map getnext id 10 key 0 1 2 3**
165::
166
167  key:
168  00 01 02 03
169  next key:
170  0d 00 07 00
171
172|
173| **# mount -t bpf none /sys/fs/bpf/**
174| **# bpftool map pin id 10 /sys/fs/bpf/map**
175| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00**
176
177Note that map update can also be used in order to change the program references
178hold by a program array map. This can be used, for example, to change the
179programs used for tail-call jumps at runtime, without having to reload the
180entry-point program. Below is an example for this use case: we load a program
181defining a prog array map, and with a main function that contains a tail call
182to other programs that can be used either to "process" packets or to "debug"
183processing. Note that the prog array map MUST be pinned into the BPF virtual
184file system for the map update to work successfully, as kernel flushes prog
185array maps when they have no more references from user space (and the update
186would be lost as soon as bpftool exits).
187
188|
189| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp**
190| **# bpftool prog --bpffs**
191
192::
193
194  545: xdp  name main_func  tag 674b4b5597193dc3  gpl
195          loaded_at 2018-12-12T15:02:58+0000  uid 0
196          xlated 240B  jited 257B  memlock 4096B  map_ids 294
197          pinned /sys/fs/bpf/foo/xdp
198  546: xdp  name bpf_func_process  tag e369a529024751fc  gpl
199          loaded_at 2018-12-12T15:02:58+0000  uid 0
200          xlated 200B  jited 164B  memlock 4096B
201          pinned /sys/fs/bpf/foo/process
202  547: xdp  name bpf_func_debug  tag 0b597868bc7f0976  gpl
203          loaded_at 2018-12-12T15:02:58+0000  uid 0
204          xlated 200B  jited 164B  memlock 4096B
205          pinned /sys/fs/bpf/foo/debug
206
207**# bpftool map**
208
209::
210
211  294: prog_array  name jmp_table  flags 0x0
212          key 4B  value 4B  max_entries 1  memlock 4096B
213          owner_prog_type xdp  owner jited
214
215|
216| **# bpftool map pin id 294 /sys/fs/bpf/bar**
217| **# bpftool map dump pinned /sys/fs/bpf/bar**
218
219::
220
221  Found 0 elements
222
223|
224| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug**
225| **# bpftool map dump pinned /sys/fs/bpf/bar**
226
227::
228
229  key: 00 00 00 00  value: 22 02 00 00
230  Found 1 element
231
232SEE ALSO
233========
234	**bpf**\ (2),
235	**bpf-helpers**\ (7),
236	**bpftool**\ (8),
237	**bpftool-prog**\ (8),
238	**bpftool-cgroup**\ (8),
239	**bpftool-net**\ (8),
240	**bpftool-perf**\ (8)
241