# listener

## Summary

Any number of `listener` objects are attached to each [proxy](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/proxy) in order to receive incoming traffic. Their main use is to specify the address, port, and protocol that will be used to receive incoming requests. A sidecar can have as many Listeners created as is needed, though at least one listener must exist or it will not be able to receive any traffic.

> **WARNING** At least one listener must be allocated for a proxy to receive traffic. Additionally, the `port` exposed by that `listener` must match the port advertised to the [service discovery](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/usage/discovery) mechanism in use.
>
> **NOTE** Listeners can also be configured directly in the `proxy` objects. When defined there, they cannot be shared among multiple proxies, but saves the user from creating additional config objects.

### Usage

A common usage pattern is for 2-3 listeners on each sidecar. One listener is setup to listen on all network interfaces (0.0.0.0) and will receive traffic from the rest of the mesh. This is the port that is advertised in service discovery. This listener would have configurations for AuthN and AuthZ, instrumentation, etc.

Another listener is configured for egress requests from the service. This is bound only to the loopback interface (127.0.0.1), and will thus only receive traffic from the local microservice. This listener would be setup with routes and filters to facilitate regular HTTP traffic out to the rest of the mesh.

A third lister (or more, as needed) would handle specific traffic and protocols to dependencies. The example below shows a listener setup to handle TCP traffic to MongoDB listening on the default MongoDB port.

