Protocol options

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/core/protocol.proto

config.core.v3.QuicProtocolOptions

[config.core.v3.QuicProtocolOptions proto]

QUIC protocol options which apply to both downstream and upstream connections.

  1. {
  2.   "max_concurrent_streams": "{...}",
  3.   "initial_stream_window_size": "{...}",
  4.   "initial_connection_window_size": "{...}"
  5. }

max_concurrent_streams

(UInt32Value) Maximum number of streams that the client can negotiate per connection. 100 if not specified.

initial_stream_window_size

(UInt32Value) Initial stream-level flow-control receive window size. Valid values range from 1 to 16777216 (2^24, maximum supported by QUICHE) and defaults to 65536 (2^16).

NOTE: 16384 (2^14) is the minimum window size supported in Google QUIC. If configured smaller than it, we will use 16384 instead. QUICHE IETF Quic implementation supports 1 bytes window. We only support increasing the default window size now, so it’s also the minimum.

This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the QUIC stream send and receive buffers. Once the buffer reaches this pointer, watermark callbacks will fire to stop the flow of data to the stream buffers.

initial_connection_window_size

(UInt32Value) Similar to initial_stream_window_size, but for connection-level flow-control. Valid values rage from 1 to 25165824 (24MB, maximum supported by QUICHE) and defaults to 65536 (2^16). window. Currently, this has the same minimum/default as initial_stream_window_size.

NOTE: 16384 (2^14) is the minimum window size supported in Google QUIC. We only support increasing the default window size now, so it’s also the minimum.

config.core.v3.UpstreamHttpProtocolOptions

[config.core.v3.UpstreamHttpProtocolOptions proto]

  1. {
  2.   "auto_sni": "...",
  3.   "auto_san_validation": "...",
  4.   "override_auto_sni_header": "..."
  5. }

auto_sni

(bool) Set transport socket SNI for new upstream connections based on the downstream HTTP host/authority header or any other arbitrary header when override_auto_sni_header is set, as seen by the router filter.

auto_san_validation

(bool) Automatic validate upstream presented certificate for new upstream connections based on the downstream HTTP host/authority header or any other arbitrary header when override_auto_sni_header is set, as seen by the router filter. This field is intended to be set with auto_sni field.

override_auto_sni_header

(string) An optional alternative to the host/authority header to be used for setting the SNI value. It should be a valid downstream HTTP header, as seen by the router filter. If unset, host/authority header will be used for populating the SNI. If the specified header is not found or the value is empty, host/authority header will be used instead. This field is intended to be set with auto_sni and/or auto_san_validation fields. If none of these fields are set then setting this would be a no-op.

config.core.v3.AlternateProtocolsCacheOptions

[config.core.v3.AlternateProtocolsCacheOptions proto]

Configures the alternate protocols cache which tracks alternate protocols that can be used to make an HTTP connection to an origin server. See https://tools.ietf.org/html/rfc7838 for HTTP Alternative Services and https://datatracker.ietf.org/doc/html/draft-ietf-dnsop-svcb-https-04 for the “HTTPS” DNS resource record.

  1. {
  2.   "name": "...",
  3.   "max_entries": "{...}",
  4.   "key_value_store_config": "{...}"
  5. }

name

(string, REQUIRED) The name of the cache. Multiple named caches allow independent alternate protocols cache configurations to operate within a single Envoy process using different configurations. All alternate protocols cache options with the same name must be equal in all fields when referenced from different configuration components. Configuration will fail to load if this is not the case.

max_entries

(UInt32Value) The maximum number of entries that the cache will hold. If not specified defaults to 1024.

key_value_store_config

(config.core.v3.TypedExtensionConfig) Allows configuring a persistent key value store to flush alternate protocols entries to disk. This function is currently only supported if concurrency is 1

config.core.v3.HttpProtocolOptions

[config.core.v3.HttpProtocolOptions proto]

  1. {
  2.   "idle_timeout": "{...}",
  3.   "max_connection_duration": "{...}",
  4.   "max_headers_count": "{...}",
  5.   "max_stream_duration": "{...}",
  6.   "headers_with_underscores_action": "...",
  7.   "max_requests_per_connection": "{...}"
  8. }

