Skip to main content
Version: 2.11

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"

If you need to enable both HTTP and stream proxy, set the only to false:

apisix:  stream_proxy: # TCP/UDP proxy    only: false    tcp: # TCP proxy address list      - 9100

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. mTLS is also supported, see Protect Route 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.