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* 36549d4d3dSStanislav Fomichev| **bpftool** **map enqueue** *MAP* **value** *VALUE* 3747ff7ac6SQuentin Monnet| **bpftool** **map help** 38ff69c21aSJakub Kicinski| 3947ff7ac6SQuentin Monnet| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 40c642ea26SJakub Kicinski| *DATA* := { [**hex**] *BYTES* } 412148481dSQuentin Monnet| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 42c642ea26SJakub Kicinski| *VALUE* := { *DATA* | *MAP* | *PROG* } 4347ff7ac6SQuentin Monnet| *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 440b592b5aSJakub Kicinski| *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 450b592b5aSJakub Kicinski| | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 460b592b5aSJakub Kicinski| | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 470b592b5aSJakub Kicinski| | **devmap** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 48197c2dacSDavid Calavera| | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 49197c2dacSDavid Calavera| | **queue** | **stack** } 50ff69c21aSJakub Kicinski 51ff69c21aSJakub KicinskiDESCRIPTION 52ff69c21aSJakub Kicinski=========== 536ebe6dbdSJakub Kicinski **bpftool map { show | list }** [*MAP*] 54ff69c21aSJakub Kicinski Show information about loaded maps. If *MAP* is specified 55ff69c21aSJakub Kicinski show information only about given map, otherwise list all 56ff69c21aSJakub Kicinski maps currently loaded on the system. 57ff69c21aSJakub Kicinski 58ff69c21aSJakub Kicinski Output will start with map ID followed by map type and 59ff69c21aSJakub Kicinski zero or more named attributes (depending on kernel version). 60ff69c21aSJakub Kicinski 610b592b5aSJakub Kicinski **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*] 620b592b5aSJakub Kicinski Create a new map with given parameters and pin it to *bpffs* 630b592b5aSJakub Kicinski as *FILE*. 640b592b5aSJakub Kicinski 65ff69c21aSJakub Kicinski **bpftool map dump** *MAP* 66ff69c21aSJakub Kicinski Dump all entries in a given *MAP*. 67ff69c21aSJakub Kicinski 687d7209cbSStanislav Fomichev **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 69ff69c21aSJakub Kicinski Update map entry for a given *KEY*. 70ff69c21aSJakub Kicinski 71ff69c21aSJakub Kicinski *UPDATE_FLAGS* can be one of: **any** update existing entry 72ff69c21aSJakub Kicinski or add if doesn't exit; **exist** update only if entry already 73ff69c21aSJakub Kicinski exists; **noexist** update only if entry doesn't exist. 74ff69c21aSJakub Kicinski 750c90f224SQuentin Monnet If the **hex** keyword is provided in front of the bytes 760c90f224SQuentin Monnet sequence, the bytes are parsed as hexadeximal values, even if 770c90f224SQuentin Monnet no "0x" prefix is added. If the keyword is not provided, then 780c90f224SQuentin Monnet the bytes are parsed as decimal values, unless a "0x" prefix 790c90f224SQuentin Monnet (for hexadecimal) or a "0" prefix (for octal) is provided. 800c90f224SQuentin Monnet 818a89fff6SStanislav Fomichev **bpftool map lookup** *MAP* [**key** *DATA*] 82ff69c21aSJakub Kicinski Lookup **key** in the map. 83ff69c21aSJakub Kicinski 84c642ea26SJakub Kicinski **bpftool map getnext** *MAP* [**key** *DATA*] 85ff69c21aSJakub Kicinski Get next key. If *key* is not specified, get first key. 86ff69c21aSJakub Kicinski 87c642ea26SJakub Kicinski **bpftool map delete** *MAP* **key** *DATA* 88ff69c21aSJakub Kicinski Remove entry from the map. 89ff69c21aSJakub Kicinski 90ff69c21aSJakub Kicinski **bpftool map pin** *MAP* *FILE* 91ff69c21aSJakub Kicinski Pin map *MAP* as *FILE*. 92ff69c21aSJakub Kicinski 93882731e0SQuentin Monnet Note: *FILE* must be located in *bpffs* mount. It must not 94882731e0SQuentin Monnet contain a dot character ('.'), which is reserved for future 95882731e0SQuentin Monnet extensions of *bpffs*. 96ff69c21aSJakub Kicinski 97f412eed9SJakub Kicinski **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 98f412eed9SJakub Kicinski Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map. 99f412eed9SJakub Kicinski 100f412eed9SJakub Kicinski Install perf rings into a perf event array map and dump 101f412eed9SJakub Kicinski output of any bpf_perf_event_output() call in the kernel. 102f412eed9SJakub Kicinski By default read the number of CPUs on the system and 103f412eed9SJakub Kicinski install perf ring for each CPU in the corresponding index 104f412eed9SJakub Kicinski in the array. 105f412eed9SJakub Kicinski 106f412eed9SJakub Kicinski If **cpu** and **index** are specified, install perf ring 107f412eed9SJakub Kicinski for given **cpu** at **index** in the array (single ring). 108f412eed9SJakub Kicinski 109f412eed9SJakub Kicinski Note that installing a perf ring into an array will silently 110f412eed9SJakub Kicinski replace any existing ring. Any other application will stop 111f412eed9SJakub Kicinski receiving events if it installed its rings earlier. 112f412eed9SJakub Kicinski 11366cf6e0bSStanislav Fomichev **bpftool map peek** *MAP* 11466cf6e0bSStanislav Fomichev Peek next **value** in the queue or stack. 11566cf6e0bSStanislav Fomichev 116549d4d3dSStanislav Fomichev **bpftool map push** *MAP* **value** *VALUE* 117549d4d3dSStanislav Fomichev Push **value** onto the stack. 118549d4d3dSStanislav Fomichev 119549d4d3dSStanislav Fomichev **bpftool map enqueue** *MAP* **value** *VALUE* 120549d4d3dSStanislav Fomichev Enqueue **value** into the queue. 121549d4d3dSStanislav Fomichev 122ff69c21aSJakub Kicinski **bpftool map help** 123ff69c21aSJakub Kicinski Print short help message. 124ff69c21aSJakub Kicinski 125a2bc2e5cSQuentin MonnetOPTIONS 126a2bc2e5cSQuentin Monnet======= 127a2bc2e5cSQuentin Monnet -h, --help 128a2bc2e5cSQuentin Monnet Print short generic help message (similar to **bpftool help**). 129a2bc2e5cSQuentin Monnet 130a2bc2e5cSQuentin Monnet -v, --version 131a2bc2e5cSQuentin Monnet Print version number (similar to **bpftool version**). 132a2bc2e5cSQuentin Monnet 1330641c3c8SQuentin Monnet -j, --json 1340641c3c8SQuentin Monnet Generate JSON output. For commands that cannot produce JSON, this 1350641c3c8SQuentin Monnet option has no effect. 1360641c3c8SQuentin Monnet 1370641c3c8SQuentin Monnet -p, --pretty 1380641c3c8SQuentin Monnet Generate human-readable JSON output. Implies **-j**. 1390641c3c8SQuentin Monnet 140c541b734SPrashant Bhole -f, --bpffs 141c541b734SPrashant Bhole Show file names of pinned maps. 142c541b734SPrashant Bhole 14333221307SQuentin Monnet -n, --nomount 14433221307SQuentin Monnet Do not automatically attempt to mount any virtual file system 14533221307SQuentin Monnet (such as tracefs or BPF virtual file system) when necessary. 14633221307SQuentin Monnet 147ff69c21aSJakub KicinskiEXAMPLES 148ff69c21aSJakub Kicinski======== 149ff69c21aSJakub Kicinski**# bpftool map show** 150ff69c21aSJakub Kicinski:: 151ff69c21aSJakub Kicinski 152ff69c21aSJakub Kicinski 10: hash name some_map flags 0x0 153ff69c21aSJakub Kicinski key 4B value 8B max_entries 2048 memlock 167936B 154ff69c21aSJakub Kicinski 1550c90f224SQuentin MonnetThe following three commands are equivalent: 1560c90f224SQuentin Monnet 1570c90f224SQuentin Monnet| 1580c90f224SQuentin Monnet| **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c** 1590c90f224SQuentin Monnet| **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c** 1600c90f224SQuentin Monnet| **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76** 161ff69c21aSJakub Kicinski 162ff69c21aSJakub Kicinski**# bpftool map lookup id 10 key 0 1 2 3** 163ff69c21aSJakub Kicinski 164ff69c21aSJakub Kicinski:: 165ff69c21aSJakub Kicinski 166ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 167ff69c21aSJakub Kicinski 168ff69c21aSJakub Kicinski 169ff69c21aSJakub Kicinski**# bpftool map dump id 10** 170ff69c21aSJakub Kicinski:: 171ff69c21aSJakub Kicinski 172ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 173ff69c21aSJakub Kicinski key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 174ff69c21aSJakub Kicinski Found 2 elements 175ff69c21aSJakub Kicinski 176ff69c21aSJakub Kicinski**# bpftool map getnext id 10 key 0 1 2 3** 177ff69c21aSJakub Kicinski:: 178ff69c21aSJakub Kicinski 179ff69c21aSJakub Kicinski key: 180ff69c21aSJakub Kicinski 00 01 02 03 181ff69c21aSJakub Kicinski next key: 182ff69c21aSJakub Kicinski 0d 00 07 00 183ff69c21aSJakub Kicinski 184ff69c21aSJakub Kicinski| 185ff69c21aSJakub Kicinski| **# mount -t bpf none /sys/fs/bpf/** 186ff69c21aSJakub Kicinski| **# bpftool map pin id 10 /sys/fs/bpf/map** 187ff69c21aSJakub Kicinski| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00** 188ff69c21aSJakub Kicinski 189bd0fb9d0SQuentin MonnetNote that map update can also be used in order to change the program references 190bd0fb9d0SQuentin Monnethold by a program array map. This can be used, for example, to change the 191bd0fb9d0SQuentin Monnetprograms used for tail-call jumps at runtime, without having to reload the 192bd0fb9d0SQuentin Monnetentry-point program. Below is an example for this use case: we load a program 193bd0fb9d0SQuentin Monnetdefining a prog array map, and with a main function that contains a tail call 194bd0fb9d0SQuentin Monnetto other programs that can be used either to "process" packets or to "debug" 195bd0fb9d0SQuentin Monnetprocessing. Note that the prog array map MUST be pinned into the BPF virtual 196bd0fb9d0SQuentin Monnetfile system for the map update to work successfully, as kernel flushes prog 197bd0fb9d0SQuentin Monnetarray maps when they have no more references from user space (and the update 198bd0fb9d0SQuentin Monnetwould be lost as soon as bpftool exits). 199bd0fb9d0SQuentin Monnet 200bd0fb9d0SQuentin Monnet| 201bd0fb9d0SQuentin Monnet| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp** 202bd0fb9d0SQuentin Monnet| **# bpftool prog --bpffs** 203bd0fb9d0SQuentin Monnet 204bd0fb9d0SQuentin Monnet:: 205bd0fb9d0SQuentin Monnet 206bd0fb9d0SQuentin Monnet 545: xdp name main_func tag 674b4b5597193dc3 gpl 207bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 208bd0fb9d0SQuentin Monnet xlated 240B jited 257B memlock 4096B map_ids 294 209bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/xdp 210bd0fb9d0SQuentin Monnet 546: xdp name bpf_func_process tag e369a529024751fc gpl 211bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 212bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 213bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/process 214bd0fb9d0SQuentin Monnet 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl 215bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 216bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 217bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/debug 218bd0fb9d0SQuentin Monnet 219bd0fb9d0SQuentin Monnet**# bpftool map** 220bd0fb9d0SQuentin Monnet 221bd0fb9d0SQuentin Monnet:: 222bd0fb9d0SQuentin Monnet 223bd0fb9d0SQuentin Monnet 294: prog_array name jmp_table flags 0x0 224bd0fb9d0SQuentin Monnet key 4B value 4B max_entries 1 memlock 4096B 225bd0fb9d0SQuentin Monnet owner_prog_type xdp owner jited 226bd0fb9d0SQuentin Monnet 227bd0fb9d0SQuentin Monnet| 228bd0fb9d0SQuentin Monnet| **# bpftool map pin id 294 /sys/fs/bpf/bar** 229bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 230bd0fb9d0SQuentin Monnet 231bd0fb9d0SQuentin Monnet:: 232bd0fb9d0SQuentin Monnet 233bd0fb9d0SQuentin Monnet Found 0 elements 234bd0fb9d0SQuentin Monnet 235bd0fb9d0SQuentin Monnet| 236bd0fb9d0SQuentin Monnet| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug** 237bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 238bd0fb9d0SQuentin Monnet 239bd0fb9d0SQuentin Monnet:: 240bd0fb9d0SQuentin Monnet 241bd0fb9d0SQuentin Monnet key: 00 00 00 00 value: 22 02 00 00 242bd0fb9d0SQuentin Monnet Found 1 element 243bd0fb9d0SQuentin Monnet 244ff69c21aSJakub KicinskiSEE ALSO 245ff69c21aSJakub Kicinski======== 246f98e46a2SQuentin Monnet **bpf**\ (2), 247f98e46a2SQuentin Monnet **bpf-helpers**\ (7), 248f98e46a2SQuentin Monnet **bpftool**\ (8), 249f98e46a2SQuentin Monnet **bpftool-prog**\ (8), 250f98e46a2SQuentin Monnet **bpftool-cgroup**\ (8), 251f98e46a2SQuentin Monnet **bpftool-net**\ (8), 252f98e46a2SQuentin Monnet **bpftool-perf**\ (8) 253