whiterose

linux unikernel
Log | Files | Refs | README | LICENSE | git clone https://git.ne02ptzero.me/git/whiterose

bpftool-map.rst (8879B)


      1 ================
      2 bpftool-map
      3 ================
      4 -------------------------------------------------------------------------------
      5 tool for inspection and simple manipulation of eBPF maps
      6 -------------------------------------------------------------------------------
      7 
      8 :Manual section: 8
      9 
     10 SYNOPSIS
     11 ========
     12 
     13 	**bpftool** [*OPTIONS*] **map** *COMMAND*
     14 
     15 	*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
     16 
     17 	*COMMANDS* :=
     18 	{ **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext**
     19 	| **delete** | **pin** | **help** }
     20 
     21 MAP COMMANDS
     22 =============
     23 
     24 |	**bpftool** **map { show | list }**   [*MAP*]
     25 |	**bpftool** **map create**     *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \
     26 |		**entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*]
     27 |	**bpftool** **map dump**       *MAP*
     28 |	**bpftool** **map update**     *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*]
     29 |	**bpftool** **map lookup**     *MAP* [**key** *DATA*]
     30 |	**bpftool** **map getnext**    *MAP* [**key** *DATA*]
     31 |	**bpftool** **map delete**     *MAP*  **key** *DATA*
     32 |	**bpftool** **map pin**        *MAP*  *FILE*
     33 |	**bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
     34 |	**bpftool** **map peek**       *MAP*
     35 |	**bpftool** **map push**       *MAP* **value** *VALUE*
     36 |	**bpftool** **map pop**        *MAP*
     37 |	**bpftool** **map enqueue**    *MAP* **value** *VALUE*
     38 |	**bpftool** **map dequeue**    *MAP*
     39 |	**bpftool** **map help**
     40 |
     41 |	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
     42 |	*DATA* := { [**hex**] *BYTES* }
     43 |	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
     44 |	*VALUE* := { *DATA* | *MAP* | *PROG* }
     45 |	*UPDATE_FLAGS* := { **any** | **exist** | **noexist** }
     46 |	*TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash**
     47 |		| **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash**
     48 |		| **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps**
     49 |		| **devmap** | **sockmap** | **cpumap** | **xskmap** | **sockhash**
     50 |		| **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage**
     51 |		| **queue** | **stack** }
     52 
     53 DESCRIPTION
     54 ===========
     55 	**bpftool map { show | list }**   [*MAP*]
     56 		  Show information about loaded maps.  If *MAP* is specified
     57 		  show information only about given map, otherwise list all
     58 		  maps currently loaded on the system.
     59 
     60 		  Output will start with map ID followed by map type and
     61 		  zero or more named attributes (depending on kernel version).
     62 
     63 	**bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE*  **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*]
     64 		  Create a new map with given parameters and pin it to *bpffs*
     65 		  as *FILE*.
     66 
     67 	**bpftool map dump**    *MAP*
     68 		  Dump all entries in a given *MAP*.
     69 
     70 	**bpftool map update**  *MAP* [**key** *DATA*] [**value** *VALUE*] [*UPDATE_FLAGS*]
     71 		  Update map entry for a given *KEY*.
     72 
     73 		  *UPDATE_FLAGS* can be one of: **any** update existing entry
     74 		  or add if doesn't exit; **exist** update only if entry already
     75 		  exists; **noexist** update only if entry doesn't exist.
     76 
     77 		  If the **hex** keyword is provided in front of the bytes
     78 		  sequence, the bytes are parsed as hexadeximal values, even if
     79 		  no "0x" prefix is added. If the keyword is not provided, then
     80 		  the bytes are parsed as decimal values, unless a "0x" prefix
     81 		  (for hexadecimal) or a "0" prefix (for octal) is provided.
     82 
     83 	**bpftool map lookup**  *MAP* [**key** *DATA*]
     84 		  Lookup **key** in the map.
     85 
     86 	**bpftool map getnext** *MAP* [**key** *DATA*]
     87 		  Get next key.  If *key* is not specified, get first key.
     88 
     89 	**bpftool map delete**  *MAP*  **key** *DATA*
     90 		  Remove entry from the map.
     91 
     92 	**bpftool map pin**     *MAP*  *FILE*
     93 		  Pin map *MAP* as *FILE*.
     94 
     95 		  Note: *FILE* must be located in *bpffs* mount. It must not
     96 		  contain a dot character ('.'), which is reserved for future
     97 		  extensions of *bpffs*.
     98 
     99 	**bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
    100 		  Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map.
    101 
    102 		  Install perf rings into a perf event array map and dump
    103 		  output of any bpf_perf_event_output() call in the kernel.
    104 		  By default read the number of CPUs on the system and
    105 		  install perf ring for each CPU in the corresponding index
    106 		  in the array.
    107 
    108 		  If **cpu** and **index** are specified, install perf ring
    109 		  for given **cpu** at **index** in the array (single ring).
    110 
    111 		  Note that installing a perf ring into an array will silently
    112 		  replace any existing ring.  Any other application will stop
    113 		  receiving events if it installed its rings earlier.
    114 
    115 	**bpftool map peek**  *MAP*
    116 		  Peek next **value** in the queue or stack.
    117 
    118 	**bpftool map push**  *MAP* **value** *VALUE*
    119 		  Push **value** onto the stack.
    120 
    121 	**bpftool map pop**  *MAP*
    122 		  Pop and print **value** from the stack.
    123 
    124 	**bpftool map enqueue**  *MAP* **value** *VALUE*
    125 		  Enqueue **value** into the queue.
    126 
    127 	**bpftool map dequeue**  *MAP*
    128 		  Dequeue and print **value** from the queue.
    129 
    130 	**bpftool map help**
    131 		  Print short help message.
    132 
    133 OPTIONS
    134 =======
    135 	-h, --help
    136 		  Print short generic help message (similar to **bpftool help**).
    137 
    138 	-v, --version
    139 		  Print version number (similar to **bpftool version**).
    140 
    141 	-j, --json
    142 		  Generate JSON output. For commands that cannot produce JSON, this
    143 		  option has no effect.
    144 
    145 	-p, --pretty
    146 		  Generate human-readable JSON output. Implies **-j**.
    147 
    148 	-f, --bpffs
    149 		  Show file names of pinned maps.
    150 
    151 	-n, --nomount
    152 		  Do not automatically attempt to mount any virtual file system
    153 		  (such as tracefs or BPF virtual file system) when necessary.
    154 
    155 EXAMPLES
    156 ========
    157 **# bpftool map show**
    158 ::
    159 
    160   10: hash  name some_map  flags 0x0
    161 	key 4B  value 8B  max_entries 2048  memlock 167936B
    162 
    163 The following three commands are equivalent:
    164 
    165 |
    166 | **# bpftool map update id 10 key hex   20   c4   b7   00 value hex   0f   ff   ff   ab   01   02   03   4c**
    167 | **# bpftool map update id 10 key     0x20 0xc4 0xb7 0x00 value     0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c**
    168 | **# bpftool map update id 10 key       32  196  183    0 value       15  255  255  171    1    2    3   76**
    169 
    170 **# bpftool map lookup id 10 key 0 1 2 3**
    171 
    172 ::
    173 
    174   key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
    175 
    176 
    177 **# bpftool map dump id 10**
    178 ::
    179 
    180   key: 00 01 02 03  value: 00 01 02 03 04 05 06 07
    181   key: 0d 00 07 00  value: 02 00 00 00 01 02 03 04
    182   Found 2 elements
    183 
    184 **# bpftool map getnext id 10 key 0 1 2 3**
    185 ::
    186 
    187   key:
    188   00 01 02 03
    189   next key:
    190   0d 00 07 00
    191 
    192 |
    193 | **# mount -t bpf none /sys/fs/bpf/**
    194 | **# bpftool map pin id 10 /sys/fs/bpf/map**
    195 | **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00**
    196 
    197 Note that map update can also be used in order to change the program references
    198 hold by a program array map. This can be used, for example, to change the
    199 programs used for tail-call jumps at runtime, without having to reload the
    200 entry-point program. Below is an example for this use case: we load a program
    201 defining a prog array map, and with a main function that contains a tail call
    202 to other programs that can be used either to "process" packets or to "debug"
    203 processing. Note that the prog array map MUST be pinned into the BPF virtual
    204 file system for the map update to work successfully, as kernel flushes prog
    205 array maps when they have no more references from user space (and the update
    206 would be lost as soon as bpftool exits).
    207 
    208 |
    209 | **# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp**
    210 | **# bpftool prog --bpffs**
    211 
    212 ::
    213 
    214   545: xdp  name main_func  tag 674b4b5597193dc3  gpl
    215           loaded_at 2018-12-12T15:02:58+0000  uid 0
    216           xlated 240B  jited 257B  memlock 4096B  map_ids 294
    217           pinned /sys/fs/bpf/foo/xdp
    218   546: xdp  name bpf_func_process  tag e369a529024751fc  gpl
    219           loaded_at 2018-12-12T15:02:58+0000  uid 0
    220           xlated 200B  jited 164B  memlock 4096B
    221           pinned /sys/fs/bpf/foo/process
    222   547: xdp  name bpf_func_debug  tag 0b597868bc7f0976  gpl
    223           loaded_at 2018-12-12T15:02:58+0000  uid 0
    224           xlated 200B  jited 164B  memlock 4096B
    225           pinned /sys/fs/bpf/foo/debug
    226 
    227 **# bpftool map**
    228 
    229 ::
    230 
    231   294: prog_array  name jmp_table  flags 0x0
    232           key 4B  value 4B  max_entries 1  memlock 4096B
    233           owner_prog_type xdp  owner jited
    234 
    235 |
    236 | **# bpftool map pin id 294 /sys/fs/bpf/bar**
    237 | **# bpftool map dump pinned /sys/fs/bpf/bar**
    238 
    239 ::
    240 
    241   Found 0 elements
    242 
    243 |
    244 | **# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug**
    245 | **# bpftool map dump pinned /sys/fs/bpf/bar**
    246 
    247 ::
    248 
    249   key: 00 00 00 00  value: 22 02 00 00
    250   Found 1 element
    251 
    252 SEE ALSO
    253 ========
    254 	**bpf**\ (2),
    255 	**bpf-helpers**\ (7),
    256 	**bpftool**\ (8),
    257 	**bpftool-prog**\ (8),
    258 	**bpftool-cgroup**\ (8),
    259 	**bpftool-feature**\ (8),
    260 	**bpftool-net**\ (8),
    261 	**bpftool-perf**\ (8)