# Protocols Grey Matter supports a variety of network protocols. This doc describes each type of connections we support and how to configure it. * [http](/grey-matter-documentation/usage/fabric/traffic_control/protocols.md#http) * [https](/grey-matter-documentation/usage/fabric/traffic_control/protocols.md#https) * [http2](/grey-matter-documentation/usage/fabric/traffic_control/protocols.md#http2) * [grpc](/grey-matter-documentation/usage/fabric/traffic_control/protocols.md#grpc) * [tcp](/grey-matter-documentation/usage/fabric/traffic_control/protocols.md#tcp) * [websockets](/grey-matter-documentation/usage/fabric/traffic_control/protocols.md#websockets) ## http Http is the default network protocol. To use http, set the `ssl_config` parameter in the `domain` and `cluster` to an empty bracket, or omit it entirely. Example `cluster`: ```javascript { "zone_key": "default-zone", "cluster_key": "exapmle-cluster", "name": "example", "instances": [] } ``` example `domain` ```javascript { "zone_key": "default-zone", "domain_key": "example-domain", "name": "*", "port": 8080 } ``` This will ensure the proxy both handles incoming connections and makes outgoing upstream connections as http. ## https Https is http encrypted with tls. We can enable https by configuring the `ssl_config` attribute in the `domain` and `cluster` objects. Here is an example of a cluster using `https`: ```javascript { "zone_key": "default-zone", "cluster_key": "exapmle-cluster", "name": "example", "instances": [], "ssl_config": { "protocols": [ "TLSv1.2" ], "require_client_certs": true, "trust_file": "/etc/proxy/tls/sidecar/ca.crt", "cert_key_pairs": [ { "certificate_path": "/etc/proxy/tls/sidecar/server.crt", "key_path": "/etc/proxy/tls/sidecar/server.key" } ] }, "require_tls": true, } ``` and a domain: ```javascript { "zone_key": "default-zone", "domain_key": "example-domain", "name": "*", "port": 8080, "ssl_config": { "protocols": [ "TLSv1.2" ], "require_client_certs": true, "trust_file": "/etc/proxy/tls/sidecar/ca.crt", "cert_key_pairs": [ { "certificate_path": "/etc/proxy/tls/sidecar/server.crt", "key_path": "/etc/proxy/tls/sidecar/server.key" } ] }, "force_https": true, } ``` Together, the configured proxy will only handle incoming and create outgoing https requests using [TLS version 1.2](https://tools.ietf.org/html/rfc5246) and which contain valid cert / key pairs. For more information on different types of https configurations, see [this doc](/grey-matter-documentation/usage/fabric/security/ssl.md) on configuring ssl throughout the mesh. At this writing, Grey Matter supports the following http encryption protocols: SSLv2, SSLv3, TLSv1.1, TLSv1.2. ## http2 http2 is similar to http, but with added performance and optimizations. For more information see [http2 specifications](https://http2.github.io/). Http2 is supported by Grey Matter automatically via envoy's [Protocol Selection](https://www.envoyproxy.io/docs/envoy/v1.12.2/api-v2/api/v2/cds.proto.html?highlight=upstreamtlscontext#enum-cluster-clusterprotocolselection) attribute. Each cluster is hard-coded to use the protocol of the downstream cluster. For example, to make a request to a sidecar in front of a http2 service the client should initiate an http2 request. For more detailed information see [this tutorial](https://github.com/DecipherNow/gm-gitbook-sync/tree/5b98b90f49d578028d2f0bedc5d18402e1eb055a/examples/http2/README.md) on making requests to tls and non-tls http2 clusters. ## grpc GRPC is an [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call) framework that uses [protocol buffers](https://github.com/protocolbuffers/protobuf) as an interface for bidirectional streaming. Currently, GRPC is not supported by Grey Matter. However, Grey Matter should *in theory* support the [envoy json -> grpc transcoder http filter](https://www.envoyproxy.io/docs/envoy/v1.12.0/configuration/http/http_filters/grpc_json_transcoder_filter.html). Using this filter, clients can make http JSON requests to a proxy instance, which is translated into gRPC compliant with the back end service's protobuf definitions. See this [WIP example](https://github.com/DecipherNow/gm-gitbook-sync/tree/5b98b90f49d578028d2f0bedc5d18402e1eb055a/examples/http_filters/grpc_json_transcoder/README.md) of this for more information. ## tcp Sidecars are able to field incoming and outgoing tcp connections using [envoy's tcp network filter](https://www.envoyproxy.io/docs/envoy/v1.12.0/configuration/listeners/network_filters/tcp_proxy_filter). To activate tcp, add `envoy.tcp_proxy` to the list of active network filters in the `listener` object. You must also specify the upstream cluster in the `network_filters.envoy_tcp_proxy` attribute. ```javascript { "zone_key": "default-zone", "listener_key": "example-listener", "name": "example-listener", "domain_keys": ["example-domain"], "ip": "0.0.0.0", "port": 8181, "protocol": "http_auto", "active_network_filters": ["envoy.tcp_proxy"], "network_filters": { "envoy_tcp_proxy": { "stat_prefix":"tcp_proxy", "cluster":"tcp_proxy" } } } ``` For more info see [this example on setting up a tcp listener](https://github.com/greymatter-io/gm-control-api/blob/release-1.2/docs/examples/network_filters/tcp_proxy/README.md). ## websockets Websockets open a two-way interactive stream between the client and server, whereas other protocols such as http are unidirectional. Websockets can be configured for a sidecar sitting in front of a compatible backend service by enabling [websocket and http upgrades](https://www.envoyproxy.io/docs/envoy/v1.12.0/intro/arch_overview/http/websocket.html). This is done in Grey Matter by setting the `"upgrade" : "websocket"` attribute in the `proxy` object of the sidecar. This can be done in the following ways: ## Environment Variable Simply set `UPGRADES=websocket` as an environment variable. The proxy will see this on startup and write the applicable envoy template. This is a string delimited list which can handle multiple upgrade types. Each upgrade corresponds to an envoy [upgrade config type](https://www.envoyproxy.io/docs/envoy/v1.12.0/api-v2/config/filter/network/http_connection_manager/v2/http_connection_manager.proto#envoy-api-msg-config-filter-network-http-connection-manager-v2-httpconnectionmanager-upgradeconfig). ## Dynamic Configuration in the Mesh Upgrades can also be configured dynamically with the Grey Matter cli. Each proxy object has an attribute `upgrades`, which corresponds to the `UPGRADES` environment variable. To enable websockets, set `upgrades` to `"websocket"`. A full example is below: ```javascript { "proxy_key": "gm-proxy-proxy", "zone_key": "default-zone", "name": "gm-proxy", "domain_keys": [ "domain" ], "listener_keys": [ "listener" ], "listeners": null, "upgrades": "websocket", "active_proxy_filters": null, "proxy_filters": null } ``` Note that setting `upgrades` configures websocket connections, but will defer to the protocol of the incoming request. This allows for the sidecar to handle websocket connections to certain routes and clusters, and http request for others. See [this tutorial on configuring websockets](https://github.com/greymatter-io/gm-control-api/blob/release-1.2/docs/examples/websockets/readme.md) for more detailed examples. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/traffic_control/protocols.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.