Nginx proxy module

Exclusive offer: get 50% off this eBook here
Nginx HTTP Server - Second Edition

Nginx HTTP Server - Second Edition — Save 50%

Make the most of your infrastructure and serve pages faster than ever with Nginx with this book and ebook

$26.99    $13.50
by Clément Nedelcu | September 2013 |

In this article created by Clément Nedelcu, the author of Nginx HTTP Server - Second Edition,we will discover the proxy module of Nginx.

(For more resources related to this topic, see here.)

The first step towards establishing the new architecture will be to discover the appropriate module. The default Nginx build comes with the proxy module, which allows forwarding of HTTP requests from the client to a backend server. We will be configuring multiple aspects of the module:

  • Basic address and port information on the backend server
  • Caching, buffering, and temporary file options
  • Limits, timeout, and error behavior
  • Other miscellaneous options

All these options are available via directives which we will learn to configure throughout this section.

Main directives

The first set of directives will allow you to establish basic configuration such as the location of the backend server, information to be passed, and how it should be passed.

Directive

Description

proxy_pass

Context: location, if

Specifies that the request should be forwarded to the backend server by indicating its location:

For TCP sockets, the syntax is proxy_pass http://hostname:port;

For Unix domain sockets, the syntax is: proxy_pass http://unix:/path/to/file.socket;

You may also refer to upstream blocks: proxy_pass http://myblock;

Instead of http://, you can use https:// for secure traffic. Additional URI parts as well as the use of variables are allowed.

Examples:

proxy_pass http://localhost:8080;

proxy_pass http://127.0.0.1:8080;

proxy_pass http://unix:/tmp/nginx.sock;

proxy_pass https://192.168.0.1;

proxy_pass http://localhost:8080/uri/;

proxy_pass http://unix:/tmp/nginx.sock:/uri/;

proxy_pass http://$server_name:8080;

# Using an upstream block

upstream backend {

    server 127.0.0.1:8080;

    server 127.0.0.1:8081;

}

location ~* \.php$

{

    proxy_pass http://backend;

}

proxy_method

Context: http, server, location

Allows overriding the HTTP method of the request to be forwarded to the backend server. If you specify POST, for example, all requests forwarded to the backend server will be POST requests.

Syntax: proxy_method method;

Example: proxy_method POST;

proxy_hide_header

Context: http, server, location

By default, as Nginx prepares the response received from the backend server to be forwarded back to the client, it ignores some of the headers such as Date, Server, X-Pad, and X-Accel-*. With this directive, you can specify an additional header line to be hidden from the client. You may insert this directive multiple times with one header name for each.

Syntax: proxy_hide_header header_name;

Example: proxy_hide_header Cache-Control;

proxy_pass_header

Context: http, server, location

Related to the above directive, this directive forces some of the ignored headers to be passed on to the client.

Syntax: proxy_pass_header headername;

Example: proxy_pass_header Date;

proxy_pass_request_body

proxy_pass_request_headers

Context: http, server, location

Defines whether or not, respectively, the request body and extra request headers should be passed on to the backend server.

Syntax: on or off;

Default: on

proxy_redirect

Context: http, server, location

Allows you to rewrite the URL appearing in the Location HTTP header on redirections triggered by the backend server.

Syntax: off, default, or the URL of your choice

off: Redirections are forwarded as it is.

default: The value of the proxy_pass directive is used as the hostname and the current path of the document is appended. Note that the proxy_redirect directive must be inserted after the proxy_pass directive as the configuration is parsed sequentially.

URL: Replace a part of the URL by another.

Additionally, you may use variables in the rewritten URL.

Examples:

proxy_redirect off;

proxy_redirect default;

proxy_redirect http://localhost:8080/ http://example.com/;

proxy_redirect http://localhost:8080/wiki/ /w/;

proxy_redirect http://localhost:8080/ http://$host/;

proxy_next_upstream

Context: http, server, location

When proxy_pass is connected to an upstream block, this directive defines the cases where requests should be abandoned and resent to the next upstream server of the block. The directive accepts a combination of values among the following:

error: An error occurred while communicating or attempting to communicate with the server

timeout: A timeout occurs during transfers or connection attempts

invalid_header: The backend server returned an empty or invalid response

http_500, http_502, http_503, http_504, http_404: In case such HTTP errors occur, Nginx switches to the next upstream

off: Forbids from using the next upstream server

Examples:

proxy_next_upstream error timeout http_504;

proxy_next_upstream timeout invalid_header;

Caching, buffering, and temporary files

Ideally, as much as possible, you should reduce the amount of requests being forwarded to the backend server. The following directive will help you build a caching system, as well as control buffering options and the way Nginx handles temporary files:

Directive

Description

proxy_buffer_size

Context: http, server, location

Sets the size of the buffer for reading the beginning of the response from the backend server, which usually contains simple header data.

The default value corresponds to the size of 1 buffer, as defined by the directive above (proxy_buffers).

Syntax: Numeric value (size)

Example:

proxy_buffer_size 4k;

proxy_buffering

