Implementing Reverse Proxy

1. Configuring Proxy Pass

Directive	Values	Description
proxy_pass	`http://backend_server`	Specifies the address of the proxied server
proxy_pass	`http://unix:/path/to/socket`	Specifies a Unix domain socket for proxying

Example: Basic proxy_pass configuration

location /api/ {
    proxy_pass http://backend_server;
}

Example: Proxying to Unix socket

location /socket/ {
    proxy_pass http://unix:/var/run/app.sock;
}

Note: When using proxy_pass, the URI part of the directive is optional. If omitted, the original request URI is passed to the proxied server.

2. Setting Proxy Headers

Header	Value	Description
proxy_set_header	`Host $host`	Sets the Host header to the original request's host
proxy_set_header	`X-Real-IP $remote_addr`	Passes the client's real IP address to the backend server
proxy_set_header	`X-Forwarded-For $proxy_add_x_forwarded_for`	Appends the client's IP to the X-Forwarded-For header
proxy_set_header	`X-Forwarded-Proto $scheme`	Indicates the original protocol (http or https) used by the client
proxy_set_header	`Forwarded "for=$remote_addr;proto=$scheme"`	Standardized Forwarded header for proxy information

Example: Configuring Proxy Headers

location /api/ {
    proxy_pass http://backend;
    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;
}

3. Forwarding Client IP

Directive	Values	Description
proxy_set_header	`X-Real-IP $remote_addr;`	Sets the X-Real-IP header to the client's real IP address
proxy_set_header	`X-Forwarded-For $proxy_add_x_forwarded_for;`	Appends the client's IP to the X-Forwarded-For header
proxy_set_header	`X-Forwarded-Proto $scheme;`	Forwards the protocol (http/https) used by the client

Example: Configuring IP forwarding

location / {
    proxy_pass http://backend;
    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;
}

Note: The X-Forwarded-For header is a de facto standard for identifying the originating IP address of a client connecting to a web server through an HTTP proxy or load balancer.

4. Preserving Host Header

Directive	Description	Default	Example
proxy_set_header	Sets a header to be passed to the proxied server	Host: $proxy_host	`proxy_set_header Host $host;`
proxy_pass	Specifies the address of the proxied server	None	`proxy_pass http://backend;`

Example: Setting Host Header

