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| 4247ff7ac6SQuentin Monnet| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 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 58ff69c21aSJakub Kicinski show information only about given map, otherwise list all 59ff69c21aSJakub Kicinski maps currently loaded on the system. 60ff69c21aSJakub Kicinski 61ff69c21aSJakub Kicinski Output will start with map ID followed by map type and 62ff69c21aSJakub Kicinski zero or more named attributes (depending on kernel version). 63ff69c21aSJakub Kicinski 640b592b5aSJakub Kicinski **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*] 650b592b5aSJakub Kicinski Create a new map with given parameters and pin it to *bpffs* 660b592b5aSJakub Kicinski as *FILE*. 670b592b5aSJakub Kicinski 68ff69c21aSJakub Kicinski **bpftool map dump** *MAP* 69ff69c21aSJakub Kicinski Dump all entries in a given *MAP*. 70ff69c21aSJakub Kicinski 717d7209cbSStanislav Fomichev **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 72ff69c21aSJakub Kicinski Update map entry for a given *KEY*. 73ff69c21aSJakub Kicinski 74ff69c21aSJakub Kicinski *UPDATE_FLAGS* can be one of: **any** update existing entry 75ff69c21aSJakub Kicinski or add if doesn't exit; **exist** update only if entry already 76ff69c21aSJakub Kicinski exists; **noexist** update only if entry doesn't exist. 77ff69c21aSJakub Kicinski 780c90f224SQuentin Monnet If the **hex** keyword is provided in front of the bytes 790c90f224SQuentin Monnet sequence, the bytes are parsed as hexadeximal values, even if 800c90f224SQuentin Monnet no "0x" prefix is added. If the keyword is not provided, then 810c90f224SQuentin Monnet the bytes are parsed as decimal values, unless a "0x" prefix 820c90f224SQuentin Monnet (for hexadecimal) or a "0" prefix (for octal) is provided. 830c90f224SQuentin Monnet 848a89fff6SStanislav Fomichev **bpftool map lookup** *MAP* [**key** *DATA*] 85ff69c21aSJakub Kicinski Lookup **key** in the map. 86ff69c21aSJakub Kicinski 87c642ea26SJakub Kicinski **bpftool map getnext** *MAP* [**key** *DATA*] 88ff69c21aSJakub Kicinski Get next key. If *key* is not specified, get first key. 89ff69c21aSJakub Kicinski 90c642ea26SJakub Kicinski **bpftool map delete** *MAP* **key** *DATA* 91ff69c21aSJakub Kicinski Remove entry from the map. 92ff69c21aSJakub Kicinski 93ff69c21aSJakub Kicinski **bpftool map pin** *MAP* *FILE* 94ff69c21aSJakub Kicinski Pin map *MAP* as *FILE*. 95ff69c21aSJakub Kicinski 96882731e0SQuentin Monnet Note: *FILE* must be located in *bpffs* mount. It must not 97882731e0SQuentin Monnet contain a dot character ('.'), which is reserved for future 98882731e0SQuentin Monnet extensions of *bpffs*. 99ff69c21aSJakub Kicinski 100f412eed9SJakub Kicinski **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 101f412eed9SJakub Kicinski Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map. 102f412eed9SJakub Kicinski 103f412eed9SJakub Kicinski Install perf rings into a perf event array map and dump 104f412eed9SJakub Kicinski output of any bpf_perf_event_output() call in the kernel. 105f412eed9SJakub Kicinski By default read the number of CPUs on the system and 106f412eed9SJakub Kicinski install perf ring for each CPU in the corresponding index 107f412eed9SJakub Kicinski in the array. 108f412eed9SJakub Kicinski 109f412eed9SJakub Kicinski If **cpu** and **index** are specified, install perf ring 110f412eed9SJakub Kicinski for given **cpu** at **index** in the array (single ring). 111f412eed9SJakub Kicinski 112f412eed9SJakub Kicinski Note that installing a perf ring into an array will silently 113f412eed9SJakub Kicinski replace any existing ring. Any other application will stop 114f412eed9SJakub Kicinski receiving events if it installed its rings earlier. 115f412eed9SJakub Kicinski 11666cf6e0bSStanislav Fomichev **bpftool map peek** *MAP* 11766cf6e0bSStanislav Fomichev Peek next **value** in the queue or stack. 11866cf6e0bSStanislav Fomichev 119549d4d3dSStanislav Fomichev **bpftool map push** *MAP* **value** *VALUE* 120549d4d3dSStanislav Fomichev Push **value** onto the stack. 121549d4d3dSStanislav Fomichev 12274f312efSStanislav Fomichev **bpftool map pop** *MAP* 12374f312efSStanislav Fomichev Pop and print **value** from the stack. 12474f312efSStanislav Fomichev 125549d4d3dSStanislav Fomichev **bpftool map enqueue** *MAP* **value** *VALUE* 126549d4d3dSStanislav Fomichev Enqueue **value** into the queue. 127549d4d3dSStanislav Fomichev 12874f312efSStanislav Fomichev **bpftool map dequeue** *MAP* 12974f312efSStanislav Fomichev Dequeue and print **value** from the queue. 13074f312efSStanislav Fomichev 1310bb52b0dSQuentin Monnet **bpftool map freeze** *MAP* 1320bb52b0dSQuentin Monnet Freeze the map as read-only from user space. Entries from a 1330bb52b0dSQuentin Monnet frozen map can not longer be updated or deleted with the 1340bb52b0dSQuentin Monnet **bpf\ ()** system call. This operation is not reversible, 1350bb52b0dSQuentin Monnet and the map remains immutable from user space until its 1360bb52b0dSQuentin Monnet destruction. However, read and write permissions for BPF 1370bb52b0dSQuentin Monnet programs to the map remain unchanged. 1380bb52b0dSQuentin Monnet 139ff69c21aSJakub Kicinski **bpftool map help** 140ff69c21aSJakub Kicinski Print short help message. 141ff69c21aSJakub Kicinski 142a2bc2e5cSQuentin MonnetOPTIONS 143a2bc2e5cSQuentin Monnet======= 144a2bc2e5cSQuentin Monnet -h, --help 145a2bc2e5cSQuentin Monnet Print short generic help message (similar to **bpftool help**). 146a2bc2e5cSQuentin Monnet 14788b3eed8SQuentin Monnet -V, --version 148a2bc2e5cSQuentin Monnet Print version number (similar to **bpftool version**). 149a2bc2e5cSQuentin Monnet 1500641c3c8SQuentin Monnet -j, --json 1510641c3c8SQuentin Monnet Generate JSON output. For commands that cannot produce JSON, this 1520641c3c8SQuentin Monnet option has no effect. 1530641c3c8SQuentin Monnet 1540641c3c8SQuentin Monnet -p, --pretty 1550641c3c8SQuentin Monnet Generate human-readable JSON output. Implies **-j**. 1560641c3c8SQuentin Monnet 157c541b734SPrashant Bhole -f, --bpffs 158c541b734SPrashant Bhole Show file names of pinned maps. 159c541b734SPrashant Bhole 16033221307SQuentin Monnet -n, --nomount 16133221307SQuentin Monnet Do not automatically attempt to mount any virtual file system 16233221307SQuentin Monnet (such as tracefs or BPF virtual file system) when necessary. 16333221307SQuentin Monnet 164775bc8adSQuentin Monnet -d, --debug 165775bc8adSQuentin Monnet Print all logs available from libbpf, including debug-level 166775bc8adSQuentin Monnet information. 167775bc8adSQuentin Monnet 168ff69c21aSJakub KicinskiEXAMPLES 169ff69c21aSJakub Kicinski======== 170ff69c21aSJakub Kicinski**# bpftool map show** 171ff69c21aSJakub Kicinski:: 172ff69c21aSJakub Kicinski 173ff69c21aSJakub Kicinski 10: hash name some_map flags 0x0 174ff69c21aSJakub Kicinski key 4B value 8B max_entries 2048 memlock 167936B 175ff69c21aSJakub Kicinski 1760c90f224SQuentin MonnetThe following three commands are equivalent: 1770c90f224SQuentin Monnet 1780c90f224SQuentin Monnet| 1790c90f224SQuentin Monnet| **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c** 1800c90f224SQuentin Monnet| **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c** 1810c90f224SQuentin Monnet| **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76** 182ff69c21aSJakub Kicinski 183ff69c21aSJakub Kicinski**# bpftool map lookup id 10 key 0 1 2 3** 184ff69c21aSJakub Kicinski 185ff69c21aSJakub Kicinski:: 186ff69c21aSJakub Kicinski 187ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 188ff69c21aSJakub Kicinski 189ff69c21aSJakub Kicinski 190ff69c21aSJakub Kicinski**# bpftool map dump id 10** 191ff69c21aSJakub Kicinski:: 192ff69c21aSJakub Kicinski 193ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 194ff69c21aSJakub Kicinski key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 195ff69c21aSJakub Kicinski Found 2 elements 196ff69c21aSJakub Kicinski 197ff69c21aSJakub Kicinski**# bpftool map getnext id 10 key 0 1 2 3** 198ff69c21aSJakub Kicinski:: 199ff69c21aSJakub Kicinski 200ff69c21aSJakub Kicinski key: 201ff69c21aSJakub Kicinski 00 01 02 03 202ff69c21aSJakub Kicinski next key: 203ff69c21aSJakub Kicinski 0d 00 07 00 204ff69c21aSJakub Kicinski 205ff69c21aSJakub Kicinski| 206ff69c21aSJakub Kicinski| **# mount -t bpf none /sys/fs/bpf/** 207ff69c21aSJakub Kicinski| **# bpftool map pin id 10 /sys/fs/bpf/map** 208ff69c21aSJakub Kicinski| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00** 209ff69c21aSJakub Kicinski 210bd0fb9d0SQuentin MonnetNote that map update can also be used in order to change the program references 211bd0fb9d0SQuentin Monnethold by a program array map. This can be used, for example, to change the 212bd0fb9d0SQuentin Monnetprograms used for tail-call jumps at runtime, without having to reload the 213bd0fb9d0SQuentin Monnetentry-point program. Below is an example for this use case: we load a program 214bd0fb9d0SQuentin Monnetdefining a prog array map, and with a main function that contains a tail call 215bd0fb9d0SQuentin Monnetto other programs that can be used either to "process" packets or to "debug" 216bd0fb9d0SQuentin Monnetprocessing. Note that the prog array map MUST be pinned into the BPF virtual 217bd0fb9d0SQuentin Monnetfile system for the map update to work successfully, as kernel flushes prog 218bd0fb9d0SQuentin Monnetarray maps when they have no more references from user space (and the update 219bd0fb9d0SQuentin Monnetwould be lost as soon as bpftool exits). 220bd0fb9d0SQuentin Monnet 221bd0fb9d0SQuentin Monnet| 222bd0fb9d0SQuentin Monnet| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp** 223bd0fb9d0SQuentin Monnet| **# bpftool prog --bpffs** 224bd0fb9d0SQuentin Monnet 225bd0fb9d0SQuentin Monnet:: 226bd0fb9d0SQuentin Monnet 227bd0fb9d0SQuentin Monnet 545: xdp name main_func tag 674b4b5597193dc3 gpl 228bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 229bd0fb9d0SQuentin Monnet xlated 240B jited 257B memlock 4096B map_ids 294 230bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/xdp 231bd0fb9d0SQuentin Monnet 546: xdp name bpf_func_process tag e369a529024751fc gpl 232bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 233bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 234bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/process 235bd0fb9d0SQuentin Monnet 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl 236bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 237bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 238bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/debug 239bd0fb9d0SQuentin Monnet 240bd0fb9d0SQuentin Monnet**# bpftool map** 241bd0fb9d0SQuentin Monnet 242bd0fb9d0SQuentin Monnet:: 243bd0fb9d0SQuentin Monnet 244bd0fb9d0SQuentin Monnet 294: prog_array name jmp_table flags 0x0 245bd0fb9d0SQuentin Monnet key 4B value 4B max_entries 1 memlock 4096B 246bd0fb9d0SQuentin Monnet owner_prog_type xdp owner jited 247bd0fb9d0SQuentin Monnet 248bd0fb9d0SQuentin Monnet| 249bd0fb9d0SQuentin Monnet| **# bpftool map pin id 294 /sys/fs/bpf/bar** 250bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 251bd0fb9d0SQuentin Monnet 252bd0fb9d0SQuentin Monnet:: 253bd0fb9d0SQuentin Monnet 254bd0fb9d0SQuentin Monnet Found 0 elements 255bd0fb9d0SQuentin Monnet 256bd0fb9d0SQuentin Monnet| 257bd0fb9d0SQuentin Monnet| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug** 258bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 259bd0fb9d0SQuentin Monnet 260bd0fb9d0SQuentin Monnet:: 261bd0fb9d0SQuentin Monnet 262bd0fb9d0SQuentin Monnet key: 00 00 00 00 value: 22 02 00 00 263bd0fb9d0SQuentin Monnet Found 1 element 264bd0fb9d0SQuentin Monnet 265ff69c21aSJakub KicinskiSEE ALSO 266ff69c21aSJakub Kicinski======== 267f98e46a2SQuentin Monnet **bpf**\ (2), 268f98e46a2SQuentin Monnet **bpf-helpers**\ (7), 269f98e46a2SQuentin Monnet **bpftool**\ (8), 270f98e46a2SQuentin Monnet **bpftool-prog**\ (8), 271f98e46a2SQuentin Monnet **bpftool-cgroup**\ (8), 27249eb7ab3SQuentin Monnet **bpftool-feature**\ (8), 273f98e46a2SQuentin Monnet **bpftool-net**\ (8), 274ca253339SAndrii Nakryiko **bpftool-perf**\ (8), 275ca253339SAndrii Nakryiko **bpftool-btf**\ (8) 276