NGINX worker_rlimit_nofile: setting file descriptor limits correctly

nginx file descriptor exhaustion is a silent failure mode. Existing connections continue to be served, but new connections queue in the kernel backlog and are eventually dropped. The client sees a timeout, while nginx error logs may show nothing until the limit is hit.

worker_rlimit_nofile raises the per-worker file descriptor limit above conservative operating system defaults. It does not operate in isolation. It sits inside a layered stack of kernel parameters, systemd service limits, container runtime defaults, and PAM session policies. A value written into nginx.conf is only effective if the master process inherits a hard limit at least as high, and the kernel ceiling permits it. If any layer caps the limit below your intended value, workers inherit that lower ceiling and your tuning is silently ignored.

What this controls

The worker_rlimit_nofile directive sets the soft and hard RLIMIT_NOFILE for each nginx worker via setrlimit(). It is defined in the main context of nginx.conf and accepts a single integer. There is no default; if omitted, workers inherit the master’s limit.

The limit is applied after the master forks a worker, so the master process itself is unaffected. The master retains the limit it inherited from systemd, the shell, or the container runtime. Workers can raise their soft limit up to the inherited hard limit, but they cannot exceed the kernel ceiling defined by fs.nr_open.

If the inherited hard limit is higher than worker_rlimit_nofile, nginx attempts to lower the worker hard limit to the directive value. This requires CAP_SYS_RESOURCE; without it, setrlimit() fails with an alert in the error log, and the worker retains the higher inherited limit. In practice, the effective limit is the greater of the directive and the inherited floor, capped by fs.nr_open.

File descriptors are cheap. In production, set the directive generously. A value of 65536 is a safe default for most servers.

flowchart TD
    kernel[kernel fs.nr_open] --> runtime[systemd or container runtime]
    runtime --> master[nginx master inherits]
    master --> worker[worker_rlimit_nofile setrlimit]
    worker --> pool[client connections upstream connections logs temp files]

Prerequisites

Before changing limits, inspect the current ceiling at every layer.

# Kernel absolute ceiling per process
cat /proc/sys/fs/nr_open

# System-wide open file ceiling
cat /proc/sys/fs/file-max

# Maximum connections per worker
nginx -T 2>/dev/null | grep -m1 'worker_connections'

# systemd limit for the nginx service
systemctl show nginx -p LimitNOFILE 2>/dev/null || echo 'nginx service not found'

# Shell limit (relevant only for manual nginx launches)
ulimit -n

If the kernel ceiling is below your target, raise it via sysctl:

sudo sysctl -w fs.nr_open=1048576
echo 'fs.nr_open=1048576' | sudo tee /etc/sysctl.d/99-nginx-fd.conf

If nginx is managed by systemd, the shell ulimit is irrelevant for the daemon.

Procedure

1. Calculate the required limit

Each active client connection consumes one file descriptor. In reverse proxy mode, each request typically opens a second FD to the upstream server. Log files, temporary files for large request or response bodies, and cached static files add more.

Use this floor:

worker_rlimit_nofile >= (worker_connections * 2) + 1024

For a proxy worker with worker_connections 4096, set worker_rlimit_nofile 65536. The extra headroom covers logs, temp files, and event notification descriptors. If open_file_cache is enabled, add its max= parameter to the requirement.

Upstream keepalive connections can reuse sockets, so the multiplier is a worst-case floor, not an exact count.

2. Set the systemd floor

When systemd starts nginx, PAM limits.conf is not consulted for the daemon. The systemd unit sets the baseline limit the master inherits. Workers can raise their soft limit up to the master’s hard limit, but only if the inherited hard limit is at least as high as the target.

Create a drop-in to set a generous floor:

sudo mkdir -p /etc/systemd/system/nginx.service.d
sudo tee /etc/systemd/system/nginx.service.d/limits.conf <<'EOF'
[Service]
LimitNOFILE=65536
EOF

sudo systemctl daemon-reload
sudo systemctl restart nginx

