Nginx Upstream Keepalive: Directives, Protocol Requirements, and Cache Configuration

In Nginx, the keepalive directive configures caching of keepalive connections to upstream servers. Each worker process preserves a configured number of idle keepalive connections in its cache rather than opening a new connection for each proxied request.

Upstream Keepalive Directive and Version Defaults

The keepalive directive is configured within the upstream block. It sets the maximum number of idle keepalive connections to upstream servers preserved in the cache of each worker process. Setting this parameter to zero disables keepalive connections to upstream servers.

The keepalive directive does not limit the total number of connections to upstream servers that an Nginx worker process can open. The documentation states that the connections parameter should be set to a number small enough to let upstream servers process new incoming connections as well.

Starting in version 1.29.7, keepalive connections are enabled by default, with a default limit of 32 connections per worker process. Before version 1.29.7, when using load balancing methods other than the default round-robin method, it was necessary to activate those methods before the keepalive directive.

Cross-Location Sharing and the local Parameter

The documentation defines specific behavior for sharing keepalive connections across different locations:

• The local parameter (introduced in version 1.29.7) disables sharing of cached keepalive connections across different locations even if the upstream server address matches.
• If the local parameter is not specified, any matching cached connection to the same upstream server can be reused regardless of location.

Protocol and Header Requirements

The documentation specifies distinct configuration rules for upstream protocols:

• HTTP: The proxy_http_version directive should be 1.1 (the default since version 1.29.7) or set to 2, and the Connection header field should be cleared. Alternatively, HTTP/1.0 persistent connections can be used by passing the Connection: Keep-Alive header field to an upstream server, though this method is not recommended.
• FastCGI: Keepalive connections require setting fastcgi_keep_conn on; in the location block.
• SCGI and uwsgi: These protocols do not have a notion of keepalive connections.
• memcached: Upstream keepalive caching can be configured with memcached_pass and the keepalive directive in the upstream block.

Cache Behavior and Server Limits

Cached keepalive connections are maintained per worker process. When the configured idle connection count is exceeded, Nginx closes the least recently used connections.

When the max_conns parameter is configured on an upstream server, it limits the maximum number of simultaneous active connections to that server. If the server group does not reside in shared memory, the limitation operates per worker process. If idle keepalive connections, multiple workers, and shared memory are enabled, the total number of active and idle connections to the proxied server may exceed the max_conns value.

Keepalive Lifecycle Directives

The ngx_http_upstream_module provides three directives within the upstream context to control keepalive connection lifecycles:

Documented Configuration Examples

For HTTP proxying prior to version 1.29.7, documentation outlines configuring the upstream block with keepalive and explicitly configuring the location:

upstream http_backend {
    server 127.0.0.1:8080;
    keepalive 16;
}

server {
    ...
    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1; # before version 1.29.7
        proxy_set_header Connection ""; # before version 1.29.7
        ...
    }
}

For FastCGI upstream servers, fastcgi_keep_conn is required:

upstream fastcgi_backend {
    server 127.0.0.1:9000;
    keepalive 8;
}

server {
    ...
    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}

For memcached upstream servers, keepalive connections can be defined as follows:

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;
    keepalive 32;
}

server {
    ...
    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }
}

Research Method and Limitations

This technical summary was prepared exclusively from the supplied public source excerpts of the official Nginx ngx_http_upstream_module documentation. The supplied source text is truncated, omitting competing coverage and leaving aspects of connection handling outside the visible excerpts unverified. No hands-on testing, benchmarks, or independent runtime observations were conducted.

Source references

• nginx.org documentation