Learning nginx - NGINX Stream Module (Layer 4 TCP/UDP Load Balancing)

#Introduction

So far we've covered NGINX at the HTTP layer. But NGINX can also be a Layer 4 (transport layer) load balancer through the stream module: forwarding raw TCP and UDP connections without understanding the protocols on top. This Episode 17 covers the stream module.

You'll proxy TCP connections to a database cluster, balance UDP traffic for DNS, and apply SSL passthrough that forwards encryption straight to the backend. After this episode, your NGINX can handle any traffic, not just HTTP.

#Introducing the stream Module

#Layer 4 vs Layer 7

The http module works at Layer 7: NGINX understands HTTP, inspects URIs, headers, and cookies. The stream module works at Layer 4: NGINX only opens a TCP or UDP connection and forwards raw bytes without unpacking the contents.

Its advantages:

• Can balance any protocol: PostgreSQL, MySQL, Redis, gRPC, SSH, DNS.
• Very low overhead because there's no protocol parsing.
• One NGINX can serve as both an HTTP and a TCP load balancer.

The stream directive is declared in a separate context, alongside http:

stream {
    upstream db_cluster {
        server 10.0.3.11:5432;
        server 10.0.3.12:5432;
    }
 
    server {
        listen 5432;
        proxy_pass db_cluster;
    }
}

The stream context lives at the top level of nginx.conf, not inside http.

#Load Balancing Databases and Services (TCP)

#TCP Proxying for PostgreSQL

Applications don't need to know which database address to use. NGINX picks the backend based on the algorithms we discussed in episode 7:

stream {
    upstream postgres_cluster {
        least_conn;
        server 10.0.3.11:5432;
        server 10.0.3.12:5432;
    }
 
    server {
        listen 5432;
        proxy_pass postgres_cluster;
        proxy_timeout 60s;
    }
}

The application only points at the NGINX IP on port 5432. least_conn suits database connections with uneven lifetimes. Note: database load balancing distributes new connections, not data replication — replication remains PostgreSQL's own job.

#Proxying Redis

The same pattern applies to Redis:

stream {
    upstream redis_cluster {
        ip_hash;
        server 10.0.3.21:6379;
        server 10.0.3.22:6379;
    }
 
    server {
        listen 6379;
        proxy_pass redis_cluster;
    }
}

ip_hash maintains session persistence so caches and state don't bounce between backends.

#Load Balancing UDP Traffic

#UDP Proxying for DNS

The stream module also handles UDP with the listen directive taking a udp parameter:

stream {
    upstream dns_cluster {
        server 10.0.4.11:53;
        server 10.0.4.12:53;
    }
 
    server {
        listen 53 udp;
        proxy_pass dns_cluster;
        proxy_responses 1;
    }
}

listen 53 udp; creates a UDP listener. The proxy_responses 1; parameter tells NGINX how many responses to expect from the backend for each request — important so NGINX knows when one UDP exchange is complete.

#UDP Proxying for Video Streaming

Realtime streaming like RTP and QUIC-based applications use UDP:

stream {
    server {
        listen 1935 udp;
        proxy_pass 10.0.5.11:1935;
    }
}

#SSL Passthrough

#Forwarding Encryption without Decryption

Sometimes SSL decryption at NGINX isn't desired: for example when the backend handles its own certificates, or the protocol uses an application that needs to see encrypted packets. The solution is SSL passthrough — NGINX just forwards encrypted bytes:

stream {
    upstream secure_services {
        server 10.0.6.11:8443;
        server 10.0.6.12:8443;
    }
 
    server {
        listen 443;
        proxy_pass secure_services;
    }
}

Notice: there's no ssl_certificate at all. NGINX opens a TCP connection on port 443, points it at the backend, and lets the TLS handshake happen directly between the client and the backend. The benefits: zero TLS overhead and the backend is free to use its own certificates. The downside: NGINX can't see the request contents, so URI- or host-based routing isn't possible.

#Conclusion

Episode 17 extended NGINX's reach to all network traffic: you can balance TCP for databases and services, handle UDP for DNS and streaming, and forward SSL passthrough without decryption.

Key takeaways:

• The stream module handles Layer 4; the http module handles Layer 7.
• TCP proxying suits PostgreSQL, MySQL, Redis, and any other service.
• listen 53 udp and proxy_responses are needed for UDP load balancing.
• SSL passthrough without ssl_certificate forwards encrypted bytes to the backend.
• Passthrough enables L4 routing but can't see URIs or hosts.
• Upstream algorithms in stream are the same as in http.

In the next episode we'll discuss NGINX Plus vs open source and modern alternatives — NGINX Plus commercial features, a comparison with HAProxy as a pure load balancer, and comparisons with the cloud-native Traefik and Caddy.