Context: http, server, location

Defines whether or not the response from the backend server should be buffered. If set to on, Nginx will store the response data in memory using the memory space offered by the buffers. If the buffers are full, the response data will be stored as a temporary file. If the directive is set to off, the response is directly forwarded to the client.

Syntax: on or off

Default: on

proxy_buffers

Context: http, server, location

Sets the amount and size of buffers that will be used for reading the response data from the backend server.

Syntax: proxy_buffers amount size;

Default: 8 buffers, 4 k or 8 k each depending on platform

Example: fastcgi_buffers 8 4k;

proxy_busy_buffers_size

Context: http, server, location

When the backend-received data accumulated in buffers exceeds the specified value, buffers are flushed and data is sent to the client.

Syntax: Numeric value (size)

Default: 2 * proxy_buffer_size

proxy_cache

Context: http, server, location

Defines a cache zone. The identifier given to the zone is to be reused in further directives.

Syntax: proxy_cache zonename;

Example: proxy_cache cache1;

proxy_cache_key

Context: http, server, location

This directive defines the cache key, in other words, it differentiates one cache entry from another. If the cache key is set to $uri, as a result, all requests with this $uri will work as a single cache entry. But that's not enough for most dynamic websites - you also need to include the query string arguments in the cache key, so that /index.php and /index.php?page=contact do not point to the same cache entry.

Syntax: proxy_cache_key key;

Example: proxy_cache_key "$scheme$host$request_uri $cookie_user";

proxy_cache_path

Context: http

Indicates the directory for storing cached files, as well as other parameters.

Syntax: proxy_cache_path path [levels=numbers keys_zone=name:size inactive=time max_size=size];

The additional parameters are:

levels: Indicates the depth level of subdirectories (usually 1:2 is enough)

keys_zone: Lets you make use of the zone you previously declared with the proxy_cache directive and indicates the size to occupy in memory

inactive: If a cached response is not used within the specified time frame, it is removed from the cache

max_size: Defines the maximum size of the entire cache

Example: proxy_cache_path /tmp/nginx_cache levels=1:2 zone=zone1:10m inactive=10m max_size=200M;

proxy_cache_methods

Context: http, server, location

Defines the HTTP methods eligible for caching. GET and HEAD are included by default and cannot be disabled.

Syntax: proxy_cache_methods METHOD;

Example: proxy_cache_methods OPTIONS;

proxy_cache_min_uses

Context: http, server, location

Defines the minimum amount of hits before a request is eligible for caching. By default, the response of a request is cached after one hit (next requests with the same cache key will receive the cached response).

Syntax: Numeric value

Example: proxy_cache_min_uses 1;

proxy_cache_valid

Context: http, server, location

This directive allows you to customize the caching time for different kinds of response codes. You may cache responses associated with 404 error codes for 1 minute, and on the opposite cache, 200 OK responses for 10 minutes or more. This directive can be inserted more than once:

proxy_cache_valid 404 1m;

proxy_cache_valid 500 502 504 5m;

proxy_cache_valid 200 10;

Syntax: proxy_cache_valid code1 [code2...] time;

proxy_cache_use_stale

Context: http, server, location

Defines whether or not Nginx should serve stale cached data in certain circumstances (in regard to the gateway). If you use proxy_cache_use_stale timeout, and if the gateway times out, then Nginx will serve cached data.

Syntax: proxy_cache_use_stale [updating] [error] [timeout] [invalid_header] [http_500];

Example: proxy_cache_use_stale error timeout;

proxy_max_temp_file_size

Context: http, server, location

Set this directive to 0 to disable the use of temporary files for requests eligible to proxy forwarding or specify a maximum file size.

Syntax: Size value

Default value: 1 GB

Example: proxy_max_temp_file_size 5m;

proxy_temp_file_write_size

Context: http, server, location

Sets the write buffer size when saving temporary files to the storage device

Syntax: Size value

Default value: 2 * proxy_buffer_size

proxy_temp_path

Context: http, server, location

 

Sets the path of temporary and cache store files.

Syntax: proxy_temp_path path [level1 [level2...]]

Examples:

proxy_temp_path /tmp/nginx_proxy;

proxy_temp_path /tmp/cache 1 2;

Limits, timeouts, and errors

The following directives will help you define timeout behavior, as well as various limitations regarding communications with the backend server:

Directive

Description

proxy_connect_timeout

Context: http, server, location

Defines the backend server connection timeout. This is different from the read/send timeout; if Nginx is already connected to the backend server, the proxy_connect_timeout is not applicable.

Syntax: Time value (in seconds)

Example: proxy_connect_timeout 15;

proxy_read_timeout

Context: http, server, location

The timeout for reading data from the backend server. This timeout isn't applied to the entire response delay but between two read operations instead.

Syntax: Time value (in seconds)

Default value: 60

Example: proxy_read_timeout 60;

proxy_send_timeout

Context: http, server, location

This timeout is for sending data to the backend server. The timeout isn't applied to the entire response delay but between two write operations instead.

Syntax: Time value (in seconds)

