apisix/docs/en/latest/stream-proxy.md

title
Stream Proxy

TCP is the protocol for many popular applications and services, such as LDAP, MySQL, and RTMP. UDP (User Datagram Protocol) is the protocol for many popular non-transactional applications, such as DNS, syslog, and RADIUS.

APISIX can dynamically load balancing TCP/UDP proxy. In Nginx world, we call TCP/UDP proxy to stream proxy, we followed this statement.

How to enable stream proxy?

Setting the stream_proxy option in conf/config.yaml, specify a list of addresses that require dynamic proxy. By default, no stream proxy is enabled.

apisix:
  stream_proxy: # TCP/UDP proxy
    tcp: # TCP proxy address list
      - 9100
      - "127.0.0.1:9101"
    udp: # UDP proxy address list
      - 9200
      - "127.0.0.1:9211"

How to set route?

Here is a mini example:

curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "remote_addr": "127.0.0.1",
    "upstream": {
        "nodes": {
            "127.0.0.1:1995": 1
        },
        "type": "roundrobin"
    }
}'

It means APISIX will proxy the request to 127.0.0.1:1995 which the client remote address is 127.0.0.1.

For more use cases, please take a look at test case.

More route match options

And we can add more options to match a route.

Here is an example:

curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "server_addr": "127.0.0.1",
    "server_port": 2000,
    "upstream": {
        "nodes": {
            "127.0.0.1:1995": 1
        },
        "type": "roundrobin"
    }
}'

It means APISIX will proxy the request to 127.0.0.1:1995 which the server address is 127.0.0.1 and the server port is equal to 2000.

Read Admin API's Stream Route section for the complete options list.

Accept TLS over TCP

APISIX can accept TLS over TCP.

First of all, we need to enable TLS for the TCP address:

apisix:
  stream_proxy: # TCP/UDP proxy
    tcp: # TCP proxy address list
      - addr: 9100
        tls: true

Second, we need to configure certificate for the given SNI. See Admin API's SSL section for how to do.

Third, we need to configure a stream route to match and proxy it to the upstream:

curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "remote_addr": "127.0.0.1",
    "upstream": {
        "nodes": {
            "127.0.0.1:1995": 1
        },
        "type": "roundrobin"
    }
}'

When the connection is TLS over TCP, we can use the SNI to match a route, like:

curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "sni": "a.test.com",
    "upstream": {
        "nodes": {
            "127.0.0.1:5991": 1
        },
        "type": "roundrobin"
    }
}'

In this case, a connection handshaked with SNI a.test.com will be proxied to 127.0.0.1:5991.