1 .. SPDX-License-Identifier: GPL-2.0-only
2 .. Copyright Red Hat
3
4 ==============================================
5 BPF_MAP_TYPE_SOCKMAP and BPF_MAP_TYPE_SOCKHASH
6 ==============================================
7
8 .. note::
9 - ``BPF_MAP_TYPE_SOCKMAP`` was introduced i
10 - ``BPF_MAP_TYPE_SOCKHASH`` was introduced
11
12 ``BPF_MAP_TYPE_SOCKMAP`` and ``BPF_MAP_TYPE_SO
13 redirect skbs between sockets or to apply poli
14 the result of a BPF (verdict) program with the
15 ``bpf_sk_redirect_map()``, ``bpf_sk_redirect_h
16 ``bpf_msg_redirect_map()`` and ``bpf_msg_redir
17
18 ``BPF_MAP_TYPE_SOCKMAP`` is backed by an array
19 index to look up a reference to a ``struct soc
20 descriptors. Similarly, ``BPF_MAP_TYPE_SOCKHAS
21 holds references to sockets via their socket d
22
23 .. note::
24 The value type is either __u32 or __u64; t
25 returning socket cookies to userspace. Ret
26 the map holds to user-space is neither saf
27
28 These maps may have BPF programs attached to t
29 and a verdict program. The parser program dete
30 parsed and therefore how much data needs to be
31 verdict program is essentially the redirect pr
32 of ``__SK_DROP``, ``__SK_PASS``, or ``__SK_RED
33
34 When a socket is inserted into one of these ma
35 replaced and a ``struct sk_psock`` is attached
36 ``sk_psock`` inherits the programs that are at
37
38 A sock object may be in multiple maps, but can
39 parse or verdict program. If adding a sock obj
40 in having multiple parser programs the update
41
42 The supported programs to attach to these maps
43
44 .. code-block:: c
45
46 struct sk_psock_progs {
47 struct bpf_prog *msg_parser;
48 struct bpf_prog *stream_parser
49 struct bpf_prog *stream_verdic
50 struct bpf_prog *skb_verdict;
51 };
52
53 .. note::
54 Users are not allowed to attach ``stream_v
55 programs to the same map.
56
57 The attach types for the map programs are:
58
59 - ``msg_parser`` program - ``BPF_SK_MSG_VERDIC
60 - ``stream_parser`` program - ``BPF_SK_SKB_STR
61 - ``stream_verdict`` program - ``BPF_SK_SKB_ST
62 - ``skb_verdict`` program - ``BPF_SK_SKB_VERDI
63
64 There are additional helpers available to use
65 programs: ``bpf_msg_apply_bytes()`` and ``bpf_
66 ``bpf_msg_apply_bytes()`` BPF programs can tel
67 bytes the given verdict should apply to. The h
68 handles a different case where a BPF program c
69 until it receives more bytes AND the program d
70 until it is known to be good.
71
72 Finally, the helpers ``bpf_msg_pull_data()`` a
73 available to ``BPF_PROG_TYPE_SK_MSG`` BPF prog
74 start and end pointers to given values or to a
75 sk_msg_buff *msg``.
76
77 All these helpers will be described in more de
78
79 Usage
80 =====
81 Kernel BPF
82 ----------
83 bpf_msg_redirect_map()
84 ^^^^^^^^^^^^^^^^^^^^^^
85 .. code-block:: c
86
87 long bpf_msg_redirect_map(struct sk_ms
88
89 This helper is used in programs implementing p
90 the message ``msg`` is allowed to pass (i.e.,
91 returns ``SK_PASS``), redirect it to the socke
92 ``BPF_MAP_TYPE_SOCKMAP``) at index ``key``. Bo
93 can be used for redirection. The ``BPF_F_INGRE
94 to select the ingress path otherwise the egres
95 only flag supported for now.
96
97 Returns ``SK_PASS`` on success, or ``SK_DROP``
98
99 bpf_sk_redirect_map()
100 ^^^^^^^^^^^^^^^^^^^^^
101 .. code-block:: c
102
103 long bpf_sk_redirect_map(struct sk_buff *s
104
105 Redirect the packet to the socket referenced b
106 ``BPF_MAP_TYPE_SOCKMAP``) at index ``key``. Bo
107 can be used for redirection. The ``BPF_F_INGRE
108 to select the ingress path otherwise the egres
109 only flag supported for now.
110
111 Returns ``SK_PASS`` on success, or ``SK_DROP``
112
113 bpf_map_lookup_elem()
114 ^^^^^^^^^^^^^^^^^^^^^
115 .. code-block:: c
116
117 void *bpf_map_lookup_elem(struct bpf_map *
118
119 socket entries of type ``struct sock *`` can b
120 ``bpf_map_lookup_elem()`` helper.
121
122 bpf_sock_map_update()
123 ^^^^^^^^^^^^^^^^^^^^^
124 .. code-block:: c
125
126 long bpf_sock_map_update(struct bpf_sock_o
127
128 Add an entry to, or update a ``map`` referenci
129 as a new value for the entry associated to ``k
130 be one of the following:
131
132 - ``BPF_ANY``: Create a new element or update
133 - ``BPF_NOEXIST``: Create a new element only i
134 - ``BPF_EXIST``: Update an existing element.
135
136 If the ``map`` has BPF programs (parser and ve
137 by the socket being added. If the socket is al
138 this results in an error.
139
140 Returns 0 on success, or a negative error in c
141
142 bpf_sock_hash_update()
143 ^^^^^^^^^^^^^^^^^^^^^^
144 .. code-block:: c
145
146 long bpf_sock_hash_update(struct bpf_sock_
147
148 Add an entry to, or update a sockhash ``map``
149 is used as a new value for the entry associate
150
151 The ``flags`` argument can be one of the follo
152
153 - ``BPF_ANY``: Create a new element or update
154 - ``BPF_NOEXIST``: Create a new element only i
155 - ``BPF_EXIST``: Update an existing element.
156
157 If the ``map`` has BPF programs (parser and ve
158 by the socket being added. If the socket is al
159 this results in an error.
160
161 Returns 0 on success, or a negative error in c
162
163 bpf_msg_redirect_hash()
164 ^^^^^^^^^^^^^^^^^^^^^^^
165 .. code-block:: c
166
167 long bpf_msg_redirect_hash(struct sk_msg_b
168
169 This helper is used in programs implementing p
170 the message ``msg`` is allowed to pass (i.e.,
171 ``SK_PASS``), redirect it to the socket refere
172 ``BPF_MAP_TYPE_SOCKHASH``) using hash ``key``.
173 interfaces can be used for redirection. The ``
174 ``flags`` is used to select the ingress path o
175 selected. This is the only flag supported for
176
177 Returns ``SK_PASS`` on success, or ``SK_DROP``
178
179 bpf_sk_redirect_hash()
180 ^^^^^^^^^^^^^^^^^^^^^^
181 .. code-block:: c
182
183 long bpf_sk_redirect_hash(struct sk_buff *
184
185 This helper is used in programs implementing p
186 If the sk_buff ``skb`` is allowed to pass (i.e
187 returns ``SK_PASS``), redirect it to the socke
188 ``BPF_MAP_TYPE_SOCKHASH``) using hash ``key``.
189 interfaces can be used for redirection. The ``
190 ``flags`` is used to select the ingress path o
191 selected. This is the only flag supported for
192
193 Returns ``SK_PASS`` on success, or ``SK_DROP``
194
195 bpf_msg_apply_bytes()
196 ^^^^^^^^^^^^^^^^^^^^^^
197 .. code-block:: c
198
199 long bpf_msg_apply_bytes(struct sk_msg_buf
200
201 For socket policies, apply the verdict of the
202 of ``bytes``) of message ``msg``. For example,
203 following cases:
204
205 - A single ``sendmsg()`` or ``sendfile()`` sys
206 logical messages that the BPF program is sup
207 should apply a verdict.
208 - A BPF program only cares to read the first `
209 message has a large payload, then setting up
210 repeatedly for all bytes, even though the ve
211 create unnecessary overhead.
212
213 Returns 0
214
215 bpf_msg_cork_bytes()
216 ^^^^^^^^^^^^^^^^^^^^^^
217 .. code-block:: c
218
219 long bpf_msg_cork_bytes(struct sk_msg_buff
220
221 For socket policies, prevent the execution of
222 message ``msg`` until the number of ``bytes``
223
224 This can be used when one needs a specific num
225 be assigned, even if the data spans multiple `
226 calls.
227
228 Returns 0
229
230 bpf_msg_pull_data()
231 ^^^^^^^^^^^^^^^^^^^^^^
232 .. code-block:: c
233
234 long bpf_msg_pull_data(struct sk_msg_buff
235
236 For socket policies, pull in non-linear data f
237 pointers ``msg->data`` and ``msg->data_end`` t
238 offsets into ``msg``, respectively.
239
240 If a program of type ``BPF_PROG_TYPE_SK_MSG``
241 parse data that the (``data``, ``data_end``) p
242 For ``sendmsg()`` hooks this is likely the fir
243 calls relying on MSG_SPLICE_PAGES (e.g., ``sen
244 range (**0**, **0**) because the data is share
245 the objective is to avoid allowing user space
246 BPF verdict is being decided. This helper can
247 set the start and end pointers to given values
248 necessary (i.e., if data was not linear and if
249 point to the same chunk).
250
251 A call to this helper is susceptible to change
252 Therefore, at load time, all checks on pointer
253 are invalidated and must be performed again, i
254 combination with direct packet access.
255
256 All values for ``flags`` are reserved for futu
257 zero.
258
259 Returns 0 on success, or a negative error in c
260
261 bpf_map_lookup_elem()
262 ^^^^^^^^^^^^^^^^^^^^^
263
264 .. code-block:: c
265
266 void *bpf_map_lookup_elem(struct bpf_m
267
268 Look up a socket entry in the sockmap or sockh
269
270 Returns the socket entry associated to ``key``
271
272 bpf_map_update_elem()
273 ^^^^^^^^^^^^^^^^^^^^^
274 .. code-block:: c
275
276 long bpf_map_update_elem(struct bpf_ma
277
278 Add or update a socket entry in a sockmap or s
279
280 The flags argument can be one of the following
281
282 - BPF_ANY: Create a new element or update an e
283 - BPF_NOEXIST: Create a new element only if it
284 - BPF_EXIST: Update an existing element.
285
286 Returns 0 on success, or a negative error in c
287
288 bpf_map_delete_elem()
289 ^^^^^^^^^^^^^^^^^^^^^^
290 .. code-block:: c
291
292 long bpf_map_delete_elem(struct bpf_map *m
293
294 Delete a socket entry from a sockmap or a sock
295
296 Returns 0 on success, or a negative error in c
297
298 User space
299 ----------
300 bpf_map_update_elem()
301 ^^^^^^^^^^^^^^^^^^^^^
302 .. code-block:: c
303
304 int bpf_map_update_elem(int fd, const
305
306 Sockmap entries can be added or updated using
307 function. The ``key`` parameter is the index v
308 ``value`` parameter is the FD value of that so
309
310 Under the hood, the sockmap update function us
311 retrieve the associated socket and its attache
312
313 The flags argument can be one of the following
314
315 - BPF_ANY: Create a new element or update an e
316 - BPF_NOEXIST: Create a new element only if it
317 - BPF_EXIST: Update an existing element.
318
319 bpf_map_lookup_elem()
320 ^^^^^^^^^^^^^^^^^^^^^
321 .. code-block:: c
322
323 int bpf_map_lookup_elem(int fd, const void
324
325 Sockmap entries can be retrieved using the ``b
326
327 .. note::
328 The entry returned is a socket cookie
329
330 bpf_map_delete_elem()
331 ^^^^^^^^^^^^^^^^^^^^^
332 .. code-block:: c
333
334 int bpf_map_delete_elem(int fd, const void
335
336 Sockmap entries can be deleted using the ``bpf
337 function.
338
339 Returns 0 on success, or negative error in cas
340
341 Examples
342 ========
343
344 Kernel BPF
345 ----------
346 Several examples of the use of sockmap APIs ca
347
348 - `tools/testing/selftests/bpf/progs/test_sock
349 - `tools/testing/selftests/bpf/progs/sockmap_p
350 - `tools/testing/selftests/bpf/progs/sockmap_v
351 - `tools/testing/selftests/bpf/progs/test_sock
352 - `tools/testing/selftests/bpf/progs/test_sock
353
354 The following code snippet shows how to declar
355
356 .. code-block:: c
357
358 struct {
359 __uint(type, BPF_MAP_TYPE_SOCK
360 __uint(max_entries, 1);
361 __type(key, __u32);
362 __type(value, __u64);
363 } sock_map_rx SEC(".maps");
364
365 The following code snippet shows a sample pars
366
367 .. code-block:: c
368
369 SEC("sk_skb/stream_parser")
370 int bpf_prog_parser(struct __sk_buff *
371 {
372 return skb->len;
373 }
374
375 The following code snippet shows a simple verd
376 sockmap to redirect traffic to another socket
377
378 .. code-block:: c
379
380 SEC("sk_skb/stream_verdict")
381 int bpf_prog_verdict(struct __sk_buff
382 {
383 __u32 lport = skb->local_port;
384 __u32 idx = 0;
385
386 if (lport == 10000)
387 return bpf_sk_redirect
388
389 return SK_PASS;
390 }
391
392 The following code snippet shows how to declar
393
394 .. code-block:: c
395
396 struct socket_key {
397 __u32 src_ip;
398 __u32 dst_ip;
399 __u32 src_port;
400 __u32 dst_port;
401 };
402
403 struct {
404 __uint(type, BPF_MAP_TYPE_SOCK
405 __uint(max_entries, 1);
406 __type(key, struct socket_key)
407 __type(value, __u64);
408 } sock_hash_rx SEC(".maps");
409
410 The following code snippet shows a simple verd
411 sockhash to redirect traffic to another socket
412 skb parameters.
413
414 .. code-block:: c
415
416 static inline
417 void extract_socket_key(struct __sk_bu
418 {
419 key->src_ip = skb->remote_ip4;
420 key->dst_ip = skb->local_ip4;
421 key->src_port = skb->remote_po
422 key->dst_port = (bpf_htonl(skb
423 }
424
425 SEC("sk_skb/stream_verdict")
426 int bpf_prog_verdict(struct __sk_buff
427 {
428 struct socket_key key;
429
430 extract_socket_key(skb, &key);
431
432 return bpf_sk_redirect_hash(sk
433 }
434
435 User space
436 ----------
437 Several examples of the use of sockmap APIs ca
438
439 - `tools/testing/selftests/bpf/prog_tests/sock
440 - `tools/testing/selftests/bpf/test_sockmap.c`
441 - `tools/testing/selftests/bpf/test_maps.c`_
442
443 The following code sample shows how to create
444 verdict program, as well as add a socket entry
445
446 .. code-block:: c
447
448 int create_sample_sockmap(int sock, in
449 {
450 int index = 0;
451 int map, err;
452
453 map = bpf_map_create(BPF_MAP_T
454 if (map < 0) {
455 fprintf(stderr, "Faile
456 return -1;
457 }
458
459 err = bpf_prog_attach(parse_pr
460 if (err){
461 fprintf(stderr, "Faile
462 goto out;
463 }
464
465 err = bpf_prog_attach(verdict_
466 if (err){
467 fprintf(stderr, "Faile
468 goto out;
469 }
470
471 err = bpf_map_update_elem(map,
472 if (err) {
473 fprintf(stderr, "Faile
474 goto out;
475 }
476
477 out:
478 close(map);
479 return err;
480 }
481
482 References
483 ===========
484
485 - https://github.com/jrfastab/linux-kernel-xdp
486 - https://lwn.net/Articles/731133/
487 - http://vger.kernel.org/lpc_net2018_talks/ktl
488 - https://lwn.net/Articles/748628/
489 - https://lore.kernel.org/bpf/20200218171023.8
490
491 .. _`tools/testing/selftests/bpf/progs/test_so
492 .. _`tools/testing/selftests/bpf/progs/sockmap
493 .. _`tools/testing/selftests/bpf/progs/sockmap
494 .. _`tools/testing/selftests/bpf/prog_tests/so
495 .. _`tools/testing/selftests/bpf/test_sockmap.
496 .. _`tools/testing/selftests/bpf/test_maps.c`:
497 .. _`tools/testing/selftests/bpf/progs/test_so
498 .. _`tools/testing/selftests/bpf/progs/test_so
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.