Sockmap socket interface configuration (proto)

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:

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

Sockmap socket interface configuration overview.

extensions.network.socket_interface.sockmap.v3.Sockmap

[extensions.network.socket_interface.sockmap.v3.Sockmap proto]

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.

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

(string) 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.

cgroup_path

(string) 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.

sockhash_max_entries

(UInt32Value) Maximum number of entries in the sockhash map. Each accelerated socket consumes one entry. If not specified, defaults to 65536.

register_user_space_sockets

(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.

accelerated_ports

(repeated 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.