Listener filter for dynamic modules (proto)

This extension has the qualified name envoy.filters.listener.dynamic_modules

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is not hardened 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:

extensions.filters.listener.dynamic_modules.v3.DynamicModuleListenerFilter

[extensions.filters.listener.dynamic_modules.v3.DynamicModuleListenerFilter proto]

Configuration of the listener filter for dynamic modules. This filter allows loading shared object files that can be loaded via dlopen by the listener filter.

A module can be loaded by multiple listener filters, hence the program can be structured in a way that the module is loaded only once and shared across multiple filters providing multiple functionalities.

Unlike network filters which operate on established TCP connections, listener filters work with raw accepted sockets BEFORE a Connection object is created. The filter can:

  • Inspect initial bytes to detect protocols (TLS, HTTP, PostgreSQL, etc.).

  • Set socket properties (SNI, ALPN, transport protocol, fingerprints).

  • Modify connection addresses (original destination restoration).

  • Set dynamic metadata and filter state for downstream filters.

  • Rate limit incoming connections.

{
  "dynamic_module_config": {...},
  "filter_name": ...,
  "filter_config": {...}
}
dynamic_module_config

(extensions.dynamic_modules.v3.DynamicModuleConfig) Specifies the shared-object level configuration.

filter_name

(string) The name for this filter configuration. This can be used to distinguish between different filter implementations inside a dynamic module. For example, a module can have completely different filter implementations (TLS inspector, rate limiter, proxy protocol parser). When Envoy receives this configuration, it passes the filter_name to the dynamic module’s listener filter config init function together with the filter_config. That way a module can decide which in-module filter implementation to use based on the name at load time.

filter_config

(Any) The configuration for the filter chosen by filter_name. This is passed to the module’s listener filter initialization function. Together with the filter_name, the module can decide which in-module filter implementation to use and fine-tune the behavior of the filter.

For example, if a module has two filter implementations, one for TLS inspection and one for rate limiting, filter_name is used to choose either TLS or rate limiting. The filter_config can be used to configure the TLS inspection options or the rate limiting parameters.

google.protobuf.Struct is serialized as JSON before passing it to the module. google.protobuf.BytesValue and google.protobuf.StringValue are passed directly without the wrapper.

# Passing a string value
filter_config:
  "@type": "type.googleapis.com/google.protobuf.StringValue"
  value: hello

# Passing raw bytes
filter_config:
  "@type": "type.googleapis.com/google.protobuf.BytesValue"
  value: aGVsbG8=  # echo -n "hello" | base64