Nginx Reverse Proxy Configuration: Headers, Timeouts, WebSocket

Wrong client IPs, redirects dropping to HTTP, broken WebSockets and 502/504s in an Nginx reverse proxy: headers, timeouts, buffers, keepalive and a diagnosis order.
Technical summary
Technology
Nginx, ngx_http_proxy_module, ngx_http_realip_module, WebSocket, PHP-FPM, Docker
Topic
Publishing applications correctly behind Nginx
Level
Intermediate–advanced
Prerequisites
  • Nginx installed on a Linux server, and basic knowledge of server blocks
  • The address and port the back-end application listens on
  • Permission to test and reload the configuration
In this article8 sections

You’ve put the application behind Nginx and the site opens. A few days later, all visitors in the logs come from 127.0.0.1, the payment return redirects to HTTP, the WebSocket connection drops at exactly the 60th second, and 502s appear at peak hours. Almost all of these are the result of a reverse proxy left with default values. Putting Nginx in front of a Node.js, Python, Java or containerized application brings TLS termination, compression, static files and access control together at a single point; but every directive at that point must be written deliberately. Below we unpack the skeleton used in production directive by directive and give the order to follow in the console when diagnosing 502/504s.

What a reverse proxy does

The client talks only to the reverse proxy; it doesn’t see the application servers behind it. In corporate web infrastructure, Nginx takes on these jobs in this role:

  • TLS termination: Certificate and protocol settings are managed independently of the application.
  • Connection buffering: Prevents slow clients from tying up application workers; the response is passed quickly to Nginx, and Nginx sends it to the client.
  • Routing: On the same domain, /api/ can go to one service and / to another.
  • Load distribution and health: Distribution across several back ends and temporarily taking a faulty server out of rotation.
  • Policy point: Request size limits, rate limits, IP restrictions, security headers.

Each of these jobs is a separate point of failure. Choosing a web server is a separate decision; we discussed it in the Nginx, Apache and IIS comparison article. From here on, it’s about Nginx.

Basic proxy configuration

The skeleton below publishes an application listening on 127.0.0.1:3000. Define the back end in an upstream block from the start; adding a second server and enabling keepalive later becomes a one-line job.

upstream app_backend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

server {
    listen 443 ssl;
    http2 on;
    server_name app.example.com;
    # ssl_certificate and ssl_certificate_key lines go here

    client_max_body_size 20m;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        include /etc/nginx/snippets/proxy-headers.conf;
    }
}

The http2 on; directive came with Nginx 1.25.1; older versions use the listen 443 ssl http2; syntax. client_max_body_size is 1 MB by default. After moving an application that uploads files behind Nginx, this is usually the first complaint: 413 Request Entity Too Large. Match the value to the application’s own upload limit.

proxy_pass and the trailing slash rule

The prime suspect for unexplained 404s after a migration is the URI part at the end of the proxy_pass value:

