What is Nginx Stream?

Arnob

4 min read

·

May 17, 2026

--

Listen

Share

NGINX Stream is the Layer 4 (TCP/UDP) proxy module of NGINX.

Press enter or click to view image in full size

NGINX is famous for handling:

• HTTP
• HTTPS
• Reverse proxy
• Load balancing for web traffic

That works at Layer 7 (Application Layer).

But the Stream module allows NGINX to handle:

• TCP traffic
• UDP traffic

at Layer 4 (Transport Layer).

What NGINX Stream Is Used For

You can proxy or load-balance services like:

• PostgreSQL
• MySQL
• Redis
• MongoDB
• SSH
• SMTP
• MQTT
• Game servers
• Raw TCP applications

Architecture

Client
   |
   v
+--------+
| NGINX  |  <-- Stream Module (TCP/UDP Proxy)
+--------+
   |
   +-------------------+
   |                   |
   v                   v
Backend 1          Backend 2
(Postgres)         (Postgres Replica)

Example: TCP Load Balancing for PostgreSQL

stream {
    upstream postgres_backend {
        server 10.0.0.11:5432;
        server 10.0.0.12:5432;
    }

    server {
        listen 5432;
        proxy_pass postgres_backend;
    }
}

Here:

• NGINX listens on port 5432
• Forwards PostgreSQL TCP traffic
• Can load balance multiple DB servers

Example: SSH Proxy

stream {
    server {
        listen 2222;
        proxy_pass 10.0.0.20:22;
    }
}

Now:

ssh -p 2222 user@your-server

NGINX forwards TCP packets to the SSH server.

Difference Between HTTP and Stream

| Feature             | HTTP Module   | Stream Module        |
| ------------------- | ------------- | -------------------- |
| Layer               | L7            | L4                   |
| Protocols           | HTTP/HTTPS    | TCP/UDP              |
| Can inspect URL     | Yes           | No                   |
| Can inspect headers | Yes           | No                   |
| SSL termination     | Yes           | Limited/pass-through |
| Use case            | Websites/APIs | Databases, SSH, MQTT |

Stream vs Reverse Proxy

HTTP Reverse Proxy

Browser -> NGINX -> Web App

NGINX understands:

• URLs
• Headers
• Cookies
• Methods

Stream Proxy

App -> NGINX -> Database

NGINX only forwards:

• TCP packets
• UDP packets

It does not understand application data.

Common Use Cases

Database HA

App -> NGINX Stream -> PostgreSQL Cluster

Redis Load Balancing

App -> NGINX Stream -> Redis Nodes

MQTT Broker Proxy

IoT Devices -> NGINX Stream -> MQTT Broker

Kubernetes

Used sometimes for:

• TCP ingress
• Database exposure
• Non-HTTP services

Enable Stream Module

Ubuntu/Debian

Install:

sudo apt install libnginx-mod-stream

Check:

nginx -V 2>&1 | grep stream

Stream Configuration Location

Usually:

/etc/nginx/nginx.conf

or

/etc/nginx/streams-enabled/

Example:

stream {
    include /etc/nginx/streams-enabled/*.conf;
}

Health Check Example

upstream backend {
    server 10.0.0.1:3306 max_fails=3 fail_timeout=30s;
    server 10.0.0.2:3306;
}

SSL Passthrough

NGINX Stream can pass encrypted TLS traffic without decrypting it.

Example:

Client -> NGINX -> HTTPS Backend

Useful for:

• End-to-end encryption
• Kubernetes ingress passthrough
• Database TLS

Main Places Where NGINX Stream Is Used!

1. Database Load Balancing

Very common for:

• PostgreSQL
• MySQL
• Redis
• MongoDB

Architecture:

Application
     |
     v
+-----------+
| NGINX     |
| Stream    |
+-----------+
     |
+----+----+
|         |
v         v
DB-1     DB-2

Example:

stream {
    upstream postgres_cluster {
        server 10.0.0.11:5432;
        server 10.0.0.12:5432;
    }

    server {
        listen 5432;
        proxy_pass postgres_cluster;
    }
}

2. Kubernetes TCP/UDP Services

In Kubernetes, HTTP ingress handles websites only.

But for:

• PostgreSQL
• Redis
• MQTT
• Game servers
• SMTP

you need TCP/UDP routing.

Example:

External Client
      |
      v
NGINX Stream
      |
      v
Kubernetes Service

Common with:

• NGINX Ingress Controller
• TCP services in K8s

3. SSH Gateway / Bastion

You can expose SSH through NGINX.

Example:

stream {
    server {
        listen 2222;
        proxy_pass 10.0.0.5:22;
    }
}

Usage:

ssh -p 2222 user@example.com

4. Redis Proxy

Application
    |
NGINX Stream
    |
Redis Cluster

Used for:

• Load balancing
• HA
• Failover entrypoint

5. MQTT / IoT Systems

Used in IoT architecture:

IoT Device
    |
NGINX Stream
    |
MQTT Broker

Common brokers:

• Mosquitto
• EMQX

6. Mail Services

Protocols:

• SMTP
• IMAP
• POP3

Example:

Mail Client
     |
NGINX Stream
     |
Mail Server

7. Game Servers

Online multiplayer games often use:

• UDP
• TCP sockets

NGINX Stream can proxy them.

8. TLS/SSL Passthrough

When you do not want NGINX to decrypt SSL.

Example:

Client HTTPS
      |
NGINX Stream
      |
Backend HTTPS

Useful for:

• End-to-end encryption
• Banking systems
• Kubernetes passthrough ingress

9. High Availability Entry Point

Single access point for multiple backend servers.

Example:

Clients
   |
NGINX Stream VIP
   |
+--+--+--+
|  |  |  |
DB App Cache

Real Infrastructure Examples

Example 1: PostgreSQL HA

App
 |
NGINX Stream
 |
+----------------+
| Primary DB     |
| Replica DB     |
+----------------+

Example 2: Kubernetes Database Access

Internet
   |
Load Balancer
   |
NGINX Stream
   |
K8s PostgreSQL Service

Example 3: Redis Cluster

Application
   |
NGINX Stream
   |
Redis Nodes

When NOT to Use Stream

Do NOT use Stream for:

• Websites
• REST APIs
• Path routing
• Header-based routing
• Cookie-based routing

For those who use the normal HTTP module.

Simple Rule

Use the HTTP module for:

Websites
APIs
HTTP/HTTPS traffic

Use the Stream module for:

TCP
UDP
Databases
SSH
MQTT
Redis
Raw sockets

Important Limitation

NGINX Stream cannot:

• Route by URL path
• Read HTTP headers
• Modify HTTP requests
• Cache HTTP responses

Because it works below HTTP.

Summary

NGINX Stream = TCP/UDP proxy + load balancer.

Think of it as:

HTTP module  -> Web traffic
Stream module -> Raw network traffic