A reload is not sufficient; process limits are inherited at fork() and cannot be changed for running workers without restart. A full restart drops active connections, so plan for a brief maintenance window or use a rolling restart strategy if traffic cannot be interrupted.

3. Configure nginx

Add the directive to the main context of nginx.conf, outside any server or location block:

worker_rlimit_nofile 65536;

Validate and reload:

nginx -t
nginx -s reload

If worker_connections exceeds the effective file descriptor limit, new connections will eventually fail at runtime with accept4() failed (24: Too many open files). Verify the running worker limits after startup.

4. Verify the effective limit

Confirm that workers received the intended limit.

master_pid=$(cat /var/run/nginx.pid)
worker_pid=$(pgrep -P "$master_pid" | head -n 1)

# Show soft and hard limits
prlimit -n -p "$worker_pid"

# Compare against current usage
echo "Open FDs: $(ls /proc/$worker_pid/fd 2>/dev/null | wc -l)"
awk '/^Max open files/ {print "Soft:", $4, "Hard:", $5}' /proc/$worker_pid/limits

To check all workers at once:

for pid in $(pgrep -P "$master_pid"); do
  awk '/^Max open files/ {printf "Worker %s: soft=%s hard=%s\n", '"$pid"', $4, $5}' /proc/$pid/limits
done

The soft limit reported by prlimit should match worker_rlimit_nofile unless the inherited hard limit was higher and unprivileged lowering failed. In that case the hard limit remains at the inherited value.

In containerized environments, the runtime may impose its own default. Check the container ulimit or the runtime’s systemd unit. For Docker, pass --ulimit nofile=65535:65535 at launch, or set LimitNOFILE in the container runtime unit. Inside containers, the host-level fs.file-max and fs.nr_open sysctls still cap the ceiling.

Common pitfalls

Assuming limits.conf affects systemd-managed daemons. PAM-based limits.conf applies to login sessions, not to systemd service units. If nginx is managed by systemd, always use a service drop-in.

Setting worker_connections higher than the effective FD limit. If worker_connections is 4096 but the effective FD limit is 1024, the FD limit wins. New connections fail with accept4() failed (24: Too many open files) once descriptors are consumed.

Trusting the configuration file over process reality. The value in nginx.conf can differ from /proc/<pid>/limits. Always verify the running process. Container runtimes and systemd frequently override the configured value.

Forgetting the proxy connection multiplier. Each proxied request uses at least two connections (client-facing and upstream). A server with worker_connections 512 can handle at most roughly 256 concurrent proxied requests before connection exhaustion. Raise worker_rlimit_nofile whenever you raise worker_connections.

Reloading instead of restarting after a systemd change. nginx -s reload re-forks workers from the existing master. Because the master did not re-execute, it retains the old inherited limits. Only a full service restart picks up a new systemd LimitNOFILE value.

Container default limits. Docker, Podman, and containerd often default to a soft limit of 1024. These defaults survive nginx reloads because they are process attributes inherited at exec time. Apply the fix in the container spec or the runtime systemd unit, not inside nginx.

Signals to monitor

How Netdata helps

• Track open files per application group alongside nginx stub_status metrics to spot workers approaching their ceiling before the kernel drops connections.
• Correlate FD usage with active connections and the accepts-handled gap to distinguish connection slot exhaustion from file descriptor exhaustion.
• Alert on TcpExtListenOverflows to catch kernel-level drops that never appear in nginx logs.
• Monitor nginx error log rates for Too many open files alongside connection metrics to confirm the failure layer.

Related guides

• How NGINX actually works in production: a mental model for operators
• NGINX active connections climbing: reading, writing, waiting explained
• NGINX connection exhaustion: detection, diagnosis, and prevention
• NGINX dropped connections: the accepts vs handled gap
• NGINX monitoring checklist: the signals every production server needs
• NGINX monitoring maturity model: from survival to expert
• nginx: worker_connections are not enough - causes and fixes
• NGINX worker_connections and worker_processes: sizing for real traffic