Configuration Request Path sent to the back end
location /api/ { proxy_pass http://app; } /api/users /api/users
location /api/ { proxy_pass http://app/; } /api/users /users
location /api/ { proxy_pass http://app/v2/; } /api/users /v2/users

The rule is: if proxy_pass contains a URI (even a single /), the prefix matched by the location is replaced with that URI. In locations defined with a regex, a proxy_pass containing a URI can’t be used (nginx -t returns an error); and when the URI is changed with rewrite … break, the URI in proxy_pass is ignored and the rewritten path is passed. In these cases, using a URI-less proxy_pass and rewriting the path explicitly is more predictable. One character, completely different behavior.

Client IP and protocol headers

The application receives the TCP connection from Nginx. It can only learn the client’s IP, the protocol used and the requested domain from headers. Instead of writing these headers separately in every server block, collect them in a single snippet file:

# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host              $host;
proxy_set_header X-Real-IP         $remote_addr;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host  $host;

By default, Nginx sends the back end the name in proxy_pass ($proxy_host) in the Host header; that’s why multi-tenant applications and frameworks that generate absolute URLs redirect the user to an address such as app_backend. When X-Forwarded-Proto is missing, the application thinks the request is HTTP; it doesn’t mark the session cookie Secure, or it enters an infinite HTTPS redirect loop.

The real trap is in the inheritance rule: if you define a single proxy_set_header inside a location, all proxy_set_header definitions in the parent block become invalid for that location. nginx -t doesn’t catch this, because the configuration is valid. Including the snippet in every location with include removes the trap. On the application side, explicitly configure trust in the proxy too (trust proxy in Express, SECURE_PROXY_SSL_HEADER in Django, the TrustProxies middleware in Laravel); otherwise the headers are ignored.

Real IP behind Cloudflare or another proxy

If there’s Cloudflare, a load balancer or a WAF in front of Nginx, $remote_addr is that device’s address. With ngx_http_realip_module, the header is trusted only from sources you trust:

# In the http block; take the full set of ranges from https://www.cloudflare.com/ips/
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 2400:cb00::/32;
# ... the other IPv4 and IPv6 ranges in the list
real_ip_header CF-Connecting-IP;

If your own load balancer is in front, real_ip_header X-Forwarded-For; and real_ip_recursive on; are used; in that case the addresses of all trusted intermediate proxies must be defined with set_real_ip_from. Writing set_real_ip_from 0.0.0.0/0 lets anyone spoof their IP by sending the header; this line, written “to make it work”, is often found in the field, and from then on rate limits and IP restrictions lose their meaning. Cloudflare’s IP list can change. Set up a task that updates this file periodically. For how Cloudflare and the cache layer work together, see the Cloudflare, WP Rocket and Redis guide.

Timeout and buffer settings

Nginx has three proxy timeouts, and none of them measures total request time; each applies to the gap between two operations:

Directive Default What it measures
proxy_connect_timeout 60s Time to establish a TCP connection with the back end (usually can’t exceed 75 seconds)
proxy_send_timeout 60s Between two write operations to the back end
proxy_read_timeout 60s Between two read operations from the back end

The rule is simple: keep the connect timeout short (a few seconds is enough for a service on the same server), and extend the read timeout per location only for long-running endpoints. Defining 300 seconds for an /export/ path that generates reports is safer than giving the whole site 300 seconds; otherwise stuck requests hold worker connections for a long time. The lasting solution is in the architecture: queue the long job and let the client poll for its status. Raising the timeout isn’t a cure.

On the buffer side, the default proxy_buffering on is right in most scenarios. There are three points you need to touch by hand:

  • proxy_buffer_size: Used for the header part of the response (one memory page by default, 4k or 8k). In applications carrying large cookies or JWTs, upstream sent too big header appears in the logs and the client gets a 502; raising it to 16k–32k is usually enough.
  • proxy_buffers and proxy_busy_buffers_size: Body buffers. If memory isn’t enough, the response is written to a temporary file; the an upstream response is buffered to a temporary file warning in the log shows this.
  • For Server-Sent Events or streaming endpoints, define proxy_buffering off; for that location, or have the application send an X-Accel-Buffering: no header.

WebSocket and upstream keepalive

WebSocket starts with the HTTP/1.1 Upgrade mechanism. Upgrade and Connection are hop-by-hop headers; Nginx doesn’t pass them to the back end on its own. If you don’t pass them, the handshake never completes. The structure recommended in nginx.org’s WebSocket proxying documentation:

# In the http block
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# In the server block
location /ws/ {
    proxy_pass http://app_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    include /etc/nginx/snippets/proxy-headers.conf;
    proxy_read_timeout 1h;
}

This location has $connection_upgrade instead of Connection ""; mixing the two up silently breaks WebSocket. For normal HTTP requests, upstream keepalive comes into play: keepalive 32; is the upper limit on idle connections each worker process keeps open to the back end. For it to work, proxy_http_version 1.1 and an empty Connection header are needed; by default Nginx speaks HTTP/1.0 with the back end and opens a new connection for every request. Under heavy traffic without keepalive, many TIME_WAIT sockets pile up on the server and ephemeral port exhaustion can occur. If the timewait count in the ss -s output is in the thousands, this is the first place to look.

In container-based deployment with Docker, if the back end is defined by a service name, Nginx resolves that name only when the configuration is loaded; if the container is recreated and its IP changes, Nginx keeps going to the old address. This is the classic cause of the “the container restarted and the site is returning 502” complaint. Either reload Nginx when the back end changes, or use a variable-based proxy_pass with resolver 127.0.0.11 valid=10s;. Production settings for a container stack are explained in detail in the Docker Compose production deployment guide.

Diagnosing 502 and 504 errors

The two error codes say different things: 502 Bad Gateway means Nginx couldn’t get a valid response from the back end; 504 Gateway Timeout means the response didn’t arrive within the timeout. The error page in the browser tells you nothing. Diagnosis starts with error.log.

error.log message Code Likely cause and check
connect() failed (111: Connection refused) 502 The application isn’t running or is listening on a different port/address; verify with ss -ltnp
connect() to unix:… failed (13: Permission denied) 502 Socket file permissions or SELinux; listen.owner/listen.group in the PHP-FPM pool
connect() failed (13: Permission denied), TCP 502 SELinux on the RHEL family; setsebool -P httpd_can_network_connect 1
upstream prematurely closed connection 502 The application crashed mid-operation or hit its memory limit; application logs
upstream sent too big header 502 proxy_buffer_size or fastcgi_buffer_size is insufficient
no live upstreams 502 All servers are temporarily disabled because of max_fails
upstream timed out (110: Connection timed out) while reading response header 504 A slow query or a lock; increasing proxy_read_timeout only hides the symptom

The order to follow in the console:

  1. Verify that the configuration is valid with nginx -t; nginx -T dumps the merged configuration and shows that the expected file is really loaded.
  2. Try the back end from the server itself, bypassing Nginx: curl -sv -H "Host: app.example.com" http://127.0.0.1:3000/. If there’s an error here too, the problem isn’t in the proxy.
  3. Add $upstream_addr, $upstream_status, $upstream_response_time and $request_time to the access log. The difference between the two durations shows whether time is being spent on the Nginx–client side or in the application.
  4. Look at 499 codes: the client closed the connection without waiting for the response; usually the timeout of the CDN or load balancer in front of you is shorter than Nginx’s.
  5. Align the timeout chain: values decreasing from outside in, as CDN > Nginx > application server > database query limit, make the error occur at the layer closest to its source and with a meaningful message.

By default, proxy_next_upstream retries the request on the next server in error timeout cases; since Nginx 1.9.13, non-idempotent requests such as POST aren’t retried after being sent to the back end. Extending this behavior with non_idempotent brings the risk of duplicate records on endpoints that create payments or orders. Leave the default.

On sites using PHP-FPM, the same diagnosis logic works through equivalents such as fastcgi_pass and fastcgi_read_timeout; for 502/504s caused by pool exhaustion, the PHP-FPM and MariaDB performance guide applies directly. The official definitions of all directives are in the ngx_http_proxy_module documentation.

Checklist before going live

  • Host, X-Forwarded-For and X-Forwarded-Proto are passed in every location; the application is configured to trust the proxy.
  • If there’s a CDN or load balancer in front, realip trusts only their ranges.
  • client_max_body_size matches the application’s upload limit.
  • Timeouts are set per location and decrease from the outer layer inwards.
  • WebSocket paths pass the Upgrade/Connection headers, and the read timeout is longer than the application’s ping interval.
  • Upstream keepalive is defined together with proxy_http_version 1.1.
  • Upstream times and status codes are recorded in the access log.

TLS protocol and cipher settings are a separate topic; for those, go to the TLS configuration on a web server guide. In setups that bring many applications together behind the same Nginx, the real work is the configuration standard and monitoring; we build this setup as part of our Nginx web server and reverse proxy service.

Frequently asked questions

What does the trailing slash at the end of the proxy_pass address change?

If proxy_pass contains a URI part (for example an address ending in http://app/), the prefix matched by the location is replaced with that URI; a /api/users request goes to the back end as /users. If there’s no URI (http://app), the path is passed as is. This difference is a common cause of unexpected 404s after a migration.

My WebSocket connections drop at exactly 60 seconds. Why?

proxy_read_timeout is 60 seconds by default and applies to the gap between two reads. If the application sends no data during that time, Nginx closes the connection. Extend the timeout for the relevant location, or use periodic ping/pong in the application; the latter also works with other proxies and load balancers in between.

Why do the logs always show Cloudflare IPs behind Cloudflare?

Because Nginx receives the connection from Cloudflare’s edge server, $remote_addr shows that address. When you add the IP ranges Cloudflare publishes to set_real_ip_from lines with the realip module and define real_ip_header CF-Connecting-IP, logs, rate limits and access rules work with the real client IP.

Should proxy_pass also be used for PHP-FPM?

No. PHP-FPM speaks FastCGI; in Nginx you connect with fastcgi_pass, and the fastcgi_-prefixed equivalents of settings such as timeouts and buffers are used. The timeout, buffer and diagnosis logic above applies just the same; client information is passed with fastcgi_param instead of proxy_set_header.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles