.. _envoy_v3_api_file_envoy/extensions/network/socket_interface/sockmap/v3/sockmap.proto:

Sockmap socket interface configuration (proto)
==============================================

.. _extension_envoy.extensions.network.socket_interface.sockmap:

This extension has the qualified name ``envoy.extensions.network.socket_interface.sockmap``


.. note::
  This extension is work-in-progress. Functionality is incomplete and it is not intended for production use.

  This extension has an unknown security posture and should only be
  used in deployments where both the downstream and upstream are
  trusted.

.. tip::
  This extension extends and can be used with the following extension category:


  - :ref:`envoy.bootstrap <extension_category_envoy.bootstrap>`



  This extension must be configured with one of the following type URLs:



  - :ref:`type.googleapis.com/envoy.extensions.network.socket_interface.sockmap.v3.Sockmap <envoy_v3_api_msg_extensions.network.socket_interface.sockmap.v3.Sockmap>`



Sockmap socket interface :ref:`configuration overview <config_sock_interface_sockmap>`.




.. _envoy_v3_api_msg_extensions.network.socket_interface.sockmap.v3.Sockmap:

extensions.network.socket_interface.sockmap.v3.Sockmap
------------------------------------------------------


:repo:`[extensions.network.socket_interface.sockmap.v3.Sockmap proto] <api/envoy/extensions/network/socket_interface/sockmap/v3/sockmap.proto#L31>`

Configuration for the ``sockmap`` socket interface. It accelerates same-host TCP hops by
loading eBPF ``sock_ops`` and ``sk_msg`` programs that redirect payloads between local sockets
through a ``BPF_MAP_TYPE_SOCKHASH``, bypassing the kernel TCP/IP stack. Connections whose peer
is not on the same host are not present in the map and transparently fall back to TCP/IP.

This interface requires a Linux kernel 4.18 or later and the capabilities to load and attach the
eBPF network programs (``CAP_SYS_ADMIN``, or ``CAP_BPF`` and ``CAP_NET_ADMIN`` on newer kernels).
When the programs cannot be loaded or attached, the interface logs the failure and every socket
falls back to the standard datapath, so traffic is never interrupted.



.. code-block:: json
  :force:

  {
    "bpf_program_path": ...,
    "cgroup_path": ...,
    "sockhash_max_entries": {...},
    "register_user_space_sockets": {...},
    "accelerated_ports": []
  }

.. _envoy_v3_api_field_extensions.network.socket_interface.sockmap.v3.Sockmap.bpf_program_path:


bpf_program_path
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Filesystem path to the compiled eBPF object that holds the ``sock_ops`` and ``sk_msg``
  programs and the ``sockhash`` map. Envoy does not ship this object. Build it from the
  extension's ``sockmap_kern.c`` source, or supply a custom build that exports the
  ``envoy_sockops`` and ``envoy_sk_msg`` programs and the ``envoy_sockhash`` map with a matching
  key layout. If not specified, acceleration is disabled and all sockets use the standard
  datapath.


.. _envoy_v3_api_field_extensions.network.socket_interface.sockmap.v3.Sockmap.cgroup_path:


cgroup_path
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Path to the cgroup v2 directory the ``sock_ops`` program is attached to. While attached, every
  socket that reaches the established state inside this cgroup is added to the ``sockhash``,
  which accelerates application-to-proxy hops. If not specified, the ``sock_ops`` program
  is not attached and only sockets accepted or connected by Envoy are registered, which still
  accelerates proxy-to-proxy hops on the same host.


.. _envoy_v3_api_field_extensions.network.socket_interface.sockmap.v3.Sockmap.sockhash_max_entries:


sockhash_max_entries
  (`UInt32Value <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#uint32value>`_) Maximum number of entries in the ``sockhash`` map. Each accelerated socket consumes one entry.
  If not specified, defaults to ``65536``.


.. _envoy_v3_api_field_extensions.network.socket_interface.sockmap.v3.Sockmap.register_user_space_sockets:


register_user_space_sockets
  (`BoolValue <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#boolvalue>`_) Whether sockets accepted or connected by Envoy are registered into the ``sockhash`` from user
  space. This is independent of ``cgroup_path`` and lets proxy-to-proxy hops be accelerated
  without attaching the ``sock_ops`` program. If not specified, defaults to ``true``.


.. _envoy_v3_api_field_extensions.network.socket_interface.sockmap.v3.Sockmap.accelerated_ports:


accelerated_ports
  (**repeated** :ref:`type.v3.Int64Range <envoy_v3_api_msg_type.v3.Int64Range>`) Proxy listener port ranges that scope which connections the ``sock_ops`` program adds to the
  ``sockhash``. Each range is half-open ``[start, end)`` with ``1 <= start < end <= 65536``, so a
  single port ``P`` is ``{ start: P, end: P + 1 }``. When set, only a connection whose local or
  peer port falls in one of these ranges is registered, so other same-host connections in the
  cgroup stay on the standard datapath. This applies only when ``cgroup_path`` is set. If empty,
  every such connection is registered. At most ``128`` ranges are allowed.