Nginx Plus TCP Load Balancing: Configuration, Principles, and Monitoring

Nginx Plus’s commercial edition now includes TCP load balancing, a feature introduced in Nginx 1.7.7 and available only in the paid version; a trial can be requested on the official website. In addition to the traditional HTTP load balancing, Nginx can now balance traffic based on the TCP protocol.

HTTP load balancing operates at layer 7 (application layer) and is often referred to as “seven‑layer load balancing.” TCP load balancing works at layer 4 (network and transport layers) and is commonly called “four‑layer load balancing,” similar to solutions such as LVS (Linux Virtual Server) and hardware appliances like F5.

TCP Load Balancing Configuration Method

Nginx uses a new stream module to implement TCP load balancing. This module, similar to the http and mail modules, allows you to define a set of services that listen for TCP connections and forward them using the proxy_pass directive within an upstream server group.

To enable it, edit nginx.conf and add a stream block at the same level as the http block:

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;
    }
}

TCP Load Balancing Execution Principle

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

The stream module supports Nginx’s existing scheduling algorithms, including the default Round Robin and hash‑based selection. Using a hash algorithm with $remote_addr enables simple session persistence, ensuring that connections from the same client IP are consistently routed to the same upstream server.

Like other upstream modules, the stream module allows custom weights (e.g., weight=2), backup and down parameters to exclude failed servers, and max_conns to limit the number of simultaneous TCP connections per server—useful for protecting servers under high concurrency.

Nginx monitors both client and upstream connections. As soon as data arrives, Nginx reads it and forwards it to the upstream side without inspecting the TCP payload. It maintains an in‑memory buffer for read/write operations, which can automatically expand when large amounts of data are transferred.

If either side closes the connection or the connection remains idle longer than the proxy_timeout setting, Nginx closes the connection. For long‑lived TCP connections, it is important to set an appropriate proxy_timeout and monitor the listening socket’s so_keepalive option to avoid premature termination.

Service Health Monitoring

The TCP load‑balancing module includes built‑in health checks. If an upstream server fails to accept TCP connections within the proxy_connect_timeout period, Nginx marks it as unhealthy and immediately attempts to connect to another server in the upstream group, logging the failure in the error log.

If a server repeatedly fails (exceeding max_fails or fail_timeout), Nginx removes it from the pool. After a 60‑second cooldown, Nginx periodically retries the server; once it recovers, the server is gradually re‑added to the upstream group, slowly increasing its share of traffic.

In high‑concurrency scenarios, sudden spikes can overwhelm a freshly started service because most requests hit cached “hot” data. Pre‑warming the service or gradually ramping up traffic helps mitigate this risk, similar to warming up a MySQL cache where over 95 % of queries hit memory.

TCP load balancing operates on the same principles as LVS but runs in user space, offering performance higher than HTTP load balancing yet lower than kernel‑level LVS. Note that the stream module is a paid feature of Nginx Plus.

Source: Translated from 伯乐在线.

Long‑press the QR code to open the browser.

Download the 大讲堂在线课程 APP for Android and iOS.

Qunar’s latest and hottest video courses are all here!