# Stream Routes

Stream routes enable API7 Gateway to proxy Layer 4 (L4) traffic — TCP and UDP connections — in addition to the standard Layer 7 (HTTP/HTTPS) traffic handled by regular [routes](https://docs.api7.ai/api7-gateway/key-concepts/services-and-routes.md). This allows you to use API7 Gateway as a unified proxy for both HTTP APIs and non-HTTP protocols such as databases, message queues, and custom TCP services.

## How Stream Routes Work[​](#how-stream-routes-work "Direct link to How Stream Routes Work")

Unlike HTTP routes that match on URI paths, HTTP methods, and headers, stream routes match on **network-layer attributes**:

| Match Field   | Description                                  | Example          |
| ------------- | -------------------------------------------- | ---------------- |
| `remote_addr` | Client IP address or CIDR range              | `10.0.0.0/8`     |
| `server_addr` | Gateway listening IP address                 | `192.168.1.100`  |
| `server_port` | Gateway listening port                       | `3306`           |
| `sni`         | TLS Server Name Indication (for TLS streams) | `db.example.com` |

All specified match fields are evaluated with AND logic. If no match fields are specified, the stream route matches all traffic on the configured stream proxy ports.

### Request Flow[​](#request-flow "Direct link to Request Flow")

<!-- -->

1. A TCP or UDP client connects to one of the gateway's configured `stream_proxy` ports.
2. The gateway evaluates all stream routes against the connection's network attributes.
3. The matching stream route determines the upstream, and the connection is proxied to the upstream service.

## Stream Services[​](#stream-services "Direct link to Stream Services")

Stream routes must belong to a **stream-type service** (service with `type: stream`). A stream service cannot contain regular HTTP routes, and an HTTP service cannot contain stream routes.

Stream services share the same lifecycle as HTTP services:

* Configuration scoped to gateway groups
* Upstream inheritance (stream routes inherit upstream configuration from their parent service unless overridden)

## Supported Plugins[​](#supported-plugins "Direct link to Supported Plugins")

Only a subset of plugins support the stream (L4) context:

| Plugin           | Category      | Description                              |
| ---------------- | ------------- | ---------------------------------------- |
| `ip-restriction` | Security      | Allow/deny traffic based on client IP    |
| `limit-conn`     | Traffic       | Limit concurrent connections             |
| `mqtt-proxy`     | Protocol      | MQTT protocol proxy and routing          |
| `traffic-split`  | Traffic       | Split traffic across upstreams by weight |
| `prometheus`     | Observability | Expose stream metrics                    |
| `syslog`         | Observability | Log stream events to syslog              |

HTTP-only plugins (such as `key-auth`, `proxy-rewrite`, or `response-rewrite`) cannot be applied to stream routes.

## Enabling Stream Proxy[​](#enabling-stream-proxy "Direct link to Enabling Stream Proxy")

Before using stream routes, you must configure the gateway to listen on TCP and/or UDP ports for stream traffic. This is done in the gateway's `config.yaml`:

```
apisix:

  stream_proxy:

    tcp:

      - addr: 9100          # Listen on all interfaces, port 9100

      - addr: "127.0.0.1:9101"  # Listen on specific IP

        tls: true            # Enable TLS on this port

    udp:

      - 9200                 # Listen on all interfaces, port 9200
```

info

Stream proxy ports are separate from the HTTP proxy ports (`node_listen` / `ssl.listen`). Clients connect to stream proxy ports for L4 traffic and to HTTP ports for L7 traffic.

## Stream Routes vs. HTTP Routes[​](#stream-routes-vs-http-routes "Direct link to Stream Routes vs. HTTP Routes")

| Aspect            | HTTP Routes                              | Stream Routes                                           |
| ----------------- | ---------------------------------------- | ------------------------------------------------------- |
| Protocol          | HTTP, HTTPS, gRPC, WebSocket             | TCP, UDP                                                |
| Match criteria    | URI, host, headers, methods, expressions | Client IP, server IP, server port, SNI                  |
| Service type      | `http`                                   | `stream`                                                |
| Plugin support    | Full plugin library                      | 6 stream-compatible plugins                             |
| Routing algorithm | Radix tree on URI                        | Sequential match on IP/port (radix tree on SNI for TLS) |

## Next Steps[​](#next-steps "Direct link to Next Steps")

* [TCP/UDP Proxy](https://docs.api7.ai/api7-gateway/how-to-guides/protocol-proxy/tcp-udp-proxy.md): Step-by-step guide to proxy TCP and UDP traffic.
* [Services and Routes](https://docs.api7.ai/api7-gateway/key-concepts/services-and-routes.md): Learn about HTTP services and routes.
* [Plugins](https://docs.api7.ai/api7-gateway/key-concepts/plugins.md): Overview of the plugin system.