prog_sk_lookup.rst 3.8 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798
  1. .. SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
  2. =====================
  3. BPF sk_lookup program
  4. =====================
  5. BPF sk_lookup program type (``BPF_PROG_TYPE_SK_LOOKUP``) introduces programmability
  6. into the socket lookup performed by the transport layer when a packet is to be
  7. delivered locally.
  8. When invoked BPF sk_lookup program can select a socket that will receive the
  9. incoming packet by calling the ``bpf_sk_assign()`` BPF helper function.
  10. Hooks for a common attach point (``BPF_SK_LOOKUP``) exist for both TCP and UDP.
  11. Motivation
  12. ==========
  13. BPF sk_lookup program type was introduced to address setup scenarios where
  14. binding sockets to an address with ``bind()`` socket call is impractical, such
  15. as:
  16. 1. receiving connections on a range of IP addresses, e.g. 192.0.2.0/24, when
  17. binding to a wildcard address ``INADRR_ANY`` is not possible due to a port
  18. conflict,
  19. 2. receiving connections on all or a wide range of ports, i.e. an L7 proxy use
  20. case.
  21. Such setups would require creating and ``bind()``'ing one socket to each of the
  22. IP address/port in the range, leading to resource consumption and potential
  23. latency spikes during socket lookup.
  24. Attachment
  25. ==========
  26. BPF sk_lookup program can be attached to a network namespace with
  27. ``bpf(BPF_LINK_CREATE, ...)`` syscall using the ``BPF_SK_LOOKUP`` attach type and a
  28. netns FD as attachment ``target_fd``.
  29. Multiple programs can be attached to one network namespace. Programs will be
  30. invoked in the same order as they were attached.
  31. Hooks
  32. =====
  33. The attached BPF sk_lookup programs run whenever the transport layer needs to
  34. find a listening (TCP) or an unconnected (UDP) socket for an incoming packet.
  35. Incoming traffic to established (TCP) and connected (UDP) sockets is delivered
  36. as usual without triggering the BPF sk_lookup hook.
  37. The attached BPF programs must return with either ``SK_PASS`` or ``SK_DROP``
  38. verdict code. As for other BPF program types that are network filters,
  39. ``SK_PASS`` signifies that the socket lookup should continue on to regular
  40. hashtable-based lookup, while ``SK_DROP`` causes the transport layer to drop the
  41. packet.
  42. A BPF sk_lookup program can also select a socket to receive the packet by
  43. calling ``bpf_sk_assign()`` BPF helper. Typically, the program looks up a socket
  44. in a map holding sockets, such as ``SOCKMAP`` or ``SOCKHASH``, and passes a
  45. ``struct bpf_sock *`` to ``bpf_sk_assign()`` helper to record the
  46. selection. Selecting a socket only takes effect if the program has terminated
  47. with ``SK_PASS`` code.
  48. When multiple programs are attached, the end result is determined from return
  49. codes of all the programs according to the following rules:
  50. 1. If any program returned ``SK_PASS`` and selected a valid socket, the socket
  51. is used as the result of the socket lookup.
  52. 2. If more than one program returned ``SK_PASS`` and selected a socket, the last
  53. selection takes effect.
  54. 3. If any program returned ``SK_DROP``, and no program returned ``SK_PASS`` and
  55. selected a socket, socket lookup fails.
  56. 4. If all programs returned ``SK_PASS`` and none of them selected a socket,
  57. socket lookup continues on.
  58. API
  59. ===
  60. In its context, an instance of ``struct bpf_sk_lookup``, BPF sk_lookup program
  61. receives information about the packet that triggered the socket lookup. Namely:
  62. * IP version (``AF_INET`` or ``AF_INET6``),
  63. * L4 protocol identifier (``IPPROTO_TCP`` or ``IPPROTO_UDP``),
  64. * source and destination IP address,
  65. * source and destination L4 port,
  66. * the socket that has been selected with ``bpf_sk_assign()``.
  67. Refer to ``struct bpf_sk_lookup`` declaration in ``linux/bpf.h`` user API
  68. header, and `bpf-helpers(7)
  69. <https://man7.org/linux/man-pages/man7/bpf-helpers.7.html>`_ man-page section
  70. for ``bpf_sk_assign()`` for details.
  71. Example
  72. =======
  73. See ``tools/testing/selftests/bpf/prog_tests/sk_lookup.c`` for the reference
  74. implementation.