tools/bpf/bpftool/Documentation/bpftool-map.rst

   1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2
   3 ================
   4 bpftool-map
   5 ================
   6 -------------------------------------------------------------------------------
   7 tool for inspection and simple manipulation of eBPF maps
   8 -------------------------------------------------------------------------------
   9
  10 :Manual section: 8
  11
  12 .. include:: substitutions.rst
  13
  14 SYNOPSIS
  15 ========
  16
  17         **bpftool** [*OPTIONS*] **map** *COMMAND*
  18
  19         *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } }
  20
  21         *COMMANDS* :=
  22         { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** |
  23         **delete** | **pin** | **help** }
  24
  25 MAP COMMANDS
  26 =============
  27
  28 |       **bpftool** **map** { **show** | **list** }   [*MAP*]
  29 |       **bpftool** **map create**     *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \
  30 |               **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] \
  31 |               [**offload_dev** *NAME*]
  32 |       **bpftool** **map dump**       *MAP*
  33 |       **bpftool** **map update**     *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*]
  34 |       **bpftool** **map lookup**     *MAP* [**key** *DATA*]
  35 |       **bpftool** **map getnext**    *MAP* [**key** *DATA*]
  36 |       **bpftool** **map delete**     *MAP*  **key** *DATA*
  37 |       **bpftool** **map pin**        *MAP*  *FILE*
  38 |       **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
  39 |       **bpftool** **map peek**       *MAP*
  40 |       **bpftool** **map push**       *MAP* **value** *VALUE*
  41 |       **bpftool** **map pop**        *MAP*
  42 |       **bpftool** **map enqueue**    *MAP* **value** *VALUE*
  43 |       **bpftool** **map dequeue**    *MAP*
  44 |       **bpftool** **map freeze**     *MAP*
  45 |       **bpftool** **map help**
  46 |
  47 |       *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* }
  48 |       *DATA* := { [**hex**] *BYTES* }
  49 |       *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* }
  50 |       *VALUE* := { *DATA* | *MAP* | *PROG* }
  51 |       *UPDATE_FLAGS* := { **any** | **exist** | **noexist** }
  52 |       *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash**
  53 |               | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash**
  54 |               | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps**
  55 |               | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash**
  56 |               | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage**
  57 |               | **queue** | **stack** | **sk_storage** | **struct_ops** | **ringbuf** | **inode_storage**
  58 |               | **task_storage** | **bloom_filter** | **user_ringbuf** | **cgrp_storage** | **arena** }
  59
  60 DESCRIPTION
  61 ===========
  62         **bpftool map { show | list }**   [*MAP*]
  63                   Show information about loaded maps.  If *MAP* is specified
  64                   show information only about given maps, otherwise list all
  65                   maps currently loaded on the system.  In case of **name**,
  66                   *MAP* may match several maps which will all be shown.
  67
  68                   Output will start with map ID followed by map type and
  69                   zero or more named attributes (depending on kernel version).
  70
  71                   Since Linux 5.8 bpftool is able to discover information about
  72                   processes that hold open file descriptors (FDs) against BPF
  73                   maps. On such kernels bpftool will automatically emit this
  74                   information as well.
  75
  76         **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE*  **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] [**offload_dev** *NAME*]
  77                   Create a new map with given parameters and pin it to *bpffs*
  78                   as *FILE*.
  79
  80                   *FLAGS* should be an integer which is the combination of
  81                   desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h
  82                   UAPI header for existing flags).
  83
  84                   To create maps of type array-of-maps or hash-of-maps, the
  85                   **inner_map** keyword must be used to pass an inner map. The
  86                   kernel needs it to collect metadata related to the inner maps
  87                   that the new map will work with.
  88
  89                   Keyword **offload_dev** expects a network interface name,
  90                   and is used to request hardware offload for the map.
  91
  92         **bpftool map dump**    *MAP*
  93                   Dump all entries in a given *MAP*.  In case of **name**,
  94                   *MAP* may match several maps which will all be dumped.
  95
  96         **bpftool map update**  *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*]
  97                   Update map entry for a given *KEY*.
  98
  99                   *UPDATE_FLAGS* can be one of: **any** update existing entry
 100                   or add if doesn't exit; **exist** update only if entry already
 101                   exists; **noexist** update only if entry doesn't exist.
 102
 103                   If the **hex** keyword is provided in front of the bytes
 104                   sequence, the bytes are parsed as hexadecimal values, even if
 105                   no "0x" prefix is added. If the keyword is not provided, then
 106                   the bytes are parsed as decimal values, unless a "0x" prefix
 107                   (for hexadecimal) or a "0" prefix (for octal) is provided.
 108
 109         **bpftool map lookup**  *MAP* [**key** *DATA*]
 110                   Lookup **key** in the map.
 111
 112         **bpftool map getnext** *MAP* [**key** *DATA*]
 113                   Get next key.  If *key* is not specified, get first key.
 114
 115         **bpftool map delete**  *MAP*  **key** *DATA*
 116                   Remove entry from the map.
 117
 118         **bpftool map pin**     *MAP*  *FILE*
 119                   Pin map *MAP* as *FILE*.
 120
 121                   Note: *FILE* must be located in *bpffs* mount. It must not
 122                   contain a dot character ('.'), which is reserved for future
 123                   extensions of *bpffs*.
 124
 125         **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
 126                   Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map.
 127
 128                   Install perf rings into a perf event array map and dump
 129                   output of any **bpf_perf_event_output**\ () call in the kernel.
 130                   By default read the number of CPUs on the system and
 131                   install perf ring for each CPU in the corresponding index
 132                   in the array.
 133
 134                   If **cpu** and **index** are specified, install perf ring
 135                   for given **cpu** at **index** in the array (single ring).
 136
 137                   Note that installing a perf ring into an array will silently
 138                   replace any existing ring.  Any other application will stop
 139                   receiving events if it installed its rings earlier.
 140
 141         **bpftool map peek**  *MAP*
 142                   Peek next value in the queue or stack.
 143
 144         **bpftool map push**  *MAP* **value** *VALUE*
 145                   Push *VALUE* onto the stack.
 146
 147         **bpftool map pop**  *MAP*
 148                   Pop and print value from the stack.
 149
 150         **bpftool map enqueue**  *MAP* **value** *VALUE*
 151                   Enqueue *VALUE* into the queue.
 152
 153         **bpftool map dequeue**  *MAP*
 154                   Dequeue and print value from the queue.
 155
 156         **bpftool map freeze**  *MAP*
 157                   Freeze the map as read-only from user space. Entries from a
 158                   frozen map can not longer be updated or deleted with the
 159                   **bpf**\ () system call. This operation is not reversible,
 160                   and the map remains immutable from user space until its
 161                   destruction. However, read and write permissions for BPF
 162                   programs to the map remain unchanged.
 163
 164         **bpftool map help**
 165                   Print short help message.
 166
 167 OPTIONS
 168 =======
 169         .. include:: common_options.rst
 170
 171         -f, --bpffs
 172                   Show file names of pinned maps.
 173
 174         -n, --nomount
 175                   Do not automatically attempt to mount any virtual file system
 176                   (such as tracefs or BPF virtual file system) when necessary.
 177
 178 EXAMPLES
 179 ========
 180 **# bpftool map show**
 181
 182 ::
 183
 184   10: hash  name some_map  flags 0x0
 185         key 4B  value 8B  max_entries 2048  memlock 167936B
 186         pids systemd(1)
 187
 188 The following three commands are equivalent:
 189
 190 |
 191 | **# bpftool map update id 10 key hex   20   c4   b7   00 value hex   0f   ff   ff   ab   01   02   03   4c**
 192 | **# bpftool map update id 10 key     0x20 0xc4 0xb7 0x00 value     0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c**
 193 | **# bpftool map update id 10 key       32  196  183    0 value       15  255  255  171    1    2    3   76**
 194
 195 **# bpftool map lookup id 10 key 0 1 2 3**
 196
 197 ::
 198
 199   key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
 200
 201
 202 **# bpftool map dump id 10**
 203
 204 ::
 205
 206   key: 00 01 02 03  value: 00 01 02 03 04 05 06 07
 207   key: 0d 00 07 00  value: 02 00 00 00 01 02 03 04
 208   Found 2 elements
 209
 210 **# bpftool map getnext id 10 key 0 1 2 3**
 211
 212 ::
 213
 214   key:
 215   00 01 02 03
 216   next key:
 217   0d 00 07 00
 218
 219 |
 220 | **# mount -t bpf none /sys/fs/bpf/**
 221 | **# bpftool map pin id 10 /sys/fs/bpf/map**
 222 | **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00**
 223
 224 Note that map update can also be used in order to change the program references
 225 hold by a program array map. This can be used, for example, to change the
 226 programs used for tail-call jumps at runtime, without having to reload the
 227 entry-point program. Below is an example for this use case: we load a program
 228 defining a prog array map, and with a main function that contains a tail call
 229 to other programs that can be used either to "process" packets or to "debug"
 230 processing. Note that the prog array map MUST be pinned into the BPF virtual
 231 file system for the map update to work successfully, as kernel flushes prog
 232 array maps when they have no more references from user space (and the update
 233 would be lost as soon as bpftool exits).
 234
 235 |
 236 | **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp**
 237 | **# bpftool prog --bpffs**
 238
 239 ::
 240
 241   545: xdp  name main_func  tag 674b4b5597193dc3  gpl
 242           loaded_at 2018-12-12T15:02:58+0000  uid 0
 243           xlated 240B  jited 257B  memlock 4096B  map_ids 294
 244           pinned /sys/fs/bpf/foo/xdp
 245   546: xdp  name bpf_func_process  tag e369a529024751fc  gpl
 246           loaded_at 2018-12-12T15:02:58+0000  uid 0
 247           xlated 200B  jited 164B  memlock 4096B
 248           pinned /sys/fs/bpf/foo/process
 249   547: xdp  name bpf_func_debug  tag 0b597868bc7f0976  gpl
 250           loaded_at 2018-12-12T15:02:58+0000  uid 0
 251           xlated 200B  jited 164B  memlock 4096B
 252           pinned /sys/fs/bpf/foo/debug
 253
 254 **# bpftool map**
 255
 256 ::
 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 |
 263 | **# bpftool map pin id 294 /sys/fs/bpf/bar**
 264 | **# bpftool map dump pinned /sys/fs/bpf/bar**
 265
 266 ::
 267
 268   Found 0 elements
 269
 270 |
 271 | **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug**
 272 | **# bpftool map dump pinned /sys/fs/bpf/bar**
 273
 274 ::
 275
 276   key: 00 00 00 00  value: 22 02 00 00
 277   Found 1 element