0001 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002
0003 ================
0004 bpftool-map
0005 ================
0006 -------------------------------------------------------------------------------
0007 tool for inspection and simple manipulation of eBPF maps
0008 -------------------------------------------------------------------------------
0009
0010 :Manual section: 8
0011
0012 .. include:: substitutions.rst
0013
0014 SYNOPSIS
0015 ========
0016
0017 **bpftool** [*OPTIONS*] **map** *COMMAND*
0018
0019 *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } }
0020
0021 *COMMANDS* :=
0022 { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** |
0023 **delete** | **pin** | **help** }
0024
0025 MAP COMMANDS
0026 =============
0027
0028 | **bpftool** **map** { **show** | **list** } [*MAP*]
0029 | **bpftool** **map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \
0030 | **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] \
0031 | [**dev** *NAME*]
0032 | **bpftool** **map dump** *MAP*
0033 | **bpftool** **map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*]
0034 | **bpftool** **map lookup** *MAP* [**key** *DATA*]
0035 | **bpftool** **map getnext** *MAP* [**key** *DATA*]
0036 | **bpftool** **map delete** *MAP* **key** *DATA*
0037 | **bpftool** **map pin** *MAP* *FILE*
0038 | **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
0039 | **bpftool** **map peek** *MAP*
0040 | **bpftool** **map push** *MAP* **value** *VALUE*
0041 | **bpftool** **map pop** *MAP*
0042 | **bpftool** **map enqueue** *MAP* **value** *VALUE*
0043 | **bpftool** **map dequeue** *MAP*
0044 | **bpftool** **map freeze** *MAP*
0045 | **bpftool** **map help**
0046 |
0047 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* }
0048 | *DATA* := { [**hex**] *BYTES* }
0049 | *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* }
0050 | *VALUE* := { *DATA* | *MAP* | *PROG* }
0051 | *UPDATE_FLAGS* := { **any** | **exist** | **noexist** }
0052 | *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash**
0053 | | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash**
0054 | | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps**
0055 | | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash**
0056 | | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage**
0057 | | **queue** | **stack** | **sk_storage** | **struct_ops** | **ringbuf** | **inode_storage**
0058 | | **task_storage** | **bloom_filter** }
0059
0060 DESCRIPTION
0061 ===========
0062 **bpftool map { show | list }** [*MAP*]
0063 Show information about loaded maps. If *MAP* is specified
0064 show information only about given maps, otherwise list all
0065 maps currently loaded on the system. In case of **name**,
0066 *MAP* may match several maps which will all be shown.
0067
0068 Output will start with map ID followed by map type and
0069 zero or more named attributes (depending on kernel version).
0070
0071 Since Linux 5.8 bpftool is able to discover information about
0072 processes that hold open file descriptors (FDs) against BPF
0073 maps. On such kernels bpftool will automatically emit this
0074 information as well.
0075
0076 **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] [**dev** *NAME*]
0077 Create a new map with given parameters and pin it to *bpffs*
0078 as *FILE*.
0079
0080 *FLAGS* should be an integer which is the combination of
0081 desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h
0082 UAPI header for existing flags).
0083
0084 To create maps of type array-of-maps or hash-of-maps, the
0085 **inner_map** keyword must be used to pass an inner map. The
0086 kernel needs it to collect metadata related to the inner maps
0087 that the new map will work with.
0088
0089 Keyword **dev** expects a network interface name, and is used
0090 to request hardware offload for the map.
0091
0092 **bpftool map dump** *MAP*
0093 Dump all entries in a given *MAP*. In case of **name**,
0094 *MAP* may match several maps which will all be dumped.
0095
0096 **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*]
0097 Update map entry for a given *KEY*.
0098
0099 *UPDATE_FLAGS* can be one of: **any** update existing entry
0100 or add if doesn't exit; **exist** update only if entry already
0101 exists; **noexist** update only if entry doesn't exist.
0102
0103 If the **hex** keyword is provided in front of the bytes
0104 sequence, the bytes are parsed as hexadecimal values, even if
0105 no "0x" prefix is added. If the keyword is not provided, then
0106 the bytes are parsed as decimal values, unless a "0x" prefix
0107 (for hexadecimal) or a "0" prefix (for octal) is provided.
0108
0109 **bpftool map lookup** *MAP* [**key** *DATA*]
0110 Lookup **key** in the map.
0111
0112 **bpftool map getnext** *MAP* [**key** *DATA*]
0113 Get next key. If *key* is not specified, get first key.
0114
0115 **bpftool map delete** *MAP* **key** *DATA*
0116 Remove entry from the map.
0117
0118 **bpftool map pin** *MAP* *FILE*
0119 Pin map *MAP* as *FILE*.
0120
0121 Note: *FILE* must be located in *bpffs* mount. It must not
0122 contain a dot character ('.'), which is reserved for future
0123 extensions of *bpffs*.
0124
0125 **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
0126 Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map.
0127
0128 Install perf rings into a perf event array map and dump
0129 output of any **bpf_perf_event_output**\ () call in the kernel.
0130 By default read the number of CPUs on the system and
0131 install perf ring for each CPU in the corresponding index
0132 in the array.
0133
0134 If **cpu** and **index** are specified, install perf ring
0135 for given **cpu** at **index** in the array (single ring).
0136
0137 Note that installing a perf ring into an array will silently
0138 replace any existing ring. Any other application will stop
0139 receiving events if it installed its rings earlier.
0140
0141 **bpftool map peek** *MAP*
0142 Peek next value in the queue or stack.
0143
0144 **bpftool map push** *MAP* **value** *VALUE*
0145 Push *VALUE* onto the stack.
0146
0147 **bpftool map pop** *MAP*
0148 Pop and print value from the stack.
0149
0150 **bpftool map enqueue** *MAP* **value** *VALUE*
0151 Enqueue *VALUE* into the queue.
0152
0153 **bpftool map dequeue** *MAP*
0154 Dequeue and print value from the queue.
0155
0156 **bpftool map freeze** *MAP*
0157 Freeze the map as read-only from user space. Entries from a
0158 frozen map can not longer be updated or deleted with the
0159 **bpf**\ () system call. This operation is not reversible,
0160 and the map remains immutable from user space until its
0161 destruction. However, read and write permissions for BPF
0162 programs to the map remain unchanged.
0163
0164 **bpftool map help**
0165 Print short help message.
0166
0167 OPTIONS
0168 =======
0169 .. include:: common_options.rst
0170
0171 -f, --bpffs
0172 Show file names of pinned maps.
0173
0174 -n, --nomount
0175 Do not automatically attempt to mount any virtual file system
0176 (such as tracefs or BPF virtual file system) when necessary.
0177
0178 EXAMPLES
0179 ========
0180 **# bpftool map show**
0181
0182 ::
0183
0184 10: hash name some_map flags 0x0
0185 key 4B value 8B max_entries 2048 memlock 167936B
0186 pids systemd(1)
0187
0188 The following three commands are equivalent:
0189
0190 |
0191 | **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c**
0192 | **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c**
0193 | **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76**
0194
0195 **# bpftool map lookup id 10 key 0 1 2 3**
0196
0197 ::
0198
0199 key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
0200
0201
0202 **# bpftool map dump id 10**
0203
0204 ::
0205
0206 key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
0207 key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04
0208 Found 2 elements
0209
0210 **# bpftool map getnext id 10 key 0 1 2 3**
0211
0212 ::
0213
0214 key:
0215 00 01 02 03
0216 next key:
0217 0d 00 07 00
0218
0219 |
0220 | **# mount -t bpf none /sys/fs/bpf/**
0221 | **# bpftool map pin id 10 /sys/fs/bpf/map**
0222 | **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00**
0223
0224 Note that map update can also be used in order to change the program references
0225 hold by a program array map. This can be used, for example, to change the
0226 programs used for tail-call jumps at runtime, without having to reload the
0227 entry-point program. Below is an example for this use case: we load a program
0228 defining a prog array map, and with a main function that contains a tail call
0229 to other programs that can be used either to "process" packets or to "debug"
0230 processing. Note that the prog array map MUST be pinned into the BPF virtual
0231 file system for the map update to work successfully, as kernel flushes prog
0232 array maps when they have no more references from user space (and the update
0233 would be lost as soon as bpftool exits).
0234
0235 |
0236 | **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp**
0237 | **# bpftool prog --bpffs**
0238
0239 ::
0240
0241 545: xdp name main_func tag 674b4b5597193dc3 gpl
0242 loaded_at 2018-12-12T15:02:58+0000 uid 0
0243 xlated 240B jited 257B memlock 4096B map_ids 294
0244 pinned /sys/fs/bpf/foo/xdp
0245 546: xdp name bpf_func_process tag e369a529024751fc gpl
0246 loaded_at 2018-12-12T15:02:58+0000 uid 0
0247 xlated 200B jited 164B memlock 4096B
0248 pinned /sys/fs/bpf/foo/process
0249 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl
0250 loaded_at 2018-12-12T15:02:58+0000 uid 0
0251 xlated 200B jited 164B memlock 4096B
0252 pinned /sys/fs/bpf/foo/debug
0253
0254 **# bpftool map**
0255
0256 ::
0257
0258 294: prog_array name jmp_table flags 0x0
0259 key 4B value 4B max_entries 1 memlock 4096B
0260 owner_prog_type xdp owner jited
0261
0262 |
0263 | **# bpftool map pin id 294 /sys/fs/bpf/bar**
0264 | **# bpftool map dump pinned /sys/fs/bpf/bar**
0265
0266 ::
0267
0268 Found 0 elements
0269
0270 |
0271 | **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug**
0272 | **# bpftool map dump pinned /sys/fs/bpf/bar**
0273
0274 ::
0275
0276 key: 00 00 00 00 value: 22 02 00 00
0277 Found 1 element
