How to Enable and Configure TCP Load Balancing with Nginx Plus

What is TCP Load Balancing in Nginx Plus?

Nginx Plus, the commercial edition of Nginx, introduced TCP load‑balancing in version 1.7.7. It extends the traditional HTTP (layer‑7) load‑balancing to layer‑4 TCP load‑balancing, similar to solutions like LVS or F5 hardware balancers.

Configuration Method

The new stream module works like the http and mail modules, allowing you to define listeners and upstream groups for TCP services. Below is a minimal configuration that listens on port 1034 and forwards traffic to an upstream named app.

stream {
    server {
        listen 1034;
        proxy_pass app;
    }
    upstream app {
        server 192.168.0.3:1034;
        server 192.168.0.4:1034;
        server 192.168.0.6:1034;
    }
}

Execution Principle

When Nginx receives a new client connection on the listening port, it immediately runs a routing algorithm to select an upstream server IP, then creates a new upstream connection to that server.

The stream module supports the same scheduling algorithms as the classic upstream module, such as Round Robin (default) and Hash. Using a hash based on $remote_addr can achieve simple session persistence, ensuring the same client IP is consistently directed to the same backend.

Weight, backup, and down parameters can be used to influence traffic distribution, while max_conns limits the number of simultaneous connections to a particular server, providing overload protection in high‑concurrency scenarios.

Nginx monitors both client and upstream connections. Data received from either side is immediately forwarded without inspecting the TCP payload. An internal memory buffer holds data for both directions, and the buffer size grows automatically for large transfers.

If either side closes the connection or the connection remains idle longer than the proxy_timeout, Nginx closes it. For long‑living TCP connections, appropriate proxy_timeout and so_keepalive settings are essential to avoid premature termination.

Service Robustness Monitoring

The stream module includes built‑in health checks. If a backend refuses connections for longer than proxy_connect_timeout, it is marked as failed and Nginx immediately tries another server in the upstream group. Failures are logged to the error log.

If a server repeatedly fails (exceeding max_fails or fail_timeout), it is temporarily removed from the pool. After 60 seconds Nginx probes the server again; if it recovers, the server is re‑added with a gradual increase in traffic share.

In high‑traffic environments, a sudden surge of requests can overwhelm a freshly started service because most requests hit cached “hot” data. Two mitigation strategies are recommended: (1) ramp up traffic gradually to allow caches to warm, and (2) pre‑warm services by loading frequently used data before opening them to users.

Overall, TCP load balancing in Nginx operates similarly to LVS but runs in user space, making it slightly slower than kernel‑mode solutions. Nevertheless, it offers a powerful, flexible option for layer‑4 traffic, albeit as a paid feature in Nginx Plus.

Reference: http://nginx.org/