location /api/ {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Note: The $host variable includes the host name and port if necessary, ensuring that the original request's host is preserved in the proxied request.

5. Configuring Proxy Buffering

Directive	Values	Description
proxy_buffering	`on` \| `off`	Enables or disables buffering of responses from the proxied server. Default is `on`.
proxy_buffer_size	`size`	Size of the buffer used for reading the first part of the response from the proxied server. Default is `4k` or `8k`.
proxy_buffers	`number` `size`	Number and size of buffers used for reading the response from the proxied server. Default is `8 4k` or `8 8k`.
proxy_busy_buffers_size	`size`	Maximum size of buffers that can be marked as busy. Default is `2*proxy_buffer_size`.
proxy_buffering	`on` \| `off`	Enables or disables buffering of responses from the proxied server. Default is `on`.

Example: Enabling proxy buffering

location /api/ {
    proxy_pass http://backend;
    proxy_buffering on;
    proxy_buffer_size 1k;
    proxy_buffers 8 2k;
    proxy_busy_buffers_size 4k;
}

Note: Buffering improves performance by reducing the number of write operations to the client. It is recommended for large responses or when dealing with slow clients.

6. Setting Proxy Timeouts

Directive	Values	Description
proxy_connect_timeout	`60s`	Timeout for connecting to the proxied server
proxy_send_timeout	`60s`	Timeout for sending a request to the proxied server
proxy_read_timeout	`60s`	Timeout for reading a response from the proxied server
proxy_buffering	`on` \| `off`	Enables or disables buffering of responses from the proxied server

Example: Configuring Proxy Timeouts

location /api/ {
    proxy_pass http://backend;
    proxy_connect_timeout 10s;
    proxy_send_timeout 15s;
    proxy_read_timeout 30s;
}

7. Handling Proxy Redirects

Directive	Description	Default	Notes
proxy_redirect	Modifies the `Location` and `Refresh` headers from the proxied server	off	Useful for correcting URLs when proxying to a different server or path

Example: Basic proxy_redirect usage

location /api/ {
    proxy_pass http://backend-server/api/;
    proxy_redirect /api/ /rest/;
}

Example: Using proxy_redirect with regex

location /app/ {
    proxy_pass http://backend-server/app/;
    proxy_redirect ~^/app/(.*) /rest/$1;
}

Note: proxy_redirect only affects the headers sent by the proxied server, not the content of the response body.

8. Configuring WebSocket Proxying

Directive	Description	Default	Notes
proxy_pass	Specifies the address of the proxied server	-	Required for WebSocket connections
proxy_http_version	Sets the HTTP version for proxy requests	1.1	Must be 1.1 for WebSocket support
proxy_set_header	Sets custom headers for the proxied request	-	Used to set Upgrade and Connection headers

Example: Basic WebSocket Configuration

location /websocket/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Note: The proxy_set_header directives are essential for WebSocket protocol upgrade.

9. Using Upstream Variables

Variable	Description	Example Value
upstream_addr	Address of the upstream server	`192.168.1.10:80`
upstream_status	Status code returned by the upstream server	`200`
upstream_response_time	Time taken to get response from upstream server	`0.045s`
upstream_connect_time	Time taken to connect to upstream server	`0.002s`

Example: Using upstream variables in logs

log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_addr" "$upstream_status" "$upstream_response_time"';

access_log /var/log/nginx/access.log custom;

Note: The upstream_ variables are only available in the access_log context and when using an upstream block.

10. Setting Proxy SSL

Directive	Description	Values	Notes
proxy_ssl	Enables or disables SSL/TLS for proxy connections	`on` \| `off`	Default: `off`
proxy_ssl_verify	Enables or disables verification of the SSL certificate	`on` \| `off`	Default: `off`
proxy_ssl_verify_depth	Specifies the maximum verification depth in the certificate chain	`number`	Default: `1`
proxy_ssl_trusted_certificate	Specifies a file with trusted CA certificates for verification	`file_path`	Used with `proxy_ssl_verify`
proxy_ssl_certificate	Specifies a file with the client certificate to use for proxy connections	`file_path`	Optional, for mutual TLS
proxy_ssl_certificate_key	Specifies a file with the private key for the client certificate	`file_path`	Required if `proxy_ssl_certificate` is set

Example: Basic SSL proxy configuration

location /api/ {
    proxy_pass https://backend-server.com/;
    proxy_ssl on;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
}

Example: Mutual TLS proxy configuration

location /secure/ {
    proxy_pass https://backend-server.com/;
    proxy_ssl on;
    proxy_ssl_verify on;
    proxy_ssl_verify_depth 2;
    proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    proxy_ssl_certificate /etc/ssl/client.crt;
    proxy_ssl_certificate_key /etc/ssl/client.key;
}

11. Configuring Proxy Cache Key

Directive	Values	Description
proxy_cache_key	`$scheme$proxy_add_x_forwarded_for$request_uri`	Defines the key for caching, default is scheme + X-Forwarded-For + request URI

Example: Custom Cache Key

location /api/ {
    proxy_cache my_cache;
    proxy_cache_key $scheme$proxy_add_x_forwarded_for$request_uri$user_agent;
}

Note: The proxy_cache_key directive allows fine-grained control over how Nginx identifies cached responses, which is crucial for avoiding cache collisions when serving content based on user-specific or dynamic request parameters.

12. Understanding Proxy Buffer Sizes

Directive	Values	Description
proxy_buffering	`on` \| `off`	Enables or disables buffering of responses from the proxied server.
proxy_buffer_size	`size`	Size of the buffer used for reading the first part of the response from the proxied server.
proxy_buffers	`number size`	Configures the number and size of buffers used for reading a response from the proxied server.
proxy_busy_buffers_size	`size`	Maximum size of buffers that can be marked as “busy” while still being sent to the client.

Example: Configuring proxy buffering

location /api/ {
    proxy_pass http://backend;
    proxy_buffering on;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
}

Note: Buffering is enabled by default. Adjust buffer sizes based on response size and expected traffic to optimize performance.