Skip to main content

Version: 3.8.0

Proxy Transport Layer (L4) Traffic

By default, APISIX operates as an application layer (L7) proxy. APISIX also supports the handling of transport layer (L4) TCP and UDP traffic, either dedicated or on top of the handling of application layer (L7) traffic.

This guide will show you how to configure APISIX to proxy transport layer (L4) traffic and configure a stream route to establish connection with MySQL server.


Start MySQL Server

Start a MySQL instance as sample upstream service in the same Docker network as APISIX, and configure the root password:

docker run -d \
--name mysql \
--network=apisix-quickstart-net \
-e MYSQL_ROOT_PASSWORD=my-secret-pw \
mysql \
mysqld --default-authentication-plugin=mysql_native_password

Enable Transport Layer (L4) Proxy

By default, APISIX only has application layer (L7) proxy enabled. To update the setting to also accept transport layer (L4) traffic, configure proxy_mode and stream_proxy in config.yaml configuration file as follows:

docker exec apisix-quickstart /bin/sh -c "echo '
enable_control: true
port: 9092
proxy_mode: http&stream
- 9100
role: traditional
config_provider: etcd
admin_key_required: false
port: 9091
' > /usr/local/apisix/conf/config.yaml"

proxy_mode: accept both transport layer (L4) and application layer (L7) traffic.

stream_proxy: configure the interface for transport layer (L4) proxy.

Reload APISIX for configuration changes to take effect:

docker exec apisix-quickstart apisix reload

Create Stream Route

Create a stream route and configure MySQL server to be the upstream service:

curl "" -X PUT -d '
"id": "stream-route-mysql",
"upstream": {
"nodes": {
"mysql:3306": 1
"type": "roundrobin"

Verify Connection

Connect with the MySQL server as root and key in the password once prompted:

mysql --host= --port=9100 -u root -p

If successful, you should see a welcome text similar to the following:

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: 8.2.0 MySQL Community Server - GPL
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Configure Matching Conditions on Stream Route

You can also configure matching conditions on stream routes to only allow requests that match the configured conditions.

Create the same stream route, but this time, with matching conditions on server_addr and server_port:

curl "" -X PUT -d '
"id": "stream-route-mysql",
"server_addr": "",
"server_port": 2000,
"upstream": {
"nodes": {
"mysql:3306": 1
"type": "roundrobin"

Verify Matching Conditions

Try to connect with the MySQL server again and key in the password:

mysql --host= --port=9100 -u root -p

You should see the request is rejected:

ERROR 2013 (HY000): Lost connection to MySQL server at 'reading initial communication packet', system error: 0

The connection would be successful if you update server_addr and server_port to and 9100 respectively, matching the expected address and port for connection.

For all available stream route configuration options, see Admin API, stream route.

Next Steps

APISIX also supports TLS over TCP connections as a transport layer (L4) proxy when accepting requests from downstream clients or proxying to upstream services. See configure TLS over TCP how-to guide to learn more (coming soon). Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.


API7 Cloud

SOC2 Type IRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation