1ff69c21aSJakub Kicinski================ 2ff69c21aSJakub Kicinskibpftool-map 3ff69c21aSJakub Kicinski================ 4ff69c21aSJakub Kicinski------------------------------------------------------------------------------- 5ff69c21aSJakub Kicinskitool for inspection and simple manipulation of eBPF maps 6ff69c21aSJakub Kicinski------------------------------------------------------------------------------- 7ff69c21aSJakub Kicinski 8ff69c21aSJakub Kicinski:Manual section: 8 9ff69c21aSJakub Kicinski 10ff69c21aSJakub KicinskiSYNOPSIS 11ff69c21aSJakub Kicinski======== 12ff69c21aSJakub Kicinski 130641c3c8SQuentin Monnet **bpftool** [*OPTIONS*] **map** *COMMAND* 140641c3c8SQuentin Monnet 15c541b734SPrashant Bhole *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } } 16ff69c21aSJakub Kicinski 17ff69c21aSJakub Kicinski *COMMANDS* := 180b592b5aSJakub Kicinski { **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext** 190b592b5aSJakub Kicinski | **delete** | **pin** | **help** } 20ff69c21aSJakub Kicinski 21ff69c21aSJakub KicinskiMAP COMMANDS 22ff69c21aSJakub Kicinski============= 23ff69c21aSJakub Kicinski 24c8caa0bbSQuentin Monnet| **bpftool** **map** { **show** | **list** } [*MAP*] 250b592b5aSJakub Kicinski| **bpftool** **map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \ 26e3b9626fSQuentin Monnet| **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] \ 27e3b9626fSQuentin Monnet| [**dev** *NAME*] 2847ff7ac6SQuentin Monnet| **bpftool** **map dump** *MAP* 297d7209cbSStanislav Fomichev| **bpftool** **map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 308a89fff6SStanislav Fomichev| **bpftool** **map lookup** *MAP* [**key** *DATA*] 31c642ea26SJakub Kicinski| **bpftool** **map getnext** *MAP* [**key** *DATA*] 32c642ea26SJakub Kicinski| **bpftool** **map delete** *MAP* **key** *DATA* 3347ff7ac6SQuentin Monnet| **bpftool** **map pin** *MAP* *FILE* 34f412eed9SJakub Kicinski| **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 3566cf6e0bSStanislav Fomichev| **bpftool** **map peek** *MAP* 36549d4d3dSStanislav Fomichev| **bpftool** **map push** *MAP* **value** *VALUE* 3774f312efSStanislav Fomichev| **bpftool** **map pop** *MAP* 38549d4d3dSStanislav Fomichev| **bpftool** **map enqueue** *MAP* **value** *VALUE* 3974f312efSStanislav Fomichev| **bpftool** **map dequeue** *MAP* 400bb52b0dSQuentin Monnet| **bpftool** **map freeze** *MAP* 4147ff7ac6SQuentin Monnet| **bpftool** **map help** 42ff69c21aSJakub Kicinski| 4399f9863aSPaul Chaignon| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* } 44c642ea26SJakub Kicinski| *DATA* := { [**hex**] *BYTES* } 45a7d22ca2SPaul Chaignon| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } 46c642ea26SJakub Kicinski| *VALUE* := { *DATA* | *MAP* | *PROG* } 4747ff7ac6SQuentin Monnet| *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 480b592b5aSJakub Kicinski| *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 490b592b5aSJakub Kicinski| | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 500b592b5aSJakub Kicinski| | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 511375dc4aSToke Høiland-Jørgensen| | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 52197c2dacSDavid Calavera| | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 53*864ab061SKP Singh| | **queue** | **stack** | **sk_storage** | **struct_ops** | **ringbuf** | **inode_storage** 54*864ab061SKP Singh | **task_storage** } 55ff69c21aSJakub Kicinski 56ff69c21aSJakub KicinskiDESCRIPTION 57ff69c21aSJakub Kicinski=========== 586ebe6dbdSJakub Kicinski **bpftool map { show | list }** [*MAP*] 59ff69c21aSJakub Kicinski Show information about loaded maps. If *MAP* is specified 6099f9863aSPaul Chaignon show information only about given maps, otherwise list all 6199f9863aSPaul Chaignon maps currently loaded on the system. In case of **name**, 6299f9863aSPaul Chaignon *MAP* may match several maps which will all be shown. 63ff69c21aSJakub Kicinski 64ff69c21aSJakub Kicinski Output will start with map ID followed by map type and 65ff69c21aSJakub Kicinski zero or more named attributes (depending on kernel version). 66ff69c21aSJakub Kicinski 67075c7766SAndrii Nakryiko Since Linux 5.8 bpftool is able to discover information about 68075c7766SAndrii Nakryiko processes that hold open file descriptors (FDs) against BPF 69075c7766SAndrii Nakryiko maps. On such kernels bpftool will automatically emit this 70075c7766SAndrii Nakryiko information as well. 71075c7766SAndrii Nakryiko 72e3b9626fSQuentin Monnet **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**inner_map** *MAP*] [**dev** *NAME*] 730b592b5aSJakub Kicinski Create a new map with given parameters and pin it to *bpffs* 740b592b5aSJakub Kicinski as *FILE*. 750b592b5aSJakub Kicinski 76c8caa0bbSQuentin Monnet *FLAGS* should be an integer which is the combination of 77c8caa0bbSQuentin Monnet desired flags, e.g. 1024 for **BPF_F_MMAPABLE** (see bpf.h 78c8caa0bbSQuentin Monnet UAPI header for existing flags). 79c8caa0bbSQuentin Monnet 80e3b9626fSQuentin Monnet To create maps of type array-of-maps or hash-of-maps, the 81e3b9626fSQuentin Monnet **inner_map** keyword must be used to pass an inner map. The 82e3b9626fSQuentin Monnet kernel needs it to collect metadata related to the inner maps 83e3b9626fSQuentin Monnet that the new map will work with. 84e3b9626fSQuentin Monnet 85c8caa0bbSQuentin Monnet Keyword **dev** expects a network interface name, and is used 86c8caa0bbSQuentin Monnet to request hardware offload for the map. 87c8caa0bbSQuentin Monnet 88ff69c21aSJakub Kicinski **bpftool map dump** *MAP* 8999f9863aSPaul Chaignon Dump all entries in a given *MAP*. In case of **name**, 9099f9863aSPaul Chaignon *MAP* may match several maps which will all be dumped. 91ff69c21aSJakub Kicinski 927d7209cbSStanislav Fomichev **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 93ff69c21aSJakub Kicinski Update map entry for a given *KEY*. 94ff69c21aSJakub Kicinski 95ff69c21aSJakub Kicinski *UPDATE_FLAGS* can be one of: **any** update existing entry 96ff69c21aSJakub Kicinski or add if doesn't exit; **exist** update only if entry already 97ff69c21aSJakub Kicinski exists; **noexist** update only if entry doesn't exist. 98ff69c21aSJakub Kicinski 990c90f224SQuentin Monnet If the **hex** keyword is provided in front of the bytes 100c8caa0bbSQuentin Monnet sequence, the bytes are parsed as hexadecimal values, even if 1010c90f224SQuentin Monnet no "0x" prefix is added. If the keyword is not provided, then 1020c90f224SQuentin Monnet the bytes are parsed as decimal values, unless a "0x" prefix 1030c90f224SQuentin Monnet (for hexadecimal) or a "0" prefix (for octal) is provided. 1040c90f224SQuentin Monnet 1058a89fff6SStanislav Fomichev **bpftool map lookup** *MAP* [**key** *DATA*] 106ff69c21aSJakub Kicinski Lookup **key** in the map. 107ff69c21aSJakub Kicinski 108c642ea26SJakub Kicinski **bpftool map getnext** *MAP* [**key** *DATA*] 109ff69c21aSJakub Kicinski Get next key. If *key* is not specified, get first key. 110ff69c21aSJakub Kicinski 111c642ea26SJakub Kicinski **bpftool map delete** *MAP* **key** *DATA* 112ff69c21aSJakub Kicinski Remove entry from the map. 113ff69c21aSJakub Kicinski 114ff69c21aSJakub Kicinski **bpftool map pin** *MAP* *FILE* 115ff69c21aSJakub Kicinski Pin map *MAP* as *FILE*. 116ff69c21aSJakub Kicinski 117882731e0SQuentin Monnet Note: *FILE* must be located in *bpffs* mount. It must not 118882731e0SQuentin Monnet contain a dot character ('.'), which is reserved for future 119882731e0SQuentin Monnet extensions of *bpffs*. 120ff69c21aSJakub Kicinski 121f412eed9SJakub Kicinski **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 122c8caa0bbSQuentin Monnet Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map. 123f412eed9SJakub Kicinski 124f412eed9SJakub Kicinski Install perf rings into a perf event array map and dump 125c8caa0bbSQuentin Monnet output of any **bpf_perf_event_output**\ () call in the kernel. 126f412eed9SJakub Kicinski By default read the number of CPUs on the system and 127f412eed9SJakub Kicinski install perf ring for each CPU in the corresponding index 128f412eed9SJakub Kicinski in the array. 129f412eed9SJakub Kicinski 130f412eed9SJakub Kicinski If **cpu** and **index** are specified, install perf ring 131f412eed9SJakub Kicinski for given **cpu** at **index** in the array (single ring). 132f412eed9SJakub Kicinski 133f412eed9SJakub Kicinski Note that installing a perf ring into an array will silently 134f412eed9SJakub Kicinski replace any existing ring. Any other application will stop 135f412eed9SJakub Kicinski receiving events if it installed its rings earlier. 136f412eed9SJakub Kicinski 13766cf6e0bSStanislav Fomichev **bpftool map peek** *MAP* 138c8caa0bbSQuentin Monnet Peek next value in the queue or stack. 13966cf6e0bSStanislav Fomichev 140549d4d3dSStanislav Fomichev **bpftool map push** *MAP* **value** *VALUE* 141c8caa0bbSQuentin Monnet Push *VALUE* onto the stack. 142549d4d3dSStanislav Fomichev 14374f312efSStanislav Fomichev **bpftool map pop** *MAP* 144c8caa0bbSQuentin Monnet Pop and print value from the stack. 14574f312efSStanislav Fomichev 146549d4d3dSStanislav Fomichev **bpftool map enqueue** *MAP* **value** *VALUE* 147c8caa0bbSQuentin Monnet Enqueue *VALUE* into the queue. 148549d4d3dSStanislav Fomichev 14974f312efSStanislav Fomichev **bpftool map dequeue** *MAP* 150c8caa0bbSQuentin Monnet Dequeue and print value from the queue. 15174f312efSStanislav Fomichev 1520bb52b0dSQuentin Monnet **bpftool map freeze** *MAP* 1530bb52b0dSQuentin Monnet Freeze the map as read-only from user space. Entries from a 1540bb52b0dSQuentin Monnet frozen map can not longer be updated or deleted with the 155c8caa0bbSQuentin Monnet **bpf**\ () system call. This operation is not reversible, 1560bb52b0dSQuentin Monnet and the map remains immutable from user space until its 1570bb52b0dSQuentin Monnet destruction. However, read and write permissions for BPF 1580bb52b0dSQuentin Monnet programs to the map remain unchanged. 1590bb52b0dSQuentin Monnet 160ff69c21aSJakub Kicinski **bpftool map help** 161ff69c21aSJakub Kicinski Print short help message. 162ff69c21aSJakub Kicinski 163a2bc2e5cSQuentin MonnetOPTIONS 164a2bc2e5cSQuentin Monnet======= 165f28ef96dSQuentin Monnet .. include:: common_options.rst 1660641c3c8SQuentin Monnet 167c541b734SPrashant Bhole -f, --bpffs 168c541b734SPrashant Bhole Show file names of pinned maps. 169c541b734SPrashant Bhole 17033221307SQuentin Monnet -n, --nomount 17133221307SQuentin Monnet Do not automatically attempt to mount any virtual file system 17233221307SQuentin Monnet (such as tracefs or BPF virtual file system) when necessary. 17333221307SQuentin Monnet 174ff69c21aSJakub KicinskiEXAMPLES 175ff69c21aSJakub Kicinski======== 176ff69c21aSJakub Kicinski**# bpftool map show** 17716f3ddfbSQuentin Monnet 178ff69c21aSJakub Kicinski:: 179ff69c21aSJakub Kicinski 180ff69c21aSJakub Kicinski 10: hash name some_map flags 0x0 181ff69c21aSJakub Kicinski key 4B value 8B max_entries 2048 memlock 167936B 182075c7766SAndrii Nakryiko pids systemd(1) 183ff69c21aSJakub Kicinski 1840c90f224SQuentin MonnetThe following three commands are equivalent: 1850c90f224SQuentin Monnet 1860c90f224SQuentin Monnet| 1870c90f224SQuentin Monnet| **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c** 1880c90f224SQuentin Monnet| **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c** 1890c90f224SQuentin Monnet| **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76** 190ff69c21aSJakub Kicinski 191ff69c21aSJakub Kicinski**# bpftool map lookup id 10 key 0 1 2 3** 192ff69c21aSJakub Kicinski 193ff69c21aSJakub Kicinski:: 194ff69c21aSJakub Kicinski 195ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 196ff69c21aSJakub Kicinski 197ff69c21aSJakub Kicinski 198ff69c21aSJakub Kicinski**# bpftool map dump id 10** 19916f3ddfbSQuentin Monnet 200ff69c21aSJakub Kicinski:: 201ff69c21aSJakub Kicinski 202ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 203ff69c21aSJakub Kicinski key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 204ff69c21aSJakub Kicinski Found 2 elements 205ff69c21aSJakub Kicinski 206ff69c21aSJakub Kicinski**# bpftool map getnext id 10 key 0 1 2 3** 20716f3ddfbSQuentin Monnet 208ff69c21aSJakub Kicinski:: 209ff69c21aSJakub Kicinski 210ff69c21aSJakub Kicinski key: 211ff69c21aSJakub Kicinski 00 01 02 03 212ff69c21aSJakub Kicinski next key: 213ff69c21aSJakub Kicinski 0d 00 07 00 214ff69c21aSJakub Kicinski 215ff69c21aSJakub Kicinski| 216ff69c21aSJakub Kicinski| **# mount -t bpf none /sys/fs/bpf/** 217ff69c21aSJakub Kicinski| **# bpftool map pin id 10 /sys/fs/bpf/map** 218ff69c21aSJakub Kicinski| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00** 219ff69c21aSJakub Kicinski 220bd0fb9d0SQuentin MonnetNote that map update can also be used in order to change the program references 221bd0fb9d0SQuentin Monnethold by a program array map. This can be used, for example, to change the 222bd0fb9d0SQuentin Monnetprograms used for tail-call jumps at runtime, without having to reload the 223bd0fb9d0SQuentin Monnetentry-point program. Below is an example for this use case: we load a program 224bd0fb9d0SQuentin Monnetdefining a prog array map, and with a main function that contains a tail call 225bd0fb9d0SQuentin Monnetto other programs that can be used either to "process" packets or to "debug" 226bd0fb9d0SQuentin Monnetprocessing. Note that the prog array map MUST be pinned into the BPF virtual 227bd0fb9d0SQuentin Monnetfile system for the map update to work successfully, as kernel flushes prog 228bd0fb9d0SQuentin Monnetarray maps when they have no more references from user space (and the update 229bd0fb9d0SQuentin Monnetwould be lost as soon as bpftool exits). 230bd0fb9d0SQuentin Monnet 231bd0fb9d0SQuentin Monnet| 232bd0fb9d0SQuentin Monnet| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp** 233bd0fb9d0SQuentin Monnet| **# bpftool prog --bpffs** 234bd0fb9d0SQuentin Monnet 235bd0fb9d0SQuentin Monnet:: 236bd0fb9d0SQuentin Monnet 237bd0fb9d0SQuentin Monnet 545: xdp name main_func tag 674b4b5597193dc3 gpl 238bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 239bd0fb9d0SQuentin Monnet xlated 240B jited 257B memlock 4096B map_ids 294 240bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/xdp 241bd0fb9d0SQuentin Monnet 546: xdp name bpf_func_process tag e369a529024751fc gpl 242bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 243bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 244bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/process 245bd0fb9d0SQuentin Monnet 547: xdp name bpf_func_debug tag 0b597868bc7f0976 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/debug 249bd0fb9d0SQuentin Monnet 250bd0fb9d0SQuentin Monnet**# bpftool map** 251bd0fb9d0SQuentin Monnet 252bd0fb9d0SQuentin Monnet:: 253bd0fb9d0SQuentin Monnet 254bd0fb9d0SQuentin Monnet 294: prog_array name jmp_table flags 0x0 255bd0fb9d0SQuentin Monnet key 4B value 4B max_entries 1 memlock 4096B 256bd0fb9d0SQuentin Monnet owner_prog_type xdp owner jited 257bd0fb9d0SQuentin Monnet 258bd0fb9d0SQuentin Monnet| 259bd0fb9d0SQuentin Monnet| **# bpftool map pin id 294 /sys/fs/bpf/bar** 260bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 261bd0fb9d0SQuentin Monnet 262bd0fb9d0SQuentin Monnet:: 263bd0fb9d0SQuentin Monnet 264bd0fb9d0SQuentin Monnet Found 0 elements 265bd0fb9d0SQuentin Monnet 266bd0fb9d0SQuentin Monnet| 267bd0fb9d0SQuentin Monnet| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug** 268bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 269bd0fb9d0SQuentin Monnet 270bd0fb9d0SQuentin Monnet:: 271bd0fb9d0SQuentin Monnet 272bd0fb9d0SQuentin Monnet key: 00 00 00 00 value: 22 02 00 00 273bd0fb9d0SQuentin Monnet Found 1 element 274