Nginx Proxy Parameters
Introduction
When setting up Nginx as a reverse proxy, configuring the right proxy parameters is essential for performance, reliability, and security. A reverse proxy sits between clients and backend servers, forwarding client requests to appropriate servers and returning the servers' responses to clients. Proxy parameters allow you to control exactly how this forwarding behavior works.
In this guide, we'll explore the most important Nginx proxy parameters, understand their purpose, and learn how to configure them effectively for different scenarios.
Basic Proxy Parameters
Let's start with the fundamental proxy parameters that form the backbone of any Nginx reverse proxy configuration.
proxy_pass
The proxy_pass
directive is the most essential parameter in a proxy configuration. It specifies the protocol and address of a proxied server.
location /api/ {
proxy_pass http://backend_server:8080/;
}
In this example, requests to /api/
will be forwarded to http://backend_server:8080/
.
Understanding URI Handling in proxy_pass
The way Nginx handles URIs depends on whether you include a URI in the proxy_pass
directive:
-
Without a URI - The full original request URI is appended:
nginx# If a request comes in as /api/users
location /api/ {
proxy_pass http://backend_server:8080;
# Request becomes http://backend_server:8080/api/users
} -
With a URI - Nginx replaces the matched location part:
nginx# If a request comes in as /api/users
location /api/ {
proxy_pass http://backend_server:8080/;
# Request becomes http://backend_server:8080/users
}
# If a request comes in as /api/users
location /api/ {
proxy_pass http://backend_server:8080/data/;
# Request becomes http://backend_server:8080/data/users
}
Header Modification Parameters
Controlling HTTP headers is crucial for proper communication between clients, Nginx, and backend servers.
proxy_set_header
This directive allows you to redefine or append fields to the request header passed to the backend server.
location /api/ {
proxy_pass http://backend_server:8080/;
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;
}
Common headers to set:
- Host: Defines which hostname to pass to the backend
- X-Real-IP: Passes the client's actual IP address
- X-Forwarded-For: Maintains a list of IPs in the request chain
- X-Forwarded-Proto: Indicates the protocol (HTTP or HTTPS) used by the client
proxy_pass_request_headers
Controls whether to pass the header fields from the client request to the proxied server.
location /api/ {
proxy_pass http://backend_server:8080/;
proxy_pass_request_headers on; # Default value
}
Request Body Handling
These parameters control how Nginx manages the request body before proxying it.
proxy_pass_request_body
Determines whether the request body is passed to the proxied server.
location /api/ {
proxy_pass http://backend_server:8080/;
proxy_pass_request_body on; # Default value
}
client_max_body_size
Sets the maximum allowed size of the client request body.
location /api/upload/ {
proxy_pass http://backend_server:8080/;
client_max_body_size 10M; # Allows uploads up to 10 megabytes
}
If the size exceeds this value, Nginx returns a 413 (Request Entity Too Large) error.
Timeout Parameters
Timeout parameters are crucial for managing connection behavior and preventing issues with slow clients or backends.
proxy_connect_timeout
Defines the timeout for establishing a connection with the proxied server.
proxy_connect_timeout 60s; # Default is 60 seconds
proxy_send_timeout
Sets the timeout for transmitting a request to the proxied server.
proxy_send_timeout 60s; # Default is 60 seconds
proxy_read_timeout
Defines the timeout for reading a response from the proxied server.
proxy_read_timeout 60s; # Default is 60 seconds
Buffer Parameters
Buffer settings control how Nginx buffers responses from proxied servers.
proxy_buffering
Enables or disables buffering of responses from the proxied server.
location /api/ {
proxy_pass http://backend_server:8080/;
proxy_buffering on; # Default value
}
With buffering enabled, Nginx receives the response from the proxied server as quickly as possible and stores it in internal buffers. This can improve performance when clients are slow.
proxy_buffers
Sets the number and size of buffers for a single connection.
location /api/ {
proxy_pass http://backend_server:8080/;
proxy_buffers 4 16k; # 4 buffers of 16 kilobytes each
}
proxy_buffer_size
Sets the size of the buffer used for reading the first part of the response.
proxy_buffer_size 4k;
SSL Parameters
When proxying to HTTPS backends, these parameters are important.
proxy_ssl_protocols
Specifies the SSL protocols that should be used when connecting to the proxied HTTPS server.
proxy_ssl_protocols TLSv1.2 TLSv1.3;
proxy_ssl_verify
Enables or disables verification of the proxied HTTPS server certificate.
proxy_ssl_verify on;
proxy_ssl_trusted_certificate
Specifies a file with trusted CA certificates for verifying the proxied HTTPS server certificate.
proxy_ssl_trusted_certificate /path/to/trusted_ca_cert.crt;
Caching Parameters
Nginx can cache responses from proxied servers for improved performance.
proxy_cache_path
Defines a cache area on disk:
# In http context
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=10g inactive=60m;
proxy_cache
Enables caching for a specific location:
location /api/ {
proxy_pass http://backend_server:8080/;
proxy_cache my_cache;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
}
Practical Example: Complete Reverse Proxy Configuration
Let's put everything together in a practical example:
http {
# Define upstream servers
upstream backend {
server backend1.example.com:8080;
server backend2.example.com:8080 backup;
}
# Define cache
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=proxy_cache:10m max_size=1g inactive=60m;
# Common proxy headers
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;
# Common timeout settings
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
# Buffer settings
proxy_buffering on;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
server {
listen 80;
server_name example.com;
# API requests
location /api/ {
proxy_pass http://backend/;
proxy_cache proxy_cache;
proxy_cache_valid 200 10m;
client_max_body_size 1M;
}
# Static content
location /static/ {
proxy_pass http://backend/static/;
proxy_cache proxy_cache;
proxy_cache_valid 200 60m;
add_header X-Cache-Status $upstream_cache_status;
}
# Streaming content
location /stream/ {
proxy_pass http://backend/stream/;
proxy_buffering off;
}
# Large file uploads
location /upload/ {
proxy_pass http://backend/upload/;
client_max_body_size 100M;
proxy_request_buffering off;
}
}
}
This configuration:
- Defines an upstream group with a backup server
- Sets up caching for proxied responses
- Configures common proxy headers and timeouts
- Creates separate location blocks for different types of requests
- Adjusts parameters for each use case (API, static content, streaming, uploads)
Understanding Proxy Request Flow with Nginx
Let's visualize how requests flow through Nginx with proxy parameters:
Troubleshooting Common Issues
502 Bad Gateway Errors
This typically indicates that Nginx couldn't connect to the backend server or the backend server closed the connection.
Potential solutions:
- Check if the backend server is running
- Increase
proxy_connect_timeout
- Verify network connectivity between Nginx and backend
Slow Response Times
If your proxy seems slow:
- Adjust buffer settings (
proxy_buffers
,proxy_buffer_size
) - Enable
proxy_buffering
for slow clients - Consider implementing caching with
proxy_cache
Header or Cookie Issues
If applications behind the proxy aren't receiving proper headers:
- Ensure you're setting the correct
proxy_set_header
directives - Check for any header modifications in your backend
Best Practices
- Always set essential headers:
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;
-
Set reasonable timeouts: Too short and valid requests might fail; too long and resources might be wasted on hanging connections.
-
Configure buffer sizes appropriately: Match your typical response sizes to avoid wasting memory.
-
Implement caching when possible: This dramatically improves performance for frequently requested content.
-
Use upstream blocks for load balancing: This provides failover and distribution capabilities.
Summary
Nginx proxy parameters provide powerful tools for controlling how requests and responses are handled in a reverse proxy setup. By understanding and properly configuring these parameters, you can:
- Correctly route requests to backend servers
- Preserve important client information through headers
- Optimize performance with buffering and caching
- Handle different types of content appropriately
- Implement timeouts to protect your servers
- Create robust, high-performance proxy configurations
The flexibility of these parameters allows Nginx to serve as an effective reverse proxy for virtually any web application or service.
Additional Resources
- Official Nginx Proxy Module Documentation
- Nginx Admin Guide
- Digital Ocean's Nginx Configuration Guide
Exercises
- Configure a basic Nginx reverse proxy for a local development server running on port 3000.
- Set up caching for static content with a 1-hour cache duration.
- Create a proxy configuration that handles both HTTP and WebSocket connections.
- Implement a configuration that proxies requests to different backend servers based on the URL path.
- Configure Nginx to proxy requests to a backend HTTPS server with certificate verification.
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)