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*] 29c642ea26SJakub Kicinski| **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*] 3447ff7ac6SQuentin Monnet| **bpftool** **map help** 35ff69c21aSJakub Kicinski| 3647ff7ac6SQuentin Monnet| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 37c642ea26SJakub Kicinski| *DATA* := { [**hex**] *BYTES* } 382148481dSQuentin Monnet| *PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* } 39c642ea26SJakub Kicinski| *VALUE* := { *DATA* | *MAP* | *PROG* } 4047ff7ac6SQuentin Monnet| *UPDATE_FLAGS* := { **any** | **exist** | **noexist** } 410b592b5aSJakub Kicinski| *TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash** 420b592b5aSJakub Kicinski| | **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash** 430b592b5aSJakub Kicinski| | **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps** 440b592b5aSJakub Kicinski| | **devmap** | **sockmap** | **cpumap** | **xskmap** | **sockhash** 45197c2dacSDavid Calavera| | **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage** 46197c2dacSDavid Calavera| | **queue** | **stack** } 47ff69c21aSJakub Kicinski 48ff69c21aSJakub KicinskiDESCRIPTION 49ff69c21aSJakub Kicinski=========== 506ebe6dbdSJakub Kicinski **bpftool map { show | list }** [*MAP*] 51ff69c21aSJakub Kicinski Show information about loaded maps. If *MAP* is specified 52ff69c21aSJakub Kicinski show information only about given map, otherwise list all 53ff69c21aSJakub Kicinski maps currently loaded on the system. 54ff69c21aSJakub Kicinski 55ff69c21aSJakub Kicinski Output will start with map ID followed by map type and 56ff69c21aSJakub Kicinski zero or more named attributes (depending on kernel version). 57ff69c21aSJakub Kicinski 580b592b5aSJakub Kicinski **bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*] 590b592b5aSJakub Kicinski Create a new map with given parameters and pin it to *bpffs* 600b592b5aSJakub Kicinski as *FILE*. 610b592b5aSJakub Kicinski 62ff69c21aSJakub Kicinski **bpftool map dump** *MAP* 63ff69c21aSJakub Kicinski Dump all entries in a given *MAP*. 64ff69c21aSJakub Kicinski 657d7209cbSStanislav Fomichev **bpftool map update** *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*] 66ff69c21aSJakub Kicinski Update map entry for a given *KEY*. 67ff69c21aSJakub Kicinski 68ff69c21aSJakub Kicinski *UPDATE_FLAGS* can be one of: **any** update existing entry 69ff69c21aSJakub Kicinski or add if doesn't exit; **exist** update only if entry already 70ff69c21aSJakub Kicinski exists; **noexist** update only if entry doesn't exist. 71ff69c21aSJakub Kicinski 720c90f224SQuentin Monnet If the **hex** keyword is provided in front of the bytes 730c90f224SQuentin Monnet sequence, the bytes are parsed as hexadeximal values, even if 740c90f224SQuentin Monnet no "0x" prefix is added. If the keyword is not provided, then 750c90f224SQuentin Monnet the bytes are parsed as decimal values, unless a "0x" prefix 760c90f224SQuentin Monnet (for hexadecimal) or a "0" prefix (for octal) is provided. 770c90f224SQuentin Monnet 78c642ea26SJakub Kicinski **bpftool map lookup** *MAP* **key** *DATA* 79ff69c21aSJakub Kicinski Lookup **key** in the map. 80ff69c21aSJakub Kicinski 81c642ea26SJakub Kicinski **bpftool map getnext** *MAP* [**key** *DATA*] 82ff69c21aSJakub Kicinski Get next key. If *key* is not specified, get first key. 83ff69c21aSJakub Kicinski 84c642ea26SJakub Kicinski **bpftool map delete** *MAP* **key** *DATA* 85ff69c21aSJakub Kicinski Remove entry from the map. 86ff69c21aSJakub Kicinski 87ff69c21aSJakub Kicinski **bpftool map pin** *MAP* *FILE* 88ff69c21aSJakub Kicinski Pin map *MAP* as *FILE*. 89ff69c21aSJakub Kicinski 90882731e0SQuentin Monnet Note: *FILE* must be located in *bpffs* mount. It must not 91882731e0SQuentin Monnet contain a dot character ('.'), which is reserved for future 92882731e0SQuentin Monnet extensions of *bpffs*. 93ff69c21aSJakub Kicinski 94f412eed9SJakub Kicinski **bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*] 95f412eed9SJakub Kicinski Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map. 96f412eed9SJakub Kicinski 97f412eed9SJakub Kicinski Install perf rings into a perf event array map and dump 98f412eed9SJakub Kicinski output of any bpf_perf_event_output() call in the kernel. 99f412eed9SJakub Kicinski By default read the number of CPUs on the system and 100f412eed9SJakub Kicinski install perf ring for each CPU in the corresponding index 101f412eed9SJakub Kicinski in the array. 102f412eed9SJakub Kicinski 103f412eed9SJakub Kicinski If **cpu** and **index** are specified, install perf ring 104f412eed9SJakub Kicinski for given **cpu** at **index** in the array (single ring). 105f412eed9SJakub Kicinski 106f412eed9SJakub Kicinski Note that installing a perf ring into an array will silently 107f412eed9SJakub Kicinski replace any existing ring. Any other application will stop 108f412eed9SJakub Kicinski receiving events if it installed its rings earlier. 109f412eed9SJakub Kicinski 110ff69c21aSJakub Kicinski **bpftool map help** 111ff69c21aSJakub Kicinski Print short help message. 112ff69c21aSJakub Kicinski 113a2bc2e5cSQuentin MonnetOPTIONS 114a2bc2e5cSQuentin Monnet======= 115a2bc2e5cSQuentin Monnet -h, --help 116a2bc2e5cSQuentin Monnet Print short generic help message (similar to **bpftool help**). 117a2bc2e5cSQuentin Monnet 118a2bc2e5cSQuentin Monnet -v, --version 119a2bc2e5cSQuentin Monnet Print version number (similar to **bpftool version**). 120a2bc2e5cSQuentin Monnet 1210641c3c8SQuentin Monnet -j, --json 1220641c3c8SQuentin Monnet Generate JSON output. For commands that cannot produce JSON, this 1230641c3c8SQuentin Monnet option has no effect. 1240641c3c8SQuentin Monnet 1250641c3c8SQuentin Monnet -p, --pretty 1260641c3c8SQuentin Monnet Generate human-readable JSON output. Implies **-j**. 1270641c3c8SQuentin Monnet 128c541b734SPrashant Bhole -f, --bpffs 129c541b734SPrashant Bhole Show file names of pinned maps. 130c541b734SPrashant Bhole 13133221307SQuentin Monnet -n, --nomount 13233221307SQuentin Monnet Do not automatically attempt to mount any virtual file system 13333221307SQuentin Monnet (such as tracefs or BPF virtual file system) when necessary. 13433221307SQuentin Monnet 135ff69c21aSJakub KicinskiEXAMPLES 136ff69c21aSJakub Kicinski======== 137ff69c21aSJakub Kicinski**# bpftool map show** 138ff69c21aSJakub Kicinski:: 139ff69c21aSJakub Kicinski 140ff69c21aSJakub Kicinski 10: hash name some_map flags 0x0 141ff69c21aSJakub Kicinski key 4B value 8B max_entries 2048 memlock 167936B 142ff69c21aSJakub Kicinski 1430c90f224SQuentin MonnetThe following three commands are equivalent: 1440c90f224SQuentin Monnet 1450c90f224SQuentin Monnet| 1460c90f224SQuentin Monnet| **# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c** 1470c90f224SQuentin Monnet| **# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c** 1480c90f224SQuentin Monnet| **# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76** 149ff69c21aSJakub Kicinski 150ff69c21aSJakub Kicinski**# bpftool map lookup id 10 key 0 1 2 3** 151ff69c21aSJakub Kicinski 152ff69c21aSJakub Kicinski:: 153ff69c21aSJakub Kicinski 154ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 155ff69c21aSJakub Kicinski 156ff69c21aSJakub Kicinski 157ff69c21aSJakub Kicinski**# bpftool map dump id 10** 158ff69c21aSJakub Kicinski:: 159ff69c21aSJakub Kicinski 160ff69c21aSJakub Kicinski key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 161ff69c21aSJakub Kicinski key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 162ff69c21aSJakub Kicinski Found 2 elements 163ff69c21aSJakub Kicinski 164ff69c21aSJakub Kicinski**# bpftool map getnext id 10 key 0 1 2 3** 165ff69c21aSJakub Kicinski:: 166ff69c21aSJakub Kicinski 167ff69c21aSJakub Kicinski key: 168ff69c21aSJakub Kicinski 00 01 02 03 169ff69c21aSJakub Kicinski next key: 170ff69c21aSJakub Kicinski 0d 00 07 00 171ff69c21aSJakub Kicinski 172ff69c21aSJakub Kicinski| 173ff69c21aSJakub Kicinski| **# mount -t bpf none /sys/fs/bpf/** 174ff69c21aSJakub Kicinski| **# bpftool map pin id 10 /sys/fs/bpf/map** 175ff69c21aSJakub Kicinski| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00** 176ff69c21aSJakub Kicinski 177bd0fb9d0SQuentin MonnetNote that map update can also be used in order to change the program references 178bd0fb9d0SQuentin Monnethold by a program array map. This can be used, for example, to change the 179bd0fb9d0SQuentin Monnetprograms used for tail-call jumps at runtime, without having to reload the 180bd0fb9d0SQuentin Monnetentry-point program. Below is an example for this use case: we load a program 181bd0fb9d0SQuentin Monnetdefining a prog array map, and with a main function that contains a tail call 182bd0fb9d0SQuentin Monnetto other programs that can be used either to "process" packets or to "debug" 183bd0fb9d0SQuentin Monnetprocessing. Note that the prog array map MUST be pinned into the BPF virtual 184bd0fb9d0SQuentin Monnetfile system for the map update to work successfully, as kernel flushes prog 185bd0fb9d0SQuentin Monnetarray maps when they have no more references from user space (and the update 186bd0fb9d0SQuentin Monnetwould be lost as soon as bpftool exits). 187bd0fb9d0SQuentin Monnet 188bd0fb9d0SQuentin Monnet| 189bd0fb9d0SQuentin Monnet| **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp** 190bd0fb9d0SQuentin Monnet| **# bpftool prog --bpffs** 191bd0fb9d0SQuentin Monnet 192bd0fb9d0SQuentin Monnet:: 193bd0fb9d0SQuentin Monnet 194bd0fb9d0SQuentin Monnet 545: xdp name main_func tag 674b4b5597193dc3 gpl 195bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 196bd0fb9d0SQuentin Monnet xlated 240B jited 257B memlock 4096B map_ids 294 197bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/xdp 198bd0fb9d0SQuentin Monnet 546: xdp name bpf_func_process tag e369a529024751fc gpl 199bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 200bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 201bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/process 202bd0fb9d0SQuentin Monnet 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl 203bd0fb9d0SQuentin Monnet loaded_at 2018-12-12T15:02:58+0000 uid 0 204bd0fb9d0SQuentin Monnet xlated 200B jited 164B memlock 4096B 205bd0fb9d0SQuentin Monnet pinned /sys/fs/bpf/foo/debug 206bd0fb9d0SQuentin Monnet 207bd0fb9d0SQuentin Monnet**# bpftool map** 208bd0fb9d0SQuentin Monnet 209bd0fb9d0SQuentin Monnet:: 210bd0fb9d0SQuentin Monnet 211bd0fb9d0SQuentin Monnet 294: prog_array name jmp_table flags 0x0 212bd0fb9d0SQuentin Monnet key 4B value 4B max_entries 1 memlock 4096B 213bd0fb9d0SQuentin Monnet owner_prog_type xdp owner jited 214bd0fb9d0SQuentin Monnet 215bd0fb9d0SQuentin Monnet| 216bd0fb9d0SQuentin Monnet| **# bpftool map pin id 294 /sys/fs/bpf/bar** 217bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 218bd0fb9d0SQuentin Monnet 219bd0fb9d0SQuentin Monnet:: 220bd0fb9d0SQuentin Monnet 221bd0fb9d0SQuentin Monnet Found 0 elements 222bd0fb9d0SQuentin Monnet 223bd0fb9d0SQuentin Monnet| 224bd0fb9d0SQuentin Monnet| **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug** 225bd0fb9d0SQuentin Monnet| **# bpftool map dump pinned /sys/fs/bpf/bar** 226bd0fb9d0SQuentin Monnet 227bd0fb9d0SQuentin Monnet:: 228bd0fb9d0SQuentin Monnet 229bd0fb9d0SQuentin Monnet key: 00 00 00 00 value: 22 02 00 00 230bd0fb9d0SQuentin Monnet Found 1 element 231bd0fb9d0SQuentin Monnet 232ff69c21aSJakub KicinskiSEE ALSO 233ff69c21aSJakub Kicinski======== 234f98e46a2SQuentin Monnet **bpf**\ (2), 235f98e46a2SQuentin Monnet **bpf-helpers**\ (7), 236f98e46a2SQuentin Monnet **bpftool**\ (8), 237f98e46a2SQuentin Monnet **bpftool-prog**\ (8), 238f98e46a2SQuentin Monnet **bpftool-cgroup**\ (8), 239f98e46a2SQuentin Monnet **bpftool-net**\ (8), 240f98e46a2SQuentin Monnet **bpftool-perf**\ (8) 241