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* 3947ff7ac6SQuentin Monnet| **bpftool** **map help** 40ff69c21aSJakub Kicinski| 4147ff7ac6SQuentin Monnet| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 42c642ea26SJakub Kicinski| *DATA* := { [**hex**] *BYTES* } 432148481dSQuentin Monnet| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 44c642ea26SJakub Kicinski| *VALUE* := { *DATA* | *MAP* | *PROG* } 4547ff7ac6SQuentin Monnet| *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 460b592b5aSJakub Kicinski| *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 470b592b5aSJakub Kicinski| | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 480b592b5aSJakub Kicinski| | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 490b592b5aSJakub Kicinski| | **devmap** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 50197c2dacSDavid Calavera| | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 51197c2dacSDavid Calavera| | **queue** | **stack** } 52ff69c21aSJakub Kicinski 53ff69c21aSJakub KicinskiDESCRIPTION 54ff69c21aSJakub Kicinski=========== 556ebe6dbdSJakub Kicinski **bpftool map { show | list }** [*MAP*] 56ff69c21aSJakub Kicinski Show information about loaded maps. If *MAP* is specified 57ff69c21aSJakub Kicinski show information only about given map, otherwise list all 58ff69c21aSJakub Kicinski maps currently loaded on the system. 59ff69c21aSJakub Kicinski 60ff69c21aSJakub Kicinski Output will start with map ID followed by map type and 61ff69c21aSJakub Kicinski zero or more named attributes (depending on kernel version). 62ff69c21aSJakub Kicinski 630b592b5aSJakub Kicinski **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*] 640b592b5aSJakub Kicinski Create a new map with given parameters and pin it to *bpffs* 650b592b5aSJakub Kicinski as *FILE*. 660b592b5aSJakub Kicinski 67ff69c21aSJakub Kicinski **bpftool map dump** *MAP* 68ff69c21aSJakub Kicinski Dump all entries in a given *MAP*. 69ff69c21aSJakub Kicinski 707d7209cbSStanislav Fomichev **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 71ff69c21aSJakub Kicinski Update map entry for a given *KEY*. 72ff69c21aSJakub Kicinski 73ff69c21aSJakub Kicinski *UPDATE_FLAGS* can be one of: **any** update existing entry 74ff69c21aSJakub Kicinski or add if doesn't exit; **exist** update only if entry already 75ff69c21aSJakub Kicinski exists; **noexist** update only if entry doesn't exist. 76ff69c21aSJakub Kicinski 770c90f224SQuentin Monnet If the **hex** keyword is provided in front of the bytes 780c90f224SQuentin Monnet sequence, the bytes are parsed as hexadeximal values, even if 790c90f224SQuentin Monnet no "0x" prefix is added. If the keyword is not provided, then 800c90f224SQuentin Monnet the bytes are parsed as decimal values, unless a "0x" prefix 810c90f224SQuentin Monnet (for hexadecimal) or a "0" prefix (for octal) is provided. 820c90f224SQuentin Monnet 838a89fff6SStanislav Fomichev **bpftool map lookup** *MAP* [**key** *DATA*] 84ff69c21aSJakub Kicinski Lookup **key** in the map. 85ff69c21aSJakub Kicinski 86c642ea26SJakub Kicinski **bpftool map getnext** *MAP* [**key** *DATA*] 87ff69c21aSJakub Kicinski Get next key. If *key* is not specified, get first key. 88ff69c21aSJakub Kicinski 89c642ea26SJakub Kicinski **bpftool map delete** *MAP* **key** *DATA* 90ff69c21aSJakub Kicinski Remove entry from the map. 91ff69c21aSJakub Kicinski 92ff69c21aSJakub Kicinski **bpftool map pin** *MAP* *FILE* 93ff69c21aSJakub Kicinski Pin map *MAP* as *FILE*. 94ff69c21aSJakub Kicinski 95882731e0SQuentin Monnet Note: *FILE* must be located in *bpffs* mount. It must not 96882731e0SQuentin Monnet contain a dot character ('.'), which is reserved for future 97882731e0SQuentin Monnet extensions of *bpffs*. 98ff69c21aSJakub Kicinski 99f412eed9SJakub Kicinski **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 100f412eed9SJakub Kicinski Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map. 101f412eed9SJakub Kicinski 102f412eed9SJakub Kicinski Install perf rings into a perf event array map and dump 103f412eed9SJakub Kicinski output of any bpf_perf_event_output() call in the kernel. 104f412eed9SJakub Kicinski By default read the number of CPUs on the system and 105f412eed9SJakub Kicinski install perf ring for each CPU in the corresponding index 106f412eed9SJakub Kicinski in the array. 107f412eed9SJakub Kicinski 108f412eed9SJakub Kicinski If **cpu** and **index** are specified, install perf ring 109f412eed9SJakub Kicinski for given **cpu** at **index** in the array (single ring). 110f412eed9SJakub Kicinski 111f412eed9SJakub Kicinski Note that installing a perf ring into an array will silently 112f412eed9SJakub Kicinski replace any existing ring. Any other application will stop 113f412eed9SJakub Kicinski receiving events if it installed its rings earlier. 114f412eed9SJakub Kicinski 11566cf6e0bSStanislav Fomichev **bpftool map peek** *MAP* 11666cf6e0bSStanislav Fomichev Peek next **value** in the queue or stack. 11766cf6e0bSStanislav Fomichev 118549d4d3dSStanislav Fomichev **bpftool map push** *MAP* **value** *VALUE* 119549d4d3dSStanislav Fomichev Push **value** onto the stack. 120549d4d3dSStanislav Fomichev 12174f312efSStanislav Fomichev **bpftool map pop** *MAP* 12274f312efSStanislav Fomichev Pop and print **value** from the stack. 12374f312efSStanislav Fomichev 124549d4d3dSStanislav Fomichev **bpftool map enqueue** *MAP* **value** *VALUE* 125549d4d3dSStanislav Fomichev Enqueue **value** into the queue. 126549d4d3dSStanislav Fomichev 12774f312efSStanislav Fomichev **bpftool map dequeue** *MAP* 12874f312efSStanislav Fomichev Dequeue and print **value** from the queue. 12974f312efSStanislav Fomichev 130ff69c21aSJakub Kicinski **bpftool map help** 131ff69c21aSJakub Kicinski Print short help message. 132ff69c21aSJakub Kicinski 133a2bc2e5cSQuentin MonnetOPTIONS 134a2bc2e5cSQuentin Monnet======= 135a2bc2e5cSQuentin Monnet -h, --help 136a2bc2e5cSQuentin Monnet Print short generic help message (similar to **bpftool help**). 137a2bc2e5cSQuentin Monnet 13888b3eed8SQuentin Monnet -V, --version 139a2bc2e5cSQuentin Monnet Print version number (similar to **bpftool version**). 140a2bc2e5cSQuentin Monnet 1410641c3c8SQuentin Monnet -j, --json 1420641c3c8SQuentin Monnet Generate JSON output. For commands that cannot produce JSON, this 1430641c3c8SQuentin Monnet option has no effect. 1440641c3c8SQuentin Monnet 1450641c3c8SQuentin Monnet -p, --pretty 1460641c3c8SQuentin Monnet Generate human-readable JSON output. Implies **-j**. 1470641c3c8SQuentin Monnet 148c541b734SPrashant Bhole -f, --bpffs 149c541b734SPrashant Bhole Show file names of pinned maps. 150c541b734SPrashant Bhole 15133221307SQuentin Monnet -n, --nomount 15233221307SQuentin Monnet Do not automatically attempt to mount any virtual file system 15333221307SQuentin Monnet (such as tracefs or BPF virtual file system) when necessary. 15433221307SQuentin Monnet 155775bc8adSQuentin Monnet -d, --debug 156775bc8adSQuentin Monnet Print all logs available from libbpf, including debug-level 157775bc8adSQuentin Monnet information. 158775bc8adSQuentin Monnet 159ff69c21aSJakub KicinskiEXAMPLES 160ff69c21aSJakub Kicinski======== 161ff69c21aSJakub Kicinski**# bpftool map show** 162ff69c21aSJakub Kicinski:: 163ff69c21aSJakub Kicinski 164ff69c21aSJakub Kicinski 10: hash name some_map flags 0x0 165ff69c21aSJakub Kicinski key 4B value 8B max_entries 2048 memlock 167936B 166ff69c21aSJakub Kicinski 1670c90f224SQuentin MonnetThe following three commands are equivalent: 1680c90f224SQuentin Monnet 1690c90f224SQuentin Monnet| 1700c90f224SQuentin Monnet| **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c** 1710c90f224SQuentin Monnet| **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c** 1720c90f224SQuentin Monnet| **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76** 173ff69c21aSJakub Kicinski 174ff69c21aSJakub Kicinski**# bpftool map lookup id 10 key 0 1 2 3** 175ff69c21aSJakub Kicinski 176ff69c21aSJakub Kicinski:: 177ff69c21aSJakub Kicinski 178ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 179ff69c21aSJakub Kicinski 180ff69c21aSJakub Kicinski 181ff69c21aSJakub Kicinski**# bpftool map dump id 10** 182ff69c21aSJakub Kicinski:: 183ff69c21aSJakub Kicinski 184ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 185ff69c21aSJakub Kicinski key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 186ff69c21aSJakub Kicinski Found 2 elements 187ff69c21aSJakub Kicinski 188ff69c21aSJakub Kicinski**# bpftool map getnext id 10 key 0 1 2 3** 189ff69c21aSJakub Kicinski:: 190ff69c21aSJakub Kicinski 191ff69c21aSJakub Kicinski key: 192ff69c21aSJakub Kicinski 00 01 02 03 193ff69c21aSJakub Kicinski next key: 194ff69c21aSJakub Kicinski 0d 00 07 00 195ff69c21aSJakub Kicinski 196ff69c21aSJakub Kicinski| 197ff69c21aSJakub Kicinski| **# mount -t bpf none /sys/fs/bpf/** 198ff69c21aSJakub Kicinski| **# bpftool map pin id 10 /sys/fs/bpf/map** 199ff69c21aSJakub Kicinski| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00** 200ff69c21aSJakub Kicinski 201bd0fb9d0SQuentin MonnetNote that map update can also be used in order to change the program references 202bd0fb9d0SQuentin Monnethold by a program array map. This can be used, for example, to change the 203bd0fb9d0SQuentin Monnetprograms used for tail-call jumps at runtime, without having to reload the 204bd0fb9d0SQuentin Monnetentry-point program. Below is an example for this use case: we load a program 205bd0fb9d0SQuentin Monnetdefining a prog array map, and with a main function that contains a tail call 206bd0fb9d0SQuentin Monnetto other programs that can be used either to "process" packets or to "debug" 207bd0fb9d0SQuentin Monnetprocessing. Note that the prog array map MUST be pinned into the BPF virtual 208bd0fb9d0SQuentin Monnetfile system for the map update to work successfully, as kernel flushes prog 209bd0fb9d0SQuentin Monnetarray maps when they have no more references from user space (and the update 210bd0fb9d0SQuentin Monnetwould be lost as soon as bpftool exits). 211bd0fb9d0SQuentin Monnet 212bd0fb9d0SQuentin Monnet| 213bd0fb9d0SQuentin Monnet| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp** 214bd0fb9d0SQuentin Monnet| **# bpftool prog --bpffs** 215bd0fb9d0SQuentin Monnet 216bd0fb9d0SQuentin Monnet:: 217bd0fb9d0SQuentin Monnet 218bd0fb9d0SQuentin Monnet 545: xdp name main_func tag 674b4b5597193dc3 gpl 219bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 220bd0fb9d0SQuentin Monnet xlated 240B jited 257B memlock 4096B map_ids 294 221bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/xdp 222bd0fb9d0SQuentin Monnet 546: xdp name bpf_func_process tag e369a529024751fc gpl 223bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 224bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 225bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/process 226bd0fb9d0SQuentin Monnet 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl 227bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 228bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 229bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/debug 230bd0fb9d0SQuentin Monnet 231bd0fb9d0SQuentin Monnet**# bpftool map** 232bd0fb9d0SQuentin Monnet 233bd0fb9d0SQuentin Monnet:: 234bd0fb9d0SQuentin Monnet 235bd0fb9d0SQuentin Monnet 294: prog_array name jmp_table flags 0x0 236bd0fb9d0SQuentin Monnet key 4B value 4B max_entries 1 memlock 4096B 237bd0fb9d0SQuentin Monnet owner_prog_type xdp owner jited 238bd0fb9d0SQuentin Monnet 239bd0fb9d0SQuentin Monnet| 240bd0fb9d0SQuentin Monnet| **# bpftool map pin id 294 /sys/fs/bpf/bar** 241bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 242bd0fb9d0SQuentin Monnet 243bd0fb9d0SQuentin Monnet:: 244bd0fb9d0SQuentin Monnet 245bd0fb9d0SQuentin Monnet Found 0 elements 246bd0fb9d0SQuentin Monnet 247bd0fb9d0SQuentin Monnet| 248bd0fb9d0SQuentin Monnet| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug** 249bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 250bd0fb9d0SQuentin Monnet 251bd0fb9d0SQuentin Monnet:: 252bd0fb9d0SQuentin Monnet 253bd0fb9d0SQuentin Monnet key: 00 00 00 00 value: 22 02 00 00 254bd0fb9d0SQuentin Monnet Found 1 element 255bd0fb9d0SQuentin Monnet 256ff69c21aSJakub KicinskiSEE ALSO 257ff69c21aSJakub Kicinski======== 258f98e46a2SQuentin Monnet **bpf**\ (2), 259f98e46a2SQuentin Monnet **bpf-helpers**\ (7), 260f98e46a2SQuentin Monnet **bpftool**\ (8), 261f98e46a2SQuentin Monnet **bpftool-prog**\ (8), 262f98e46a2SQuentin Monnet **bpftool-cgroup**\ (8), 26349eb7ab3SQuentin Monnet **bpftool-feature**\ (8), 264f98e46a2SQuentin Monnet **bpftool-net**\ (8), 265ca253339SAndrii Nakryiko **bpftool-perf**\ (8), 266ca253339SAndrii Nakryiko **bpftool-btf**\ (8) 267