1. Introduction
NGINX is a common cross-platform multipurpose server. As such, it can link many parts of an internal or external network, transferring and providing access to files and dynamic data. In fact, it can also serve as a load balancer, ensuring availability. To that end, we may need to configure delay times to avoid errors like 504 Gateway Time-out and 408 Request Time-out.
In this tutorial, we explore timeouts and ways to set and disable different timeouts in NGINX. First, we explain how to add options in the NGINX configuration. After that, we enumerate and describe NGINX timeout types and settings. Finally, we show a snippet to effectively disable common timeouts.
We tested the code in this tutorial on Debian 11 (Bullseye) with GNU Bash 5.1.4. It should work in most POSIX-compliant environments.
2. Configure NGINX
A timeout is a period of time after which a given process is terminated. While this can be an actual Linux process ID (PID), timeouts are a general concept.
Since NGINX can serve in many different capacities, the timeout we may want to set might depend on the function we aim for. Here, all timeouts are in seconds, but we can also use the NGINX time units:
- ms – milliseconds
- s – seconds
- m – minutes
- h – hours
- d – days
- w – weeks
- M – months, 30 days
- y – years, 365 days
Critically, for some settings, using 0 forces immediate timeouts, so setting an unlikely high value like 9999999 or simply 1y is usually the way to disable them.
To set options, we modify NGINX configuration files. Best practices dictate we shouldn’t change nginx.conf directly, and instead should create .conf files in conf.d, which is usually in /etc/nginx:
$ ls /etc/nginx/conf.d
xopt.conf
Almost all options we discuss can be set in any of three blocks:
To do that, we just add the appropriate name with its parameter values after whitespace, finishing with a ; semicolon:
$ cat /etc/nginx/conf.d/xopt.conf
http {
send_timeout 1800;
}
After any modifications, we can check the configuration file syntax:
$ nginx -t -c /etc/nginx/conf.d/xopt.conf
nginx: the configuration file /etc/nginx/conf.d/xopt.conf syntax is ok
nginx: configuration file /etc/nginx/conf.d/xopt.conf test is successful
In this case, the -t flag of nginx tests the file specified by -c (usual default /etc/nginx/nginx.conf).
Finally, we reload NGINX:
$ nginx -s reload
[OR]
$ systemctl reload nginx
[OR]
$ service nginx reload
Now, let’s explore some specific settings.
3. Basic NGINX Timeouts
Several of the NGINX timeouts are basic and fairly universal:
- client_body_timeout – maximum time (between successive reads) for reading the body of a client request (defaults 60, may result in 408 Request Time-out)
- client_header_timeout – maximum time for reading the header of a client request (default 60, may result in 408 Request Time-out)
- keepalive_timeout – maximum time for a client connection to be kept on the server (mandatory first parameter, default 75, 0 disables), as well as value for the Keep-Alive: timeout=time (optional second parameter, default 60)
- lingering_timeout – if lingering_close is on, sets the maximum time for more client data to arrive (default 5), which it reads and ignores, repeating the cycle for a maximum time of lingering_time (default 30)
- send_timeout – maximum time (between successive writes) when sending a response back to a client (default 60)
In addition, name resolution may be the culprit for many issues. By setting resolver_timeout, we can limit or increase the maximum time for resolving a name when using NGINX (default 30).
Also, ssl_session_timeout is the maximum time for a client to reuse SSL session parameters (default 5m).
All of the above affect most connections. Now, let’s move on to some specifics.
4. NGINX Low-level TCP Timeout
On a lower level, the listen directive has a so_keepalive parameter to configure the TCP listening socket. In other words, by setting it to on or off, we enable the keepalive mechanism SO_KEEPALIVE.
For supported operating systems, we can also supply a colon-separated list of options:
- keepidle – sets TCP_KEEPIDLE
- keepintvl – sets TCP_KEEPINTVL
- keepcnt – sets TCP_KEEPCNT
On the other hand, skipping any of these parameters leaves the system default.
5. Server
The server directive has its own parameters provided by the upstream module.
One of them is the fail_timeout, which sets the maximum time to attempt max_fails (default 1, 0 disables) server contact before considering the server unavailable (default 10). This state remains for the same period before any retries.
However, if we only have a single server, these options are ignored.
6. NGINX proxy_* Timeouts
There are three common proxy server timeout values for NGINX:
- proxy_connect_timeout – maximum time to connect to a proxied server (default 60, usually under 75)
- proxy_read_timeout – maximum time (between reads) to read proxied server response (default 60)
- proxy_send_timeout – maximum time (between writes) to send proxied server request (default 60)
In addition, there is the proxy_cache_lock_timeout that defines the maximum time to prevent simultaneous cache requests (default 5) if proxy_cache_lock (default off) is on. Stale caching can also depend on this timeout value.
7. NGINX fastcgi_* Timeouts
Of course, NGINX also provides FastCGI server transmission constraint settings:
- fastcgi_connect_timeout – maximum time to connect with FastCGI server (default 60, usually under 75)
- fastcgi_read_timeout – maximum time (between reads) to read FastCGI server response (default 60)
- fastcgi_send_timeout – maximum time (between writes) to send FastCGI server request (default 60)
Again, fastcgi_cache_lock_timeout defines the maximum time to prevent simultaneous cache requests (default 5) if fastcgi_cache_lock (default off) is on. Further, similar to the proxy_* settings, stale caching can depend on this timeout value.
8. NGINX memcached_* Timeouts
For Memcached, NGINX offers similar options to those for proxy and FastCGI:
- memcached_connect_timeout – maximum time to connect with memcached server (default 60, usually under 75)
- memcached_read_timeout – maximum time (between reads) to read memcached server response (default 60)
- memcached_send_timeout – maximum time (between writes) to send memcached server request (default 60)
Of course, we don’t have a cache lock in this case.
9. Disabling Common NGINX Timeouts
While similar settings exist for other modules as well, in general, to effectively disable the effect of common timeout options, we can use a list of settings in an http or server block:
keepalive_timeout 1d;
send_timeout 1d;
client_body_timeout 1d;
client_header_timeout 1d;
proxy_connect_timeout 1d;
proxy_read_timeout 1d;
proxy_send_timeout 1d;
fastcgi_connect_timeout 1d;
fastcgi_read_timeout 1d;
fastcgi_send_timeout 1d;
memcached_connect_timeout 1d;
memcached_read_timeout 1d;
memcached_send_timeout 1d;
In all cases, we set the period to one day. Consequently, using these settings may heavily reduce performance.
10. Summary
In this article, we discussed timeouts and the NGINX timeout settings.
In conclusion, while NGINX provides many options to change different timeouts, changing the correct one is imperative for optimizing performance.