---
title: "Listeners"
url: "/reference/resources/listeners/"
kind: "reference"
summary: "Field reference for listeners, filter chains, filter chain matching and the downstream TLS context."
---

> Arion site index: [/llms.txt](/llms.txt)

# Listeners

Field reference for listeners, filter chains, filter chain matching and the downstream TLS context.

Listeners are declared under `envoy_bootstrap.static_resources.listeners` (or delivered over xDS) using standard Envoy field names; any field not listed here makes Arion refuse the configuration (see [supported configuration](@/reference/envoy-compatibility/supported-configuration.md)).

## listener

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string | yes | — | Unique listener name. |
| `address` | object | yes* | — | `socket_address` with an IP literal `address` and a `port_value`. Hostnames, named ports and pipe addresses are rejected. |
| `internal_listener` | object | yes* | — | Marks the listener as internal (`internal_listener: {}`); it has no `address` and is reached through cluster endpoints with an `envoy_internal_address`. |
| `filter_chains` | list | yes | — | At least one [filter chain](#filter-chain). Every `filter_chain_match` in the list must be unique. |
| `listener_filters` | list | no | `[]` | [Listener filters](#listener-filters) that run before a filter chain is chosen. |
| `socket_options` | list | no | — | At most one entry, and only `SO_BINDTODEVICE` (`level: 1`, `name: 25`, `buf_value` set to the interface name). |
| `tcp_backlog_size` | uint32 | no | `128` | Length of the kernel accept queue for the listening socket. |
| `access_log` | list | no | `[]` | Connection-level access logs (file, stdout or stderr sinks). See [access log operators](@/reference/observability/access-log-operators.md). |

\* exactly one of `address` or `internal_listener`.

```yaml,arion=fragment
static_resources:
  listeners:
    - name: listener_http
      address:
        socket_address: { address: 0.0.0.0, port_value: 8080 }
      tcp_backlog_size: 1024
      filter_chains:
        - name: default
          filters:
            - name: http_gateway
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                # see the HTTP connection manager reference
```

## filter_chain

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string | yes | — | Filter chain name. |
| `filter_chain_match` | object | no | match all | [Match criteria](#filter-chain-match) that select this chain for a connection. |
| `filters` | list | yes | — | [Network filters](#network-filters). The last entry must be an HTTP connection manager or a TCP proxy. |
| `transport_socket` | object | no | plaintext | A `DownstreamTlsContext` to terminate [TLS](#tls-downstreamtlscontext), or a `RawBuffer` for explicit plaintext. |

## filter_chain_match

All configured criteria must match; when several chains match, the most specific value wins (for example exact SNI beats `*.example.com`, which beats a chain with no `server_names`).

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `destination_port` | uint16 | no | any | Destination port of the connection. |
| `prefix_ranges` | list | no | any | Destination CIDR ranges, each `{address_prefix, prefix_len}`. |
| `server_names` | list | no | any | TLS SNI names. Exact (`api.example.com`) or subdomain wildcard (`*.example.com`). A bare `*` and internal wildcards are rejected. Requires the TLS inspector listener filter. |
| `source_prefix_ranges` | list | no | any | Source CIDR ranges. |
| `source_ports` | list | no | any | Source ports. |

```yaml,arion=fragment
filter_chains:
  - name: api_chain
    filter_chain_match:
      server_names: [api.example.com]
      destination_port: 8443
    filters:
      # network filters, ending in an HTTP connection manager or TCP proxy
```

## Network filters

`filters` entries are `{name, typed_config}` pairs. Accepted `@type` values:

| `@type` (under `type.googleapis.com/`) | Position | Description |
|---|---|---|
| `envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager` | terminal | [HTTP connection manager](@/reference/filters/network/http-connection-manager.md); exactly one terminal filter per chain. |
| `envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy` | terminal | [TCP proxy](@/reference/filters/network/tcp-proxy.md); alternative terminal filter. |
| `envoy.extensions.filters.network.rbac.v3.RBAC` | before terminal | [Network RBAC](@/reference/filters/network/rbac.md); may appear more than once. |
| `envoy.extensions.filters.network.ratelimit.v3.RateLimit` | before terminal | [Global rate limit](@/reference/filters/network/rate-limit.md); at most once. Without a TLS inspector its `domain` is required. |
| `envoy.extensions.filters.network.connection_limit.v3.ConnectionLimit` | before terminal | [Connection limit](@/reference/filters/network/connection-limit.md); at most once. |

## Listener filters

`listener_filters` entries are `{name, typed_config}` pairs. Accepted `@type` values:

| `@type` (under `type.googleapis.com/`) | Description |
|---|---|
| `envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector` | Reads the TLS ClientHello so `server_names` matching works. `enable_ja3_fingerprinting` is accepted only as `false`. See [TLS inspector](@/reference/filters/listener/tls-inspector.md). |
| `envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol` | Parses PROXY protocol v1/v2 headers. See [proxy protocol](@/reference/filters/listener/proxy-protocol.md). |
| `envoy.extensions.filters.listener.local_ratelimit.v3.LocalRateLimit` | Token-bucket limit on accepted connections. See [local rate limit](@/reference/filters/listener/local-rate-limit.md). |

```yaml,arion=fragment
listener_filters:
  - name: tls_inspector
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector
      enable_ja3_fingerprinting: false
```

## TLS (DownstreamTlsContext)

Set as the filter chain `transport_socket` with `@type: type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext`.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `common_tls_context` | object | yes | — | Certificates, TLS parameters and peer validation (below). |
| `require_client_certificate` | bool | no | `false` | Require and verify a client certificate (mTLS). Needs a `validation_context`. |

### common_tls_context

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `tls_certificates` | list | one of | — | Inline server certificates, each `{certificate_chain, private_key}` [data sources](@/reference/resources/secrets.md#data-sources). |
| `tls_certificate_sds_secret_configs` | list | one of | — | Named references (`- name: <secret>`) to [secrets](@/reference/resources/secrets.md). Only the `name` field is accepted. |
| `tls_params` | object | no | see below | Protocol version bounds. |
| `validation_context` | object | no | no client auth | Inline `{trusted_ca, trust_chain_verification}` for verifying client certificates. |
| `validation_context_sds_secret_config` | object | no | — | Named reference (`name: <secret>`) to a validation-context secret. |

`tls_certificates` and `tls_certificate_sds_secret_configs` are mutually exclusive. Not supported (the config is refused): `alpn_protocols`, `cipher_suites`, `ecdh_curves`, `signature_algorithms`, `require_sni`, `combined_validation_context`, session ticket keys and stateful session resumption.

### tls_params

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `tls_minimum_protocol_version` | enum | no | `TLSv1_2` | `TLSv1_2` or `TLSv1_3`. TLS 1.0 and 1.1 are rejected; `TLS_AUTO` means 1.2. |
| `tls_maximum_protocol_version` | enum | no | auto | `TLSv1_2` or `TLSv1_3`; must not be lower than the minimum. |

```yaml,arion=fragment
transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    common_tls_context:
      tls_params:
        tls_minimum_protocol_version: TLSv1_2
      tls_certificate_sds_secret_configs:
        - name: example_com_cert
```