idle_timeout

(Duration) The idle timeout for connections. The idle timeout is defined as the period in which there are no active requests. When the idle timeout is reached the connection will be closed. If the connection is an HTTP/2 downstream connection a drain sequence will occur prior to closing the connection, see drain_timeout. Note that request based timeouts mean that HTTP/2 PINGs will not keep the connection alive. If not specified, this defaults to 1 hour. To disable idle timeouts explicitly set this to 0.

Warning

Disabling this timeout has a highly likelihood of yielding connection leaks due to lost TCP FIN packets, etc.

If the overload action “envoy.overload_actions.reduce_timeouts” is configured, this timeout is scaled for downstream connections according to the value for HTTP_DOWNSTREAM_CONNECTION_IDLE.

max_connection_duration

(Duration) The maximum duration of a connection. The duration is defined as a period since a connection was established. If not set, there is no max duration. When max_connection_duration is reached and if there are no active streams, the connection will be closed. If there are any active streams, the drain sequence will kick-in, and the connection will be force-closed after the drain period. See drain_timeout. Note: This feature is not yet implemented for the upstream connections.

max_headers_count

(UInt32Value) The maximum number of headers. If unconfigured, the default maximum number of request headers allowed is 100. Requests that exceed this limit will receive a 431 response for HTTP/1.x and cause a stream reset for HTTP/2.

max_stream_duration

(Duration) Total duration to keep alive an HTTP request/response stream. If the time limit is reached the stream will be reset independent of any other timeouts. If not specified, this value is not set.

headers_with_underscores_action

(config.core.v3.HttpProtocolOptions.HeadersWithUnderscoresAction) Action to take when a client request with a header name containing underscore characters is received. If this setting is not specified, the value defaults to ALLOW. Note: upstream responses are not affected by this setting.

max_requests_per_connection

(UInt32Value) Optional maximum requests for both upstream and downstream connections. If not specified, there is no limit. Setting this parameter to 1 will effectively disable keep alive. For HTTP/2 and HTTP/3, due to concurrent stream processing, the limit is approximate.

Enum config.core.v3.HttpProtocolOptions.HeadersWithUnderscoresAction

[config.core.v3.HttpProtocolOptions.HeadersWithUnderscoresAction proto]

Action to take when Envoy receives client request with header names containing underscore characters. Underscore character is allowed in header names by the RFC-7230 and this behavior is implemented as a security measure due to systems that treat ‘_’ and ‘-‘ as interchangeable. Envoy by default allows client request headers with underscore characters.

ALLOW

(DEFAULT) ⁣Allow headers with underscores. This is the default behavior.

REJECT_REQUEST

⁣Reject client request. HTTP/1 requests are rejected with the 400 status. HTTP/2 requests end with the stream reset. The “httpN.requests_rejected_with_underscores_in_headers” counter is incremented for each rejected request.

DROP_HEADER

⁣Drop the header with name containing underscores. The header is dropped before the filter chain is invoked and as such filters will not see dropped headers. The “httpN.dropped_headers_with_underscores” is incremented for each dropped header.

config.core.v3.Http1ProtocolOptions

[config.core.v3.Http1ProtocolOptions proto]

  1. {
  2.   "allow_absolute_url": "{...}",
  3.   "accept_http_10": "...",
  4.   "default_host_for_http_10": "...",
  5.   "header_key_format": "{...}",
  6.   "enable_trailers": "...",
  7.   "allow_chunked_length": "...",
  8.   "override_stream_error_on_invalid_http_message": "{...}"
  9. }

allow_absolute_url

(BoolValue) Handle HTTP requests with absolute URLs in the requests. These requests are generally sent by clients to forward/explicit proxies. This allows clients to configure envoy as their HTTP proxy. In Unix, for example, this is typically done by setting the http_proxy environment variable.

accept_http_10

(bool) Handle incoming HTTP/1.0 and HTTP 0.9 requests. This is off by default, and not fully standards compliant. There is support for pre-HTTP/1.1 style connect logic, dechunking, and handling lack of client host iff default_host_for_http_10 is configured.

default_host_for_http_10

