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 246ebe6dbdSJakub Kicinski| **bpftool** **map { show | list }** [*MAP*] 250b592b5aSJakub Kicinski| **bpftool** **map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \ 260b592b5aSJakub Kicinski| **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*] 2747ff7ac6SQuentin Monnet| **bpftool** **map dump** *MAP* 287d7209cbSStanislav Fomichev| **bpftool** **map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 298a89fff6SStanislav Fomichev| **bpftool** **map lookup** *MAP* [**key** *DATA*] 30c642ea26SJakub Kicinski| **bpftool** **map getnext** *MAP* [**key** *DATA*] 31c642ea26SJakub Kicinski| **bpftool** **map delete** *MAP* **key** *DATA* 3247ff7ac6SQuentin Monnet| **bpftool** **map pin** *MAP* *FILE* 33f412eed9SJakub Kicinski| **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 3466cf6e0bSStanislav Fomichev| **bpftool** **map peek** *MAP* 35549d4d3dSStanislav Fomichev| **bpftool** **map push** *MAP* **value** *VALUE* 3674f312efSStanislav Fomichev| **bpftool** **map pop** *MAP* 37549d4d3dSStanislav Fomichev| **bpftool** **map enqueue** *MAP* **value** *VALUE* 3874f312efSStanislav Fomichev| **bpftool** **map dequeue** *MAP* 390bb52b0dSQuentin Monnet| **bpftool** **map freeze** *MAP* 4047ff7ac6SQuentin Monnet| **bpftool** **map help** 41ff69c21aSJakub Kicinski| 4299f9863aSPaul Chaignon| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* | **name** *MAP_NAME* } 43c642ea26SJakub Kicinski| *DATA* := { [**hex**] *BYTES* } 44a7d22ca2SPaul Chaignon| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* | **name** *PROG_NAME* } 45c642ea26SJakub Kicinski| *VALUE* := { *DATA* | *MAP* | *PROG* } 4647ff7ac6SQuentin Monnet| *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 470b592b5aSJakub Kicinski| *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 480b592b5aSJakub Kicinski| | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 490b592b5aSJakub Kicinski| | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 501375dc4aSToke Høiland-Jørgensen| | **devmap** | **devmap_hash** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 51197c2dacSDavid Calavera| | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 52197c2dacSDavid Calavera| | **queue** | **stack** } 53ff69c21aSJakub Kicinski 54ff69c21aSJakub KicinskiDESCRIPTION 55ff69c21aSJakub Kicinski=========== 566ebe6dbdSJakub Kicinski **bpftool map { show | list }** [*MAP*] 57ff69c21aSJakub Kicinski Show information about loaded maps. If *MAP* is specified 5899f9863aSPaul Chaignon show information only about given maps, otherwise list all 5999f9863aSPaul Chaignon maps currently loaded on the system. In case of **name**, 6099f9863aSPaul Chaignon *MAP* may match several maps which will all be shown. 61ff69c21aSJakub Kicinski 62ff69c21aSJakub Kicinski Output will start with map ID followed by map type and 63ff69c21aSJakub Kicinski zero or more named attributes (depending on kernel version). 64ff69c21aSJakub Kicinski 650b592b5aSJakub Kicinski **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*] 660b592b5aSJakub Kicinski Create a new map with given parameters and pin it to *bpffs* 670b592b5aSJakub Kicinski as *FILE*. 680b592b5aSJakub Kicinski 69ff69c21aSJakub Kicinski **bpftool map dump** *MAP* 7099f9863aSPaul Chaignon Dump all entries in a given *MAP*. In case of **name**, 7199f9863aSPaul Chaignon *MAP* may match several maps which will all be dumped. 72ff69c21aSJakub Kicinski 737d7209cbSStanislav Fomichev **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 74ff69c21aSJakub Kicinski Update map entry for a given *KEY*. 75ff69c21aSJakub Kicinski 76ff69c21aSJakub Kicinski *UPDATE_FLAGS* can be one of: **any** update existing entry 77ff69c21aSJakub Kicinski or add if doesn't exit; **exist** update only if entry already 78ff69c21aSJakub Kicinski exists; **noexist** update only if entry doesn't exist. 79ff69c21aSJakub Kicinski 800c90f224SQuentin Monnet If the **hex** keyword is provided in front of the bytes 810c90f224SQuentin Monnet sequence, the bytes are parsed as hexadeximal values, even if 820c90f224SQuentin Monnet no "0x" prefix is added. If the keyword is not provided, then 830c90f224SQuentin Monnet the bytes are parsed as decimal values, unless a "0x" prefix 840c90f224SQuentin Monnet (for hexadecimal) or a "0" prefix (for octal) is provided. 850c90f224SQuentin Monnet 868a89fff6SStanislav Fomichev **bpftool map lookup** *MAP* [**key** *DATA*] 87ff69c21aSJakub Kicinski Lookup **key** in the map. 88ff69c21aSJakub Kicinski 89c642ea26SJakub Kicinski **bpftool map getnext** *MAP* [**key** *DATA*] 90ff69c21aSJakub Kicinski Get next key. If *key* is not specified, get first key. 91ff69c21aSJakub Kicinski 92c642ea26SJakub Kicinski **bpftool map delete** *MAP* **key** *DATA* 93ff69c21aSJakub Kicinski Remove entry from the map. 94ff69c21aSJakub Kicinski 95ff69c21aSJakub Kicinski **bpftool map pin** *MAP* *FILE* 96ff69c21aSJakub Kicinski Pin map *MAP* as *FILE*. 97ff69c21aSJakub Kicinski 98882731e0SQuentin Monnet Note: *FILE* must be located in *bpffs* mount. It must not 99882731e0SQuentin Monnet contain a dot character ('.'), which is reserved for future 100882731e0SQuentin Monnet extensions of *bpffs*. 101ff69c21aSJakub Kicinski 102f412eed9SJakub Kicinski **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 103f412eed9SJakub Kicinski Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map. 104f412eed9SJakub Kicinski 105f412eed9SJakub Kicinski Install perf rings into a perf event array map and dump 106f412eed9SJakub Kicinski output of any bpf_perf_event_output() call in the kernel. 107f412eed9SJakub Kicinski By default read the number of CPUs on the system and 108f412eed9SJakub Kicinski install perf ring for each CPU in the corresponding index 109f412eed9SJakub Kicinski in the array. 110f412eed9SJakub Kicinski 111f412eed9SJakub Kicinski If **cpu** and **index** are specified, install perf ring 112f412eed9SJakub Kicinski for given **cpu** at **index** in the array (single ring). 113f412eed9SJakub Kicinski 114f412eed9SJakub Kicinski Note that installing a perf ring into an array will silently 115f412eed9SJakub Kicinski replace any existing ring. Any other application will stop 116f412eed9SJakub Kicinski receiving events if it installed its rings earlier. 117f412eed9SJakub Kicinski 11866cf6e0bSStanislav Fomichev **bpftool map peek** *MAP* 11966cf6e0bSStanislav Fomichev Peek next **value** in the queue or stack. 12066cf6e0bSStanislav Fomichev 121549d4d3dSStanislav Fomichev **bpftool map push** *MAP* **value** *VALUE* 122549d4d3dSStanislav Fomichev Push **value** onto the stack. 123549d4d3dSStanislav Fomichev 12474f312efSStanislav Fomichev **bpftool map pop** *MAP* 12574f312efSStanislav Fomichev Pop and print **value** from the stack. 12674f312efSStanislav Fomichev 127549d4d3dSStanislav Fomichev **bpftool map enqueue** *MAP* **value** *VALUE* 128549d4d3dSStanislav Fomichev Enqueue **value** into the queue. 129549d4d3dSStanislav Fomichev 13074f312efSStanislav Fomichev **bpftool map dequeue** *MAP* 13174f312efSStanislav Fomichev Dequeue and print **value** from the queue. 13274f312efSStanislav Fomichev 1330bb52b0dSQuentin Monnet **bpftool map freeze** *MAP* 1340bb52b0dSQuentin Monnet Freeze the map as read-only from user space. Entries from a 1350bb52b0dSQuentin Monnet frozen map can not longer be updated or deleted with the 1360bb52b0dSQuentin Monnet **bpf\ ()** system call. This operation is not reversible, 1370bb52b0dSQuentin Monnet and the map remains immutable from user space until its 1380bb52b0dSQuentin Monnet destruction. However, read and write permissions for BPF 1390bb52b0dSQuentin Monnet programs to the map remain unchanged. 1400bb52b0dSQuentin Monnet 141ff69c21aSJakub Kicinski **bpftool map help** 142ff69c21aSJakub Kicinski Print short help message. 143ff69c21aSJakub Kicinski 144a2bc2e5cSQuentin MonnetOPTIONS 145a2bc2e5cSQuentin Monnet======= 146a2bc2e5cSQuentin Monnet -h, --help 147a2bc2e5cSQuentin Monnet Print short generic help message (similar to **bpftool help**). 148a2bc2e5cSQuentin Monnet 14988b3eed8SQuentin Monnet -V, --version 150a2bc2e5cSQuentin Monnet Print version number (similar to **bpftool version**). 151a2bc2e5cSQuentin Monnet 1520641c3c8SQuentin Monnet -j, --json 1530641c3c8SQuentin Monnet Generate JSON output. For commands that cannot produce JSON, this 1540641c3c8SQuentin Monnet option has no effect. 1550641c3c8SQuentin Monnet 1560641c3c8SQuentin Monnet -p, --pretty 1570641c3c8SQuentin Monnet Generate human-readable JSON output. Implies **-j**. 1580641c3c8SQuentin Monnet 159c541b734SPrashant Bhole -f, --bpffs 160c541b734SPrashant Bhole Show file names of pinned maps. 161c541b734SPrashant Bhole 16233221307SQuentin Monnet -n, --nomount 16333221307SQuentin Monnet Do not automatically attempt to mount any virtual file system 16433221307SQuentin Monnet (such as tracefs or BPF virtual file system) when necessary. 16533221307SQuentin Monnet 166775bc8adSQuentin Monnet -d, --debug 167775bc8adSQuentin Monnet Print all logs available from libbpf, including debug-level 168775bc8adSQuentin Monnet information. 169775bc8adSQuentin Monnet 170ff69c21aSJakub KicinskiEXAMPLES 171ff69c21aSJakub Kicinski======== 172ff69c21aSJakub Kicinski**# bpftool map show** 173ff69c21aSJakub Kicinski:: 174ff69c21aSJakub Kicinski 175ff69c21aSJakub Kicinski 10: hash name some_map flags 0x0 176ff69c21aSJakub Kicinski key 4B value 8B max_entries 2048 memlock 167936B 177ff69c21aSJakub Kicinski 1780c90f224SQuentin MonnetThe following three commands are equivalent: 1790c90f224SQuentin Monnet 1800c90f224SQuentin Monnet| 1810c90f224SQuentin Monnet| **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c** 1820c90f224SQuentin Monnet| **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c** 1830c90f224SQuentin Monnet| **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76** 184ff69c21aSJakub Kicinski 185ff69c21aSJakub Kicinski**# bpftool map lookup id 10 key 0 1 2 3** 186ff69c21aSJakub Kicinski 187ff69c21aSJakub Kicinski:: 188ff69c21aSJakub Kicinski 189ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 190ff69c21aSJakub Kicinski 191ff69c21aSJakub Kicinski 192ff69c21aSJakub Kicinski**# bpftool map dump id 10** 193ff69c21aSJakub Kicinski:: 194ff69c21aSJakub Kicinski 195ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 196ff69c21aSJakub Kicinski key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 197ff69c21aSJakub Kicinski Found 2 elements 198ff69c21aSJakub Kicinski 199ff69c21aSJakub Kicinski**# bpftool map getnext id 10 key 0 1 2 3** 200ff69c21aSJakub Kicinski:: 201ff69c21aSJakub Kicinski 202ff69c21aSJakub Kicinski key: 203ff69c21aSJakub Kicinski 00 01 02 03 204ff69c21aSJakub Kicinski next key: 205ff69c21aSJakub Kicinski 0d 00 07 00 206ff69c21aSJakub Kicinski 207ff69c21aSJakub Kicinski| 208ff69c21aSJakub Kicinski| **# mount -t bpf none /sys/fs/bpf/** 209ff69c21aSJakub Kicinski| **# bpftool map pin id 10 /sys/fs/bpf/map** 210ff69c21aSJakub Kicinski| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00** 211ff69c21aSJakub Kicinski 212bd0fb9d0SQuentin MonnetNote that map update can also be used in order to change the program references 213bd0fb9d0SQuentin Monnethold by a program array map. This can be used, for example, to change the 214bd0fb9d0SQuentin Monnetprograms used for tail-call jumps at runtime, without having to reload the 215bd0fb9d0SQuentin Monnetentry-point program. Below is an example for this use case: we load a program 216bd0fb9d0SQuentin Monnetdefining a prog array map, and with a main function that contains a tail call 217bd0fb9d0SQuentin Monnetto other programs that can be used either to "process" packets or to "debug" 218bd0fb9d0SQuentin Monnetprocessing. Note that the prog array map MUST be pinned into the BPF virtual 219bd0fb9d0SQuentin Monnetfile system for the map update to work successfully, as kernel flushes prog 220bd0fb9d0SQuentin Monnetarray maps when they have no more references from user space (and the update 221bd0fb9d0SQuentin Monnetwould be lost as soon as bpftool exits). 222bd0fb9d0SQuentin Monnet 223bd0fb9d0SQuentin Monnet| 224bd0fb9d0SQuentin Monnet| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp** 225bd0fb9d0SQuentin Monnet| **# bpftool prog --bpffs** 226bd0fb9d0SQuentin Monnet 227bd0fb9d0SQuentin Monnet:: 228bd0fb9d0SQuentin Monnet 229bd0fb9d0SQuentin Monnet 545: xdp name main_func tag 674b4b5597193dc3 gpl 230bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 231bd0fb9d0SQuentin Monnet xlated 240B jited 257B memlock 4096B map_ids 294 232bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/xdp 233bd0fb9d0SQuentin Monnet 546: xdp name bpf_func_process tag e369a529024751fc gpl 234bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 235bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 236bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/process 237bd0fb9d0SQuentin Monnet 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl 238bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 239bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 240bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/debug 241bd0fb9d0SQuentin Monnet 242bd0fb9d0SQuentin Monnet**# bpftool map** 243bd0fb9d0SQuentin Monnet 244bd0fb9d0SQuentin Monnet:: 245bd0fb9d0SQuentin Monnet 246bd0fb9d0SQuentin Monnet 294: prog_array name jmp_table flags 0x0 247bd0fb9d0SQuentin Monnet key 4B value 4B max_entries 1 memlock 4096B 248bd0fb9d0SQuentin Monnet owner_prog_type xdp owner jited 249bd0fb9d0SQuentin Monnet 250bd0fb9d0SQuentin Monnet| 251bd0fb9d0SQuentin Monnet| **# bpftool map pin id 294 /sys/fs/bpf/bar** 252bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 253bd0fb9d0SQuentin Monnet 254bd0fb9d0SQuentin Monnet:: 255bd0fb9d0SQuentin Monnet 256bd0fb9d0SQuentin Monnet Found 0 elements 257bd0fb9d0SQuentin Monnet 258bd0fb9d0SQuentin Monnet| 259bd0fb9d0SQuentin Monnet| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug** 260bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 261bd0fb9d0SQuentin Monnet 262bd0fb9d0SQuentin Monnet:: 263bd0fb9d0SQuentin Monnet 264bd0fb9d0SQuentin Monnet key: 00 00 00 00 value: 22 02 00 00 265bd0fb9d0SQuentin Monnet Found 1 element 266bd0fb9d0SQuentin Monnet 267ff69c21aSJakub KicinskiSEE ALSO 268ff69c21aSJakub Kicinski======== 269f98e46a2SQuentin Monnet **bpf**\ (2), 270f98e46a2SQuentin Monnet **bpf-helpers**\ (7), 271f98e46a2SQuentin Monnet **bpftool**\ (8), 272f98e46a2SQuentin Monnet **bpftool-prog**\ (8), 273f98e46a2SQuentin Monnet **bpftool-cgroup**\ (8), 27449eb7ab3SQuentin Monnet **bpftool-feature**\ (8), 275f98e46a2SQuentin Monnet **bpftool-net**\ (8), 276ca253339SAndrii Nakryiko **bpftool-perf**\ (8), 277ca253339SAndrii Nakryiko **bpftool-btf**\ (8) 278