Default value: 60

Example: proxy_send_timeout 60;

proxy_ignore_client_abort

Context: http, server, location

If set to on, Nginx will continue processing the proxy request, even if the client aborts its request. In the other case (off), when the client aborts its request, Nginx also aborts its request to the backend server.

Default value: off

proxy_intercept_errors

Context: http, server, location

By default, Nginx returns all error pages (HTTP status code 400 and higher) sent by the backend server directly to the client. If you set this directive to on, the error code is parsed and can be matched against the values specified in the error_page directive.

Default value: off

proxy_send_lowat

Context: http, server, location

An option allowing you to make use of the SO_SNDLOWAT flag for TCP sockets under BSD-based operating systems only. This value defines the minimum number of bytes in the buffer for output operations.

Syntax: Numeric value (size)

Default value: 0

Other directives

Finally, the last set of directives available in the proxy module is uncategorized and is as follows:

Directive

Description

proxy_headers_hash_max_size

Context: http, server, location

Sets the maximum size for the proxy headers hash tables.

Syntax: Numeric value

Default value: 512

proxy_headers_hash_bucket_size

Context: http, server, location

Sets the bucket size for the proxy headers hash tables.

Syntax: Numeric value

Default value: 64

proxy_ignore_headers

Context: http, server, location

Prevents Nginx from processing one of the following four headers from the backend server response:

X-Accel-Redirect, X-Accel-Expires, Expires, and Cache-Control.

Syntax: proxy_ignore_headers header1 [header2...];

proxy_set_body

Context: http, server, location

Allows you to set a static request body for debugging purposes. Variables may be used in the directive value.

Syntax: String value (any value)

Example: proxy_set_body test;

proxy_set_header

Context: http, server, location

This directive allows you to redefine header values to be transferred to the backend server. It can be declared multiple times.

Syntax: proxy_set_header Header Value;

Example: proxy_set_header Host $host;

proxy_store

Context: http, server, location

Specifies whether or not the backend server response should be stored as a file. Stored response files can be reused for serving other requests.

Possible values: on, off, or a path relative to the document root (or alias). You may also set this to on and define the proxy_temp_path directive.

Examples:

proxy_store on;

proxy_temp_path /temp/store;

proxy_store_access

Context: http, server, location

This directive defines file access permissions for the stored response files.

Syntax: proxy_store_access [user:[r|w|rw]] [group:[r|w|rw]] [all:[r|w|rw]];

Example: proxy_store_access user:rw group:rw all:r;

proxy_http_version

Context: http, server, location

Sets the HTTP version to be used for communicating with the proxy backend. HTTP 1.0 is the default value, but if you are going to enable keepalive connections, you might want to set this directive to 1.1.

Syntax: proxy_http_version 1.0 | 1.1;

proxy_cookie_domain

proxy_cookie_path

Context: http, server, location

Applies an on-the-fly modification to the domain or path attributes of a cookie (case insensitive).

Syntaxes: proxy_cookie_domain off | domain replacement;

proxy_cookie_path off | domain replacement ;

Variables

The proxy module offers several variables that can be inserted in various locations, for example, in the proxy_set_header directive or in the logging-related directives such as log_format. The available variables are:

  • $proxy_host: Contains the hostname of the backend server used for the current request.
  • $proxy_port: Contains the port of the backend server used for the current request.
  • $proxy_add_x_forwarded_for: This variable contains the value of the X-Forwarded-For request header, followed by the remote address of the client. Both values are separated by a comma. If the X-Forwarded-For request header is unavailable, the variable only contains the client remote address.
  • $proxy_internal_body_length: Length of the request body (set with the proxy_set_body directive or 0).

Summary

In this article, we learned to discover an appropriate module before establishing a new connection. We configured multiple aspects of the module.

Resources for Article :


Further resources on this subject:


Nginx HTTP Server - Second Edition Make the most of your infrastructure and serve pages faster than ever with Nginx with this book and ebook
Published: July 2013
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

About the Author :


Clément Nedelcu

Clément Nedelcu was born in France and studied in UK, French, and Chinese universities. After teaching computer science and programming in several eastern Chinese universities, he worked as a Technology Consultant in France, specializing in web and Microsoft .NET programming as well as Linux server administration. Since 2005, he has also been administering a major network of websites in his spare time. This eventually led him to discover Nginx: it made such a difference that he started his own blog about it. One thing leading to another…

Books From Packt


Mastering Nginx
Mastering Nginx

Instant Nginx Starter [Instant]
Instant Nginx Starter [Instant]

Nginx HTTP Server
Nginx HTTP Server

 Nginx 1 Web Server Implementation Cookbook
Nginx 1 Web Server Implementation Cookbook

Squid Proxy Server 3.1: Beginner's Guide
Squid Proxy Server 3.1: Beginner's Guide

Ext JS 4 First Look
Ext JS 4 First Look

JBoss ESB Beginner’s Guide
JBoss ESB Beginner’s Guide

OpenStack Cloud Computing Cookbook
OpenStack Cloud Computing Cookbook


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software