143448428SQuentin Monnet.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 243448428SQuentin Monnet 3ff69c21aSJakub Kicinski================ 4ff69c21aSJakub Kicinskibpftool-map 5ff69c21aSJakub Kicinski================ 6ff69c21aSJakub Kicinski------------------------------------------------------------------------------- 7ff69c21aSJakub Kicinskitool for inspection and simple manipulation of eBPF maps 8ff69c21aSJakub Kicinski------------------------------------------------------------------------------- 9ff69c21aSJakub Kicinski 10ff69c21aSJakub Kicinski:Manual section: 8 11ff69c21aSJakub Kicinski 12b6231815SQuentin Monnet.. include:: substitutions.rst 13b6231815SQuentin Monnet 14ff69c21aSJakub KicinskiSYNOPSIS 15ff69c21aSJakub Kicinski======== 16ff69c21aSJakub Kicinski 170641c3c8SQuentin Monnet **bpftool** [*OPTIONS*] **map** *COMMAND* 180641c3c8SQuentin Monnet 19b6231815SQuentin Monnet *OPTIONS* := { |COMMON_OPTIONS| | { **-f** | **--bpffs** } | { **-n** | **--nomount** } } 20ff69c21aSJakub Kicinski 21ff69c21aSJakub Kicinski *COMMANDS* := 22986dec18SQuentin Monnet { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** | 23986dec18SQuentin Monnet **delete** | **pin** | **help** } 24ff69c21aSJakub Kicinski 25ff69c21aSJakub KicinskiMAP COMMANDS 26ff69c21aSJakub Kicinski============= 27ff69c21aSJakub Kicinski 28c8caa0bbSQuentin Monnet| **bpftool** **map** { **show** | **list** } [*MAP*] 290b592b5aSJakub Kicinski| **bpftool** **map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \ 30e3b9626fSQuentin Monnet| **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] \ 31*f46392eeSLarysa Zaremba| [**offload_dev** *NAME*] 3247ff7ac6SQuentin Monnet| **bpftool** **map dump** *MAP* 337d7209cbSStanislav Fomichev| **bpftool** **map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 348a89fff6SStanislav Fomichev| **bpftool** **map lookup** *MAP* [**key** *DATA*] 35c642ea26SJakub Kicinski| **bpftool** **map getnext** *MAP* [**key** *DATA*] 36c642ea26SJakub Kicinski| **bpftool** **map delete** *MAP* **key** *DATA* 3747ff7ac6SQuentin Monnet| **bpftool** **map pin** *MAP* *FILE* 38f412eed9SJakub Kicinski| **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 3966cf6e0bSStanislav Fomichev| **bpftool** **map peek** *MAP* 40549d4d3dSStanislav Fomichev| **bpftool** **map push** *MAP* **value** *VALUE* 4174f312efSStanislav Fomichev| **bpftool** **map pop** *MAP* 42549d4d3dSStanislav Fomichev| **bpftool** **map enqueue** *MAP* **value** *VALUE* 4374f312efSStanislav Fomichev| **bpftool** **map dequeue** *MAP* 440bb52b0dSQuentin Monnet| **bpftool** **map freeze** *MAP* 4547ff7ac6SQuentin Monnet| **bpftool** **map help** 46ff69c21aSJakub Kicinski| 4799f9863aSPaul Chaignon| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* } 48c642ea26SJakub Kicinski| *DATA* := { [**hex**] *BYTES* } 49a7d22ca2SPaul Chaignon| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } 50c642ea26SJakub Kicinski| *VALUE* := { *DATA* | *MAP* | *PROG* } 5147ff7ac6SQuentin Monnet| *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 520b592b5aSJakub Kicinski| *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 530b592b5aSJakub Kicinski| | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 540b592b5aSJakub Kicinski| | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 551375dc4aSToke Høiland-Jørgensen| | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 56197c2dacSDavid Calavera| | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 57864ab061SKP Singh| | **queue** | **stack** | **sk_storage** | **struct_ops** | **ringbuf** | **inode_storage** 58f7f0f165SYonghong Song| | **task_storage** | **bloom_filter** | **user_ringbuf** | **cgrp_storage** } 59ff69c21aSJakub Kicinski 60ff69c21aSJakub KicinskiDESCRIPTION 61ff69c21aSJakub Kicinski=========== 626ebe6dbdSJakub Kicinski **bpftool map { show | list }** [*MAP*] 63ff69c21aSJakub Kicinski Show information about loaded maps. If *MAP* is specified 6499f9863aSPaul Chaignon show information only about given maps, otherwise list all 6599f9863aSPaul Chaignon maps currently loaded on the system. In case of **name**, 6699f9863aSPaul Chaignon *MAP* may match several maps which will all be shown. 67ff69c21aSJakub Kicinski 68ff69c21aSJakub Kicinski Output will start with map ID followed by map type and 69ff69c21aSJakub Kicinski zero or more named attributes (depending on kernel version). 70ff69c21aSJakub Kicinski 71075c7766SAndrii Nakryiko Since Linux 5.8 bpftool is able to discover information about 72075c7766SAndrii Nakryiko processes that hold open file descriptors (FDs) against BPF 73075c7766SAndrii Nakryiko maps. On such kernels bpftool will automatically emit this 74075c7766SAndrii Nakryiko information as well. 75075c7766SAndrii Nakryiko 76*f46392eeSLarysa Zaremba **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*] 770b592b5aSJakub Kicinski Create a new map with given parameters and pin it to *bpffs* 780b592b5aSJakub Kicinski as *FILE*. 790b592b5aSJakub Kicinski 80c8caa0bbSQuentin Monnet *FLAGS* should be an integer which is the combination of 81c8caa0bbSQuentin Monnet desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h 82c8caa0bbSQuentin Monnet UAPI header for existing flags). 83c8caa0bbSQuentin Monnet 84e3b9626fSQuentin Monnet To create maps of type array-of-maps or hash-of-maps, the 85e3b9626fSQuentin Monnet **inner_map** keyword must be used to pass an inner map. The 86e3b9626fSQuentin Monnet kernel needs it to collect metadata related to the inner maps 87e3b9626fSQuentin Monnet that the new map will work with. 88e3b9626fSQuentin Monnet 89*f46392eeSLarysa Zaremba Keyword **offload_dev** expects a network interface name, 90*f46392eeSLarysa Zaremba and is used to request hardware offload for the map. 91c8caa0bbSQuentin Monnet 92ff69c21aSJakub Kicinski **bpftool map dump** *MAP* 9399f9863aSPaul Chaignon Dump all entries in a given *MAP*. In case of **name**, 9499f9863aSPaul Chaignon *MAP* may match several maps which will all be dumped. 95ff69c21aSJakub Kicinski 967d7209cbSStanislav Fomichev **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 97ff69c21aSJakub Kicinski Update map entry for a given *KEY*. 98ff69c21aSJakub Kicinski 99ff69c21aSJakub Kicinski *UPDATE_FLAGS* can be one of: **any** update existing entry 100ff69c21aSJakub Kicinski or add if doesn't exit; **exist** update only if entry already 101ff69c21aSJakub Kicinski exists; **noexist** update only if entry doesn't exist. 102ff69c21aSJakub Kicinski 1030c90f224SQuentin Monnet If the **hex** keyword is provided in front of the bytes 104c8caa0bbSQuentin Monnet sequence, the bytes are parsed as hexadecimal values, even if 1050c90f224SQuentin Monnet no "0x" prefix is added. If the keyword is not provided, then 1060c90f224SQuentin Monnet the bytes are parsed as decimal values, unless a "0x" prefix 1070c90f224SQuentin Monnet (for hexadecimal) or a "0" prefix (for octal) is provided. 1080c90f224SQuentin Monnet 1098a89fff6SStanislav Fomichev **bpftool map lookup** *MAP* [**key** *DATA*] 110ff69c21aSJakub Kicinski Lookup **key** in the map. 111ff69c21aSJakub Kicinski 112c642ea26SJakub Kicinski **bpftool map getnext** *MAP* [**key** *DATA*] 113ff69c21aSJakub Kicinski Get next key. If *key* is not specified, get first key. 114ff69c21aSJakub Kicinski 115c642ea26SJakub Kicinski **bpftool map delete** *MAP* **key** *DATA* 116ff69c21aSJakub Kicinski Remove entry from the map. 117ff69c21aSJakub Kicinski 118ff69c21aSJakub Kicinski **bpftool map pin** *MAP* *FILE* 119ff69c21aSJakub Kicinski Pin map *MAP* as *FILE*. 120ff69c21aSJakub Kicinski 121882731e0SQuentin Monnet Note: *FILE* must be located in *bpffs* mount. It must not 122882731e0SQuentin Monnet contain a dot character ('.'), which is reserved for future 123882731e0SQuentin Monnet extensions of *bpffs*. 124ff69c21aSJakub Kicinski 125f412eed9SJakub Kicinski **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 126c8caa0bbSQuentin Monnet Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map. 127f412eed9SJakub Kicinski 128f412eed9SJakub Kicinski Install perf rings into a perf event array map and dump 129c8caa0bbSQuentin Monnet output of any **bpf_perf_event_output**\ () call in the kernel. 130f412eed9SJakub Kicinski By default read the number of CPUs on the system and 131f412eed9SJakub Kicinski install perf ring for each CPU in the corresponding index 132f412eed9SJakub Kicinski in the array. 133f412eed9SJakub Kicinski 134f412eed9SJakub Kicinski If **cpu** and **index** are specified, install perf ring 135f412eed9SJakub Kicinski for given **cpu** at **index** in the array (single ring). 136f412eed9SJakub Kicinski 137f412eed9SJakub Kicinski Note that installing a perf ring into an array will silently 138f412eed9SJakub Kicinski replace any existing ring. Any other application will stop 139f412eed9SJakub Kicinski receiving events if it installed its rings earlier. 140f412eed9SJakub Kicinski 14166cf6e0bSStanislav Fomichev **bpftool map peek** *MAP* 142c8caa0bbSQuentin Monnet Peek next value in the queue or stack. 14366cf6e0bSStanislav Fomichev 144549d4d3dSStanislav Fomichev **bpftool map push** *MAP* **value** *VALUE* 145c8caa0bbSQuentin Monnet Push *VALUE* onto the stack. 146549d4d3dSStanislav Fomichev 14774f312efSStanislav Fomichev **bpftool map pop** *MAP* 148c8caa0bbSQuentin Monnet Pop and print value from the stack. 14974f312efSStanislav Fomichev 150549d4d3dSStanislav Fomichev **bpftool map enqueue** *MAP* **value** *VALUE* 151c8caa0bbSQuentin Monnet Enqueue *VALUE* into the queue. 152549d4d3dSStanislav Fomichev 15374f312efSStanislav Fomichev **bpftool map dequeue** *MAP* 154c8caa0bbSQuentin Monnet Dequeue and print value from the queue. 15574f312efSStanislav Fomichev 1560bb52b0dSQuentin Monnet **bpftool map freeze** *MAP* 1570bb52b0dSQuentin Monnet Freeze the map as read-only from user space. Entries from a 1580bb52b0dSQuentin Monnet frozen map can not longer be updated or deleted with the 159c8caa0bbSQuentin Monnet **bpf**\ () system call. This operation is not reversible, 1600bb52b0dSQuentin Monnet and the map remains immutable from user space until its 1610bb52b0dSQuentin Monnet destruction. However, read and write permissions for BPF 1620bb52b0dSQuentin Monnet programs to the map remain unchanged. 1630bb52b0dSQuentin Monnet 164ff69c21aSJakub Kicinski **bpftool map help** 165ff69c21aSJakub Kicinski Print short help message. 166ff69c21aSJakub Kicinski 167a2bc2e5cSQuentin MonnetOPTIONS 168a2bc2e5cSQuentin Monnet======= 169f28ef96dSQuentin Monnet .. include:: common_options.rst 1700641c3c8SQuentin Monnet 171c541b734SPrashant Bhole -f, --bpffs 172c541b734SPrashant Bhole Show file names of pinned maps. 173c541b734SPrashant Bhole 17433221307SQuentin Monnet -n, --nomount 17533221307SQuentin Monnet Do not automatically attempt to mount any virtual file system 17633221307SQuentin Monnet (such as tracefs or BPF virtual file system) when necessary. 17733221307SQuentin Monnet 178ff69c21aSJakub KicinskiEXAMPLES 179ff69c21aSJakub Kicinski======== 180ff69c21aSJakub Kicinski**# bpftool map show** 18116f3ddfbSQuentin Monnet 182ff69c21aSJakub Kicinski:: 183ff69c21aSJakub Kicinski 184ff69c21aSJakub Kicinski 10: hash name some_map flags 0x0 185ff69c21aSJakub Kicinski key 4B value 8B max_entries 2048 memlock 167936B 186075c7766SAndrii Nakryiko pids systemd(1) 187ff69c21aSJakub Kicinski 1880c90f224SQuentin MonnetThe following three commands are equivalent: 1890c90f224SQuentin Monnet 1900c90f224SQuentin Monnet| 1910c90f224SQuentin Monnet| **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c** 1920c90f224SQuentin Monnet| **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c** 1930c90f224SQuentin Monnet| **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76** 194ff69c21aSJakub Kicinski 195ff69c21aSJakub Kicinski**# bpftool map lookup id 10 key 0 1 2 3** 196ff69c21aSJakub Kicinski 197ff69c21aSJakub Kicinski:: 198ff69c21aSJakub Kicinski 199ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 200ff69c21aSJakub Kicinski 201ff69c21aSJakub Kicinski 202ff69c21aSJakub Kicinski**# bpftool map dump id 10** 20316f3ddfbSQuentin Monnet 204ff69c21aSJakub Kicinski:: 205ff69c21aSJakub Kicinski 206ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 207ff69c21aSJakub Kicinski key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 208ff69c21aSJakub Kicinski Found 2 elements 209ff69c21aSJakub Kicinski 210ff69c21aSJakub Kicinski**# bpftool map getnext id 10 key 0 1 2 3** 21116f3ddfbSQuentin Monnet 212ff69c21aSJakub Kicinski:: 213ff69c21aSJakub Kicinski 214ff69c21aSJakub Kicinski key: 215ff69c21aSJakub Kicinski 00 01 02 03 216ff69c21aSJakub Kicinski next key: 217ff69c21aSJakub Kicinski 0d 00 07 00 218ff69c21aSJakub Kicinski 219ff69c21aSJakub Kicinski| 220ff69c21aSJakub Kicinski| **# mount -t bpf none /sys/fs/bpf/** 221ff69c21aSJakub Kicinski| **# bpftool map pin id 10 /sys/fs/bpf/map** 222ff69c21aSJakub Kicinski| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00** 223ff69c21aSJakub Kicinski 224bd0fb9d0SQuentin MonnetNote that map update can also be used in order to change the program references 225bd0fb9d0SQuentin Monnethold by a program array map. This can be used, for example, to change the 226bd0fb9d0SQuentin Monnetprograms used for tail-call jumps at runtime, without having to reload the 227bd0fb9d0SQuentin Monnetentry-point program. Below is an example for this use case: we load a program 228bd0fb9d0SQuentin Monnetdefining a prog array map, and with a main function that contains a tail call 229bd0fb9d0SQuentin Monnetto other programs that can be used either to "process" packets or to "debug" 230bd0fb9d0SQuentin Monnetprocessing. Note that the prog array map MUST be pinned into the BPF virtual 231bd0fb9d0SQuentin Monnetfile system for the map update to work successfully, as kernel flushes prog 232bd0fb9d0SQuentin Monnetarray maps when they have no more references from user space (and the update 233bd0fb9d0SQuentin Monnetwould be lost as soon as bpftool exits). 234bd0fb9d0SQuentin Monnet 235bd0fb9d0SQuentin Monnet| 236bd0fb9d0SQuentin Monnet| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp** 237bd0fb9d0SQuentin Monnet| **# bpftool prog --bpffs** 238bd0fb9d0SQuentin Monnet 239bd0fb9d0SQuentin Monnet:: 240bd0fb9d0SQuentin Monnet 241bd0fb9d0SQuentin Monnet 545: xdp name main_func tag 674b4b5597193dc3 gpl 242bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 243bd0fb9d0SQuentin Monnet xlated 240B jited 257B memlock 4096B map_ids 294 244bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/xdp 245bd0fb9d0SQuentin Monnet 546: xdp name bpf_func_process tag e369a529024751fc gpl 246bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 247bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 248bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/process 249bd0fb9d0SQuentin Monnet 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl 250bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 251bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 252bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/debug 253bd0fb9d0SQuentin Monnet 254bd0fb9d0SQuentin Monnet**# bpftool map** 255bd0fb9d0SQuentin Monnet 256bd0fb9d0SQuentin Monnet:: 257bd0fb9d0SQuentin Monnet 258bd0fb9d0SQuentin Monnet 294: prog_array name jmp_table flags 0x0 259bd0fb9d0SQuentin Monnet key 4B value 4B max_entries 1 memlock 4096B 260bd0fb9d0SQuentin Monnet owner_prog_type xdp owner jited 261bd0fb9d0SQuentin Monnet 262bd0fb9d0SQuentin Monnet| 263bd0fb9d0SQuentin Monnet| **# bpftool map pin id 294 /sys/fs/bpf/bar** 264bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 265bd0fb9d0SQuentin Monnet 266bd0fb9d0SQuentin Monnet:: 267bd0fb9d0SQuentin Monnet 268bd0fb9d0SQuentin Monnet Found 0 elements 269bd0fb9d0SQuentin Monnet 270bd0fb9d0SQuentin Monnet| 271bd0fb9d0SQuentin Monnet| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug** 272bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 273bd0fb9d0SQuentin Monnet 274bd0fb9d0SQuentin Monnet:: 275bd0fb9d0SQuentin Monnet 276bd0fb9d0SQuentin Monnet key: 00 00 00 00 value: 22 02 00 00 277bd0fb9d0SQuentin Monnet Found 1 element 278