Mastering Nginx Load Balancing and Reverse Proxy Configuration

Load Balancing Configuration

As a proxy server, Nginx usually forwards requests to an upstream server cluster. Load balancing selects a strategy to distribute requests evenly across the upstream servers.

1.1 upstream block

Syntax: upstream name { ... } Context: http

upstream defines a cluster of upstream servers for use with proxy_pass . Example:

<code>upstream backend {
    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com;
}

server {
    location / {
        proxy_pass http://backend;
    }
}
</code>

1.2 server

Syntax: server name [parameters]; Context: upstream

The server directive specifies an upstream server name, which can be a domain, IP address, port, or UNIX socket, followed by optional parameters such as:

weight=number : sets the request weight (default 1).

max_fails=number together with fail_timeout defines how many failures within the timeout period mark the server as unavailable (default 1, 0 disables checking).

fail_timeout=time : time period after which failures are counted (default 10s).

down : permanently disables the server (used with ip_hash ).

backup : marks the server as a backup, used only when all non‑backup servers fail.

<code>upstream backend {
    server backendl.example.com weight=5;
    server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;
}
</code>

1.3 ip_hash

Syntax: ip_hash; Context: upstream

Ensures that requests from the same client IP are consistently routed to the same upstream server, which is useful for caching scenarios. ip_hash cannot be used together with weight . If a server becomes unavailable, mark it with down instead of removing it.

<code>upstream backend {
    ip_hash;
    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}
</code>

1.4 Variables for logging

Variable

Meaning

$upstream_addr

Address of the upstream server that handled the request

$upstream_cache_status

Cache status (MISS, EXPIRED, UPDATING, STALE, HIT)

$upstream_status

HTTP status code returned by the upstream server

$upstream_response_time

Response time of the upstream server (ms precision)

$upstream_http_$HEADER

Upstream HTTP header, e.g.,

$upstream_http_host

<code>log_format timing '$remote_addr - $remote_user [$time_local] $request '
    'upstream_response_time $upstream_response_time msec $msec request_time $request time';

log_format up_head '$remote_addr - $remote_user [$time_local] $request '
    'upstream_http_content_type $upstream_http_content_type';
</code>

Reverse Proxy Basic Configuration

2.1 proxy_pass

Syntax: proxy_pass URL; Context: location, if

Forwards the current request to the server specified by URL . Examples:

<code>proxy_pass http://localhost:8000/uri/;
proxy_pass http://unix:/path/to/backend.socket:/uri/;

upstream backend { ... }
server {
    location / {
        proxy_pass http://backend;
    }
}

proxy_pass https://192.168.0.1;
</code>

To forward the original Host header, add:

<code>proxy_set_header Host $host;
</code>

2.2 proxy_method

Syntax: proxy_method method;

Changes the HTTP method used when forwarding the request. Example:

<code>proxy_method POST;
</code>

With this setting, a client GET request will be forwarded as POST.

2.3 proxy_hide_header

Syntax: proxy_hide_header the_header; Context: http, server, location

Prevents specified response headers from being passed to the client. Example:

<code>proxy_hide_header Cache-Control;
proxy_hide_header MicrosoftofficeWebServer;
</code>

2.4 proxy_pass_header

Syntax: proxy_pass_header the_header;

Allows previously hidden headers to be forwarded. Example:

<code>proxy_pass_header X-Accel-Redirect;
</code>

2.5 proxy_pass_request_body

Syntax: proxy_pass_request_body on|off; Default: on

Controls whether the request body is sent to the upstream server.

2.6 proxy_pass_request_headers

Syntax: proxy_pass_request_headers on|off; Default: on

Controls whether request headers are forwarded to the upstream server.

2.7 proxy_redirect

Syntax: proxy_redirect [default|off|redirect replacement]; Default: default

Rewrites Location or Refresh headers in redirects from the upstream server. Example:

<code>proxy_redirect http://localhost:8000/two/ http://frontend/one/;
</code>

Using variables:

<code>proxy_redirect http://localhost:8000/ $host:$server_port/;
</code>

Omitting the replacement host keeps the original host:

<code>proxy_redirect http://localhost:8000/two/ /one/;
</code>

Setting off leaves the header unchanged.

2.8 proxy_next_upstream

Syntax: proxy_next_upstream [error|timeout|invalid_header|http_500|http_502|http_503|http_504|http_404|off]; Default: error timeout

Specifies conditions under which Nginx will retry the request with the next upstream server. Options include connection errors, timeouts, invalid headers, and specific HTTP status codes.

Nginx also provides many other reverse‑proxy settings such as connection timeouts, temporary file handling, and response caching.