(string) A default host for HTTP/1.0 requests. This is highly suggested if accept_http_10 is true as Envoy does not otherwise support HTTP/1.0 without a Host header. This is a no-op if accept_http_10 is not true.

header_key_format

(config.core.v3.Http1ProtocolOptions.HeaderKeyFormat) Describes how the keys for response headers should be formatted. By default, all header keys are lower cased.

enable_trailers

(bool) Enables trailers for HTTP/1. By default the HTTP/1 codec drops proxied trailers.

Attention

Note that this only happens when Envoy is chunk encoding which occurs when: - The request is HTTP/1.1. - Is neither a HEAD only request nor a HTTP Upgrade. - Not a response to a HEAD request. - The content length header is not present.

allow_chunked_length

(bool) Allows Envoy to process requests/responses with both Content-Length and Transfer-Encoding headers set. By default such messages are rejected, but if option is enabled - Envoy will remove Content-Length header and process message. See RFC7230, sec. 3.3.3 <https://tools.ietf.org/html/rfc7230#section-3.3.3&gt; for details.

Attention

Enabling this option might lead to request smuggling vulnerability, especially if traffic is proxied via multiple layers of proxies.

override_stream_error_on_invalid_http_message

(BoolValue) Allows invalid HTTP messaging. When this option is false, then Envoy will terminate HTTP/1.1 connections upon receiving an invalid HTTP message. However, when this option is true, then Envoy will leave the HTTP/1.1 connection open where possible. If set, this overrides any HCM stream_error_on_invalid_http_messaging.

config.core.v3.Http1ProtocolOptions.HeaderKeyFormat

[config.core.v3.Http1ProtocolOptions.HeaderKeyFormat proto]

  1. {
  2.   "proper_case_words": "{...}",
  3.   "stateful_formatter": "{...}"
  4. }

proper_case_words

(config.core.v3.Http1ProtocolOptions.HeaderKeyFormat.ProperCaseWords) Formats the header by proper casing words: the first character and any character following a special character will be capitalized if it’s an alpha character. For example, “content-type” becomes “Content-Type”, and “foo$b#$are” becomes “Foo$B#$Are”. Note that while this results in most headers following conventional casing, certain headers are not covered. For example, the “TE” header will be formatted as “Te”.

Precisely one of proper_case_words, stateful_formatter must be set.

stateful_formatter

(config.core.v3.TypedExtensionConfig) Configuration for stateful formatter extensions that allow using received headers to affect the output of encoding headers. E.g., preserving case during proxying.

Tip

This extension category has the following known extensions:

Precisely one of proper_case_words, stateful_formatter must be set.

config.core.v3.Http1ProtocolOptions.HeaderKeyFormat.ProperCaseWords

[config.core.v3.Http1ProtocolOptions.HeaderKeyFormat.ProperCaseWords proto]

config.core.v3.KeepaliveSettings

[config.core.v3.KeepaliveSettings proto]

  1. {
  2.   "interval": "{...}",
  3.   "timeout": "{...}",
  4.   "interval_jitter": "{...}",
  5.   "connection_idle_interval": "{...}"
  6. }

interval

(Duration) Send HTTP/2 PING frames at this period, in order to test that the connection is still alive. If this is zero, interval PINGs will not be sent.

timeout

(Duration, REQUIRED) How long to wait for a response to a keepalive PING. If a response is not received within this time period, the connection will be aborted.

interval_jitter

(type.v3.Percent) A random jitter amount as a percentage of interval that will be added to each interval. A value of zero means there will be no jitter. The default value is 15%.

connection_idle_interval

(Duration) If the connection has been idle for this duration, send a HTTP/2 ping ahead of new stream creation, to quickly detect dead connections. If this is zero, this type of PING will not be sent. If an interval ping is outstanding, a second ping will not be sent as the interval ping will determine if the connection is dead.

config.core.v3.Http2ProtocolOptions

[config.core.v3.Http2ProtocolOptions proto]

  1. {
  2.   "hpack_table_size": "{...}",
  3.   "max_concurrent_streams": "{...}",
  4.   "initial_stream_window_size": "{...}",
  5.   "initial_connection_window_size": "{...}",
  6.   "allow_connect": "...",
  7.   "max_outbound_frames": "{...}",
  8.   "max_outbound_control_frames": "{...}",
  9.   "max_consecutive_inbound_frames_with_empty_payload": "{...}",
  10.   "max_inbound_priority_frames_per_stream": "{...}",
  11.   "max_inbound_window_update_frames_per_data_frame_sent": "{...}",
  12.   "stream_error_on_invalid_http_messaging": "...",
  13.   "override_stream_error_on_invalid_http_message": "{...}",
  14.   "connection_keepalive": "{...}"
  15. }

hpack_table_size

(UInt32Value) Maximum table size (in octets) that the encoder is permitted to use for the dynamic HPACK table. Valid values range from 0 to 4294967295 (2^32 - 1) and defaults to 4096. 0 effectively disables header compression.

max_concurrent_streams

(UInt32Value) Maximum concurrent streams allowed for peer on one HTTP/2 connection. Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 2147483647.

For upstream connections, this also limits how many streams Envoy will initiate concurrently on a single connection. If the limit is reached, Envoy may queue requests or establish additional connections (as allowed per circuit breaker limits).

This acts as an upper bound: Envoy will lower the max concurrent streams allowed on a given connection based on upstream settings. Config dumps will reflect the configured upper bound, not the per-connection negotiated limits.

initial_stream_window_size

(UInt32Value) Initial stream-level flow-control window size. Valid values range from 65535 (2^16 - 1, HTTP/2 default) to 2147483647 (2^31 - 1, HTTP/2 maximum) and defaults to 268435456 (256 * 1024 * 1024).

NOTE: 65535 is the initial window size from HTTP/2 spec. We only support increasing the default window size now, so it’s also the minimum.

This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to stop the flow of data to the codec buffers.

initial_connection_window_size

(UInt32Value) Similar to initial_stream_window_size, but for connection-level flow-control window. Currently, this has the same minimum/maximum/default as initial_stream_window_size.

allow_connect

(bool) Allows proxying Websocket and other upgrades over H2 connect.

max_outbound_frames

(UInt32Value) Limit the number of pending outbound downstream frames of all types (frames that are waiting to be written into the socket). Exceeding this limit triggers flood mitigation and connection is terminated. The http2.outbound_flood stat tracks the number of terminated connections due to flood mitigation. The default limit is 10000. NOTE: flood and abuse mitigation for upstream connections is presently enabled by the envoy.reloadable_features.upstream_http2_flood_checks flag.

max_outbound_control_frames

(UInt32Value) Limit the number of pending outbound downstream frames of types PING, SETTINGS and RST_STREAM, preventing high memory utilization when receiving continuous stream of these frames. Exceeding this limit triggers flood mitigation and connection is terminated. The http2.outbound_control_flood stat tracks the number of terminated connections due to flood mitigation. The default limit is 1000. NOTE: flood and abuse mitigation for upstream connections is presently enabled by the envoy.reloadable_features.upstream_http2_flood_checks flag.

max_consecutive_inbound_frames_with_empty_payload

(UInt32Value) Limit the number of consecutive inbound frames of types HEADERS, CONTINUATION and DATA with an empty payload and no end stream flag. Those frames have no legitimate use and are abusive, but might be a result of a broken HTTP/2 implementation. The http2.inbound_empty_frames_flood` stat tracks the number of connections terminated due to flood mitigation. Setting this to 0 will terminate connection upon receiving first frame with an empty payload and no end stream flag. The default limit is 1. NOTE: flood and abuse mitigation for upstream connections is presently enabled by the envoy.reloadable_features.upstream_http2_flood_checks flag.

max_inbound_priority_frames_per_stream

(UInt32Value) Limit the number of inbound PRIORITY frames allowed per each opened stream. If the number of PRIORITY frames received over the lifetime of connection exceeds the value calculated using this formula:

  1. max_inbound_priority_frames_per_stream * (1 + opened_streams)

the connection is terminated. For downstream connections the opened_streams is incremented when Envoy receives complete response headers from the upstream server. For upstream connection the opened_streams is incremented when Envoy send the HEADERS frame for a new stream. The http2.inbound_priority_frames_flood stat tracks the number of connections terminated due to flood mitigation. The default limit is 100. NOTE: flood and abuse mitigation for upstream connections is presently enabled by the envoy.reloadable_features.upstream_http2_flood_checks flag.

max_inbound_window_update_frames_per_data_frame_sent

(UInt32Value) Limit the number of inbound WINDOW_UPDATE frames allowed per DATA frame sent. If the number of WINDOW_UPDATE frames received over the lifetime of connection exceeds the value calculated using this formula:

  1. 5 + 2 * (opened_streams +
  2.          max_inbound_window_update_frames_per_data_frame_sent * outbound_data_frames)

the connection is terminated. For downstream connections the opened_streams is incremented when Envoy receives complete response headers from the upstream server. For upstream connections the opened_streams is incremented when Envoy sends the HEADERS frame for a new stream. The http2.inbound_priority_frames_flood stat tracks the number of connections terminated due to flood mitigation. The default max_inbound_window_update_frames_per_data_frame_sent value is 10. Setting this to 1 should be enough to support HTTP/2 implementations with basic flow control, but more complex implementations that try to estimate available bandwidth require at least 2. NOTE: flood and abuse mitigation for upstream connections is presently enabled by the envoy.reloadable_features.upstream_http2_flood_checks flag.

stream_error_on_invalid_http_messaging

(bool) Allows invalid HTTP messaging and headers. When this option is disabled (default), then the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However, when this option is enabled, only the offending stream is terminated.

This is overridden by HCM stream_error_on_invalid_http_messaging iff present.

This is deprecated in favor of override_stream_error_on_invalid_http_message

See RFC7540, sec. 8.1 for details.

override_stream_error_on_invalid_http_message

(BoolValue) Allows invalid HTTP messaging and headers. When this option is disabled (default), then the whole HTTP/2 connection is terminated upon receiving invalid HEADERS frame. However, when this option is enabled, only the offending stream is terminated.

This overrides any HCM stream_error_on_invalid_http_messaging

See RFC7540, sec. 8.1 for details.

connection_keepalive

(config.core.v3.KeepaliveSettings) Send HTTP/2 PING frames to verify that the connection is still healthy. If the remote peer does not respond within the configured timeout, the connection will be aborted.

config.core.v3.Http2ProtocolOptions.SettingsParameter

[config.core.v3.Http2ProtocolOptions.SettingsParameter proto]

Defines a parameter to be sent in the SETTINGS frame. See RFC7540, sec. 6.5.1 for details.

  1. {
  2.   "identifier": "{...}",
  3.   "value": "{...}"
  4. }

identifier

(UInt32Value, REQUIRED) The 16 bit parameter identifier.

value

(UInt32Value, REQUIRED) The 32 bit parameter value.

config.core.v3.Http3ProtocolOptions

[config.core.v3.Http3ProtocolOptions proto]

A message which allows using HTTP/3.

  1. {
  2.   "quic_protocol_options": "{...}",
  3.   "override_stream_error_on_invalid_http_message": "{...}",
  4.   "allow_extended_connect": "..."
  5. }

quic_protocol_options

(config.core.v3.QuicProtocolOptions)

override_stream_error_on_invalid_http_message

(BoolValue) Allows invalid HTTP messaging and headers. When this option is disabled (default), then the whole HTTP/3 connection is terminated upon receiving invalid HEADERS frame. However, when this option is enabled, only the offending stream is terminated.

If set, this overrides any HCM stream_error_on_invalid_http_messaging.

allow_extended_connect

(bool) Allows proxying Websocket and other upgrades over HTTP/3 CONNECT using the header mechanisms from the HTTP/2 extended connect RFC and settings proposed for HTTP/3 Note that HTTP/3 CONNECT is not yet an RFC.

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

config.core.v3.SchemeHeaderTransformation

[config.core.v3.SchemeHeaderTransformation proto]

A message to control transformations to the :scheme header

  1. {
  2.   "scheme_to_overwrite": "..."
  3. }

scheme_to_overwrite

(string) Overwrite any Scheme header with the contents of this string.