![](https://3431003532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LsNFVozLgvw3NDMzxBg-1847203797%2Fuploads%2Fgit-blob-4165d3d0a963b3c59ac6a26d1a07a18077026eea%2Fmulti-listener.jpg?alt=media)

### Example Object

```javascript
{
    "zone_key": "default-zone",
    "listener_key": "catalog-listener",
    "domain_keys": ["catalog"],
    "name": "catalog",
    "ip": "0.0.0.0",
    "port": 9080,
    "protocol": "http_auto",
    "tracing_config": null,
    "use_remote_address": false,
    "access_loggers": null,
    "http2_protocol_options": {}
}
```

### Secret Configuration for SPIFFE/SPIRE

To configure the service to require SPIFFE/SPIRE on its ingress, you must set a `secret` on the listener. **NOTE** if you intend to use SPIFFE/SPIRE on a service ingress, **do not** set an `ssl_config` on the corresponding domain object. Any `ssl_config` set on the domain will override this secret set on the listener. An example secret object is as follows:

```javascript
"secret": {
    "secret_key": "secret-{{.service.serviceName}}-secret",
    "secret_name": "spiffe://{{ .Values.global.spire.trustDomain }}/{{.service.serviceName}}/mTLS",
    "secret_validation_name": "spiffe://{{ .Values.global.spire.trustDomain }}",
    "ecdh_curves": [
        "X25519:P-256:P-521:P-384"
    ]
}
```

This object will configure Envoy to use Secret Discovery Service to fetch SPIFFE certificates from the configured path specified as an environment variable `SPIRE_PATH` in `gm-proxy`. For information on how Envoy's SDS works, see the [docs](https://www.envoyproxy.io/docs/envoy/v1.15.0/configuration/security/secret). The `secret_key` specifies the name of the secret to fetch. `secret_name` should be the [SPIFFE Id](https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE-ID.md#2-spiffe-identity) of your certificate. `secret_validation_name` will set the validation context for the sds secret config.

### Envoy Reference

* [Envoy Listener Reference](https://www.envoyproxy.io/docs/envoy/v1.15.0/configuration/listeners/listeners)

### Fields

#### `listener_key`

A unique key to identify this listener configuration in the Fabric API. This key is used in [proxy](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/proxy) objects to attach physical listeners to Sidecars.

#### `zone_key`

The zone in which this object will live. It will only be able to be referenced by objects or sent to Sidecars that live in the same zone.

#### `name`

A unique name for this listener on the Sidecar. This does not need to be globally unique across the Fabric mesh, but needs to be unique for each Sidecar.

#### `active_network_filters`

Array of [network filters](https://github.com/greymatter-io/gm-gitbook-sync/tree/a36d354058c7abbfff58b20908ff27c2ed1c6077/reference/api/fabric-api/filters/network.md) that should be active on this listener's filter chain. This list acts as a simple mechanism for turning specific filters on/off without needing to completely remove their configuration from the [network\_filter](#networkfilters) section.

> NOTE: The order of filters in this array dictates the evaluation order of the filters in the chain.

#### `network_filters`

Array of filter configurations to be used when a filter is [enabled](#activenetworkfilters).

#### `active_http_filters`

Array of [http filters](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/filters/http) that should be active on this listener's filter chain. This list acts as a simple mechanism for turning specific filters on/off without needing to completely remove their configuration from the [http\_filter](#httpfilters) section.

> NOTE: The order of filters in this array dictates the evaluation order of the filters in the chain.

#### `http_filters`

Array of filter configurations to be used when a filter is [enabled](#activehttpfilters).

#### `use_remote_address`

Boolean value which should only be set for front-facing edge nodes in order to allow for x-forwarding through a proxy. This field is false by default, allowing the connection manager to operate in a transparent mode which does not modify the XFF list.

#### `ip`

Network interface this listener will bind to. For example, `"0.0.0.0"` to listen for requests from anywhere on the network, or `"127.0.0.1:` to listen only for local requests.

#### `port`

Integer port this listener will bind to. Must be available on the host or the listener provisioning will fail.

#### `protocol`

> DEPRECATION: This field has been deprecated and will be removed in the next major version release.

This field has no effect.

#### `domain_keys`

Array of [domain keys](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/domain#domainkey) that will be linked to this listener.

#### `tracing_config`

[Configuration](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener/tracing_config) to set up distributed tracing on this listener.

#### `secret`

[Configuration](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener/secret) to set up SSL certificates through Envoy's [Secret discovery service](https://www.envoyproxy.io/docs/envoy/v1.15.0/configuration/security/secret).

#### `checksum`

An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.

#### `access_loggers`

Configuration object for configuring the Listener's HTTP Connection Manager [access loggers](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/accesslog/v3/accesslog.proto#envoy-v3-api-msg-config-accesslog-v3-accesslog) and the envoy.router [upstream loggers](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/accesslog/v3/accesslog.proto#envoy-v3-api-msg-config-accesslog-v3-accesslog).

By default, one HTTP gRPC access logger (connected to the xds\_cluster) and one File Logger (logging to `/dev/stdout`) is configured in the HTTP Connection Manager. Configuring a gRPC logger overwrites the default gRPC logger, but not the default File Logger (and vice-versa). The envoy.router contains only one HTTP gRPC logger (also connected to the xds\_cluster), and the same overwriting rules apply.

**Configuration object**

```javascript
"access_loggers": {
    "http_connection_loggers": {
        "disabled": false,
        "file_loggers": [
            {
                "path": "",
                "format": "",
                "json_format": {},
                "typed_json_format": {}
            }
        ],
        "http_grpc_access_loggers": [
            {
                "common_config": {
                    "log_name": "",
                    "grpc_service": {
                        "cluster_name": ""
                    }
                }
            }
        ]
    },
    "http_upstream_loggers": {
        "disabled": false,
        "file_loggers": [
            {
                "path": "",
                "format": "",
                "json_format": {},
                "typed_json_format": {}
            }
        ],
        "http_grpc_access_loggers": [
            {
                "common_config": {
                    "log_name": "",
                    "grpc_service": {
                        "cluster_name": ""
                    }
                }
            }
        ]
    }
}
```

`http_connection_loggers` add loggers to the HTTP Connection Manager, and `http_upstream_loggers` add loggers to the `envoy.router`. The logger configurations mirror the [Envoy Access Logger docs](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/accesslog/v3/accesslog.proto#envoy-v3-api-msg-config-accesslog-v3-accesslog).

Setting `disabled` removes all access loggers.

#### `http2_protocol_options`

Options for configuring HTTP/2. Setting this field on the listener indicates that the listener will only accept HTTP/2 connections.