DEV Community

Arnob
Arnob

Posted on

What is Nginx Stream?

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

captionless image

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)
Enter fullscreen mode Exit fullscreen mode

Example: TCP Load Balancing for PostgreSQL 

stream {
    upstream postgres_backend {
        server 10.0.0.11:5432;
        server 10.0.0.12:5432;
    }
Enter fullscreen mode Exit fullscreen mode 
    server {
        listen 5432;
        proxy_pass postgres_backend;
    }
}
Enter fullscreen mode Exit fullscreen mode

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;
    }
}
Enter fullscreen mode Exit fullscreen mode

Now:

ssh -p 2222 user@your-server
Enter fullscreen mode Exit fullscreen mode

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 |
Enter fullscreen mode Exit fullscreen mode

Stream vs Reverse Proxy

HTTP Reverse Proxy 

Browser -> NGINX -> Web App
Enter fullscreen mode Exit fullscreen mode

NGINX understands:

  • URLs
  • Headers
  • Cookies
  • Methods

Stream Proxy 

App -> NGINX -> Database
Enter fullscreen mode Exit fullscreen mode

NGINX only forwards:

  • TCP packets
  • UDP packets

It does not understand application data.

Common Use Cases

Database HA 

App -> NGINX Stream -> PostgreSQL Cluster
Enter fullscreen mode Exit fullscreen mode

Redis Load Balancing 

App -> NGINX Stream -> Redis Nodes
Enter fullscreen mode Exit fullscreen mode

MQTT Broker Proxy 

IoT Devices -> NGINX Stream -> MQTT Broker
Enter fullscreen mode Exit fullscreen mode

Kubernetes

Used sometimes for:

  • TCP ingress
  • Database exposure
  • Non-HTTP services

Enable Stream Module

Ubuntu/Debian

Install:

sudo apt install libnginx-mod-stream
Enter fullscreen mode Exit fullscreen mode

Check:

nginx -V 2>&1 | grep stream
Enter fullscreen mode Exit fullscreen mode

Stream Configuration Location

Usually:

/etc/nginx/nginx.conf
Enter fullscreen mode Exit fullscreen mode

or

/etc/nginx/streams-enabled/
Enter fullscreen mode Exit fullscreen mode

Example:

stream {
    include /etc/nginx/streams-enabled/*.conf;
}
Enter fullscreen mode Exit fullscreen mode

Health Check Example 

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

SSL Passthrough

NGINX Stream can pass encrypted TLS traffic without decrypting it.

Example:

Client -> NGINX -> HTTPS Backend
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Example:

stream {
    upstream postgres_cluster {
        server 10.0.0.11:5432;
        server 10.0.0.12:5432;
    }
Enter fullscreen mode Exit fullscreen mode 
    server {
        listen 5432;
        proxy_pass postgres_cluster;
    }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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;
    }
}
Enter fullscreen mode Exit fullscreen mode

Usage:

ssh -p 2222 user@example.com
Enter fullscreen mode Exit fullscreen mode

4. Redis Proxy 

Application
    |
NGINX Stream
    |
Redis Cluster
Enter fullscreen mode Exit fullscreen mode

Used for:

  • Load balancing
  • HA
  • Failover entrypoint

5. MQTT / IoT Systems

Used in IoT architecture:

IoT Device
    |
NGINX Stream
    |
MQTT Broker
Enter fullscreen mode Exit fullscreen mode

Common brokers:

  • Mosquitto
  • EMQX

6. Mail Services

Protocols:

  • SMTP
  • IMAP
  • POP3

Example:

Mail Client
     |
NGINX Stream
     |
Mail Server
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Real Infrastructure Examples

Example 1: PostgreSQL HA 

App
 |
NGINX Stream
 |
+----------------+
| Primary DB     |
| Replica DB     |
+----------------+
Enter fullscreen mode Exit fullscreen mode

Example 2: Kubernetes Database Access 

Internet
   |
Load Balancer
   |
NGINX Stream
   |
K8s PostgreSQL Service
Enter fullscreen mode Exit fullscreen mode

Example 3: Redis Cluster 

Application
   |
NGINX Stream
   |
Redis Nodes
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Use the Stream module for: 

TCP
UDP
Databases
SSH
MQTT
Redis
Raw sockets
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Top comments (0)