tech 

NGINX Reverse Proxy

TE 0 Comments

Configure NGINX as a reverse proxy for HTTP and other protocols, with support for modifying request headers and fine-tuned buffering of responses.

This article describes the basic configuration of a proxy server. You will learn how to pass a request from NGINX to proxied servers over different protocols, modify client request headers that are sent to the proxied server, and configure buffering of responses coming from the proxied servers.

Introduction

Proxying is typically used to distribute the load among several servers, seamlessly show content from different websites, or pass requests for processing to application servers over protocols other than HTTP.

Passing a Request to a Proxied Server

When NGINX proxies a request, it sends the request to a specified proxied server, fetches the response, and sends it back to the client. It is possible to proxy requests to an HTTP server (another NGINX server or any other server) or a non-HTTP server (which can run an application developed with a specific framework, such as PHP or Python) using a specified protocol. Supported protocols include FastCGI , uwsgi , SCGI , and memcached .

To pass a request to an HTTP proxied server, the proxy_pass directive is specified inside a location . For example:

location /some/path/ {
    proxy_pass http://www.example.com/link/;
}

This example configuration results in passing all requests processed in this location to the proxied server at the specified address. This address can be specified as a domain name or an IP address. The address may also include a port:

location ~ \.php {
    proxy_pass http://127.0.0.1:8000;
}

Note that in the first example above, the address of the proxied server is followed by a URI, /link/. If the URI is specified along with the address, it replaces the part of the request URI that matches the location parameter. For example, here the request with the /some/path/page.html URI will be proxied to http://www.example.com/link/page.html. If the address is specified without a URI, or it is not possible to determine the part of URI to be replaced, the full request URI is passed (possibly, modified).

To pass a request to a non-HTTP proxied server, the appropriate **_pass directive should be used:

Note that in these cases, the rules for specifying addresses may be different. You may also need to pass additional parameters to the server (see the reference documentation for more detail).

The proxy_pass directive can also point to a named group of servers. In this case, requests are distributed among the servers in the group according to the specified method .

Passing Request Headers

By default, NGINX redefines two header fields in proxied requests, “Host” and “Connection”, and eliminates the header fields whose values are empty strings. “Host” is set to the $proxy_host variable, and “Connection” is set to close.

To change these setting, as well as modify other header fields, use the proxy_set_header directive. This directive can be specified in a location or higher. It can also be specified in a particular server context or in the http block. For example:

location /some/path/ {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_pass http://localhost:8000;
}

In this configuration the “Host” field is set to the $host variable.

To prevent a header field from being passed to the proxied server, set it to an empty string as follows:

location /some/path/ {
    proxy_set_header Accept-Encoding "";
    proxy_pass http://localhost:8000;
}

Configuring Buffers

By default NGINX buffers responses from proxied servers. A response is stored in the internal buffers and is not sent to the client until the whole response is received. Buffering helps to optimize performance with slow clients, which can waste proxied server time if the response is passed from NGINX to the client synchronously. However, when buffering is enabled NGINX allows the proxied server to process responses quickly, while NGINX stores the responses for as much time as the clients need to download them.

The directive that is responsible for enabling and disabling buffering is proxy_buffering . By default it is set to on and buffering is enabled.

The proxy_buffers directive controls the size and the number of buffers allocated for a request. The first part of the response from a proxied server is stored in a separate buffer, the size of which is set with the proxy_buffer_size directive. This part usually contains a comparatively small response header and can be made smaller than the buffers for the rest of the response.

In the following example, the default number of buffers is increased and the size of the buffer for the first portion of the response is made smaller than the default.

location /some/path/ {
    proxy_buffers 16 4k;
    proxy_buffer_size 2k;
    proxy_pass http://localhost:8000;
}

If buffering is disabled, the response is sent to the client synchronously while it is receiving it from the proxied server. This behavior may be desirable for fast interactive clients that need to start receiving the response as soon as possible.

To disable buffering in a specific location, place the proxy_buffering directive in the location with the off parameter, as follows:

location /some/path/ {
    proxy_buffering off;
    proxy_pass http://localhost:8000;
}

In this case NGINX uses only the buffer configured by proxy_buffer_size to store the current part of a response.

A common use of a reverse proxy is to provide load balancing. Learn how to improve power, performance, and focus on your apps with rapid deployment in the free Five Reasons to Choose a Software Load Balancer ebook.

Choosing an Outgoing IP Address

If your proxy server has several network interfaces, sometimes you might need to choose a particular source IP address for connecting to a proxied server or an upstream. This may be useful if a proxied server behind NGINX is configured to accept connections from particular IP networks or IP address ranges.

Specify the proxy_bind directive and the IP address of the necessary network interface:

location /app1/ {
    proxy_bind 127.0.0.1;
    proxy_pass http://example.com/app1/;
}

location /app2/ {
    proxy_bind 127.0.0.2;
    proxy_pass http://example.com/app2/;
}

The IP address can be also specified with a variable. For example, the $server_addr variable passes the IP address of the network interface that accepted the request:

location /app3/ {
    proxy_bind $server_addr;
    proxy_pass http://example.com/app3/;
}

NGINX SSL Termination

Terminate HTTPS traffic from clients, relieving your upstream web and application servers of the computational load of SSL/TLS encryption.

This section describes how to configure an HTTPS server on NGINX and NGINX Plus.

Setting up an HTTPS Server

To set up an HTTPS server, in your nginx.conf file include the ssl parameter to the listen directive in the server block, then specify the locations of the server certificate and private key files:

server {
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.crt;
    ssl_certificate_key www.example.com.key;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    #...
}

The server certificate is a public entity. It is sent to every client that connects to the NGINX or NGINX Plus server. The private key is a secure entity and should be stored in a file with restricted access. However, the NGINX master process must be able to read this file. Alternatively, the private key can be stored in the same file as the certificate:

ssl_certificate     www.example.com.cert;
ssl_certificate_key www.example.com.cert;

In this case it is important to restrict access to the file. Note that although the certificate and the key are stored in one file in this case, only the certificate is sent to clients.

The ssl_protocols and ssl_ciphers directives can be used to require that clients use only the strong versions and ciphers of SSL/TLS when establishing connections.

Since version 1.9.1, NGINX uses these defaults:

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;

Vulnerabilities are sometimes found in the design of older ciphers, and we recommend disabling them in a modern NGINX configuration (unfortunately, the default configuration cannot easily be changed because of backward compatibility for existing NGINX deployments). Please note that CBC-mode ciphers might be vulnerable to a number of attacks (the BEAST attack in particular as described in CVE-2011-3389 ), and we recommend not using SSLv3 due to the POODLE attack, unless you need to support legacy clients.

OCSP Validation of Client Certificates

NGINX can be configured to use Online Certificate Status Protocol (OCSP) to check the validity of X.509 client certificates as they are presented. An OCSP request for the client certificate status is sent to an OCSP responder which checks the certificate validity and returns the response with the certificate status:

  • Good – the certificate is not revoked
  • Revoked – the certificate is revoked
  • Unknown – no information is available about the client certificate

To enable OCSP validation of SSL client certificates, specify the ssl_ocsp directive along with the ssl_verify_client directive, which enables certificate verification:

server {
    listen 443 ssl;

    ssl_certificate     /etc/ssl/foo.example.com.crt;
    ssl_certificate_key /etc/ssl/foo.example.com.key;

    ssl_verify_client       on;
    ssl_trusted_certificate /etc/ssl/cachain.pem;
    ssl_ocsp                on; # Enable OCSP validation

    #...
}

NGINX sends the OCSP request to the OCSP URI embedded in the client certificate unless a different URI is defined with the ssl_ocsp_responder directive. Only http:// OCSP responders are supported:

#...
ssl_ocsp_responder http://ocsp.example.com/;
#...

To cache OCSP responses in a single memory zone shared by all worker processes, specify the ssl_ocsp_cache directive to define the name and size of the zone. Responses are cached for 1 hour unless the nextUpdatevalue in the OCSP response specifies a different value:

#...
ssl_ocsp_cache shared:one:10m;
#...

The result of the client certificate validation is available in the $ssl_client_verify variable, including the reason for OCSP failure.

HTTPS Server Optimization

SSL operations consume extra CPU resources. The most CPU-intensive operation is the SSL handshake. There are two ways to minimize the number of these operations per client:

  • Enabling keepalive connections to send several requests via one connection
  • Reusing SSL session parameters to avoid SSL handshakes for parallel and subsequent connections

Sessions are stored in the SSL session cache shared between worker processes and configured by the ssl_session_cache directive. One megabyte of cache contains about 4000 sessions. The default cache timeout is 5 minutes. This timeout can be increased using the ssl_session_timeout directive. Below is a sample configuration optimized for a multi-core system with 10 megabyte shared session cache:

worker_processes auto;

http {
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;

    server {
        listen              443 ssl;
        server_name         www.example.com;
        keepalive_timeout   70;

        ssl_certificate     www.example.com.crt;
        ssl_certificate_key www.example.com.key;
        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers         HIGH:!aNULL:!MD5;
        #...
    }
}

SSL Certificate Chains

Some browsers may complain about a certificate signed by a well-known certificate authority, while other browsers may accept the certificate without issues. This occurs because the issuing authority has signed the server certificate using an intermediate certificate that is not present in the base of well-known trusted certificate authorities which is distributed in a particular browser. In this case the authority provides a bundle of chained certificates that should be concatenated to the signed server certificate. The server certificate must appear before the chained certificates in the combined file:

$ cat www.example.com.crt bundle.crt > www.example.com.chained.crt

The resulting file should be used in the ssl_certificate directive:

server {
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.chained.crt;
    ssl_certificate_key www.example.com.key;
    #...
}

If the server certificate and the bundle have been concatenated in the wrong order, NGINX fails to start and displays the following error message:

SSL_CTX_use_PrivateKey_file(" ... /www.example.com.key") failed
   (SSL: error:0B080074:x509 certificate routines:
    X509_check_private_key:key values mismatch)

The error happens because NGINX has tried to use the private key with the bundle’s first certificate instead of the server certificate.

Browsers usually store intermediate certificates which they receive and are signed by trusted authorities. So actively used browsers may already have the required intermediate certificates and may not complain about a certificate sent without a chained bundle. To ensure the server sends the complete certificate chain the openssl command-line utility may be used:

$ openssl s_client -connect www.godaddy.com:443
...
Certificate chain
 0 s:/C=US/ST=Arizona/L=Scottsdale/1.3.6.1.4.1.311.60.2.1.3=US
     /1.3.6.1.4.1.311.60.2.1.2=AZ/O=GoDaddy.com, Inc
     /OU=MIS Department/CN=www.GoDaddy.com
     /serialNumber=0796928-7/2.5.4.15=V1.0, Clause 5.(b)
   i:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
     /OU=http://certificates.godaddy.com/repository
     /CN=Go Daddy Secure Certification Authority
     /serialNumber=07969287
 1 s:/C=US/ST=Arizona/L=Scottsdale/O=GoDaddy.com, Inc.
     /OU=http://certificates.godaddy.com/repository
     /CN=Go Daddy Secure Certification Authority
     /serialNumber=07969287
   i:/C=US/O=The Go Daddy Group, Inc.
     /OU=Go Daddy Class 2 Certification Authority
 2 s:/C=US/O=The Go Daddy Group, Inc.
     /OU=Go Daddy Class 2 Certification Authority
   i:/L=ValiCert Validation Network/O=ValiCert, Inc.
     /OU=ValiCert Class 2 Policy Validation Authority
     /CN=http://www.valicert.com//emailAddress=info@valicert.com
...

In this example the subject (“s”) of the www.GoDaddy.com server certificate #0 is signed by an issuer (“i”) which itself is the subject of certificate #1. Certificate #1 is signed by an issuer which itself is the subject of certificate #2. This certificate, however, is signed by the well‑known issuer ValiCert, Inc. whose certificate is stored in the browsers themselves.

If a certificate bundle has not been added, only the server certificate (#0) is shown.

A Single HTTP/HTTPS Server

It is possible to configure a single server that handles both HTTP and HTTPS requests by placing one listen directive with the ssl parameter and one without in the same virtual server:

server {
    listen              80;
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.crt;
    ssl_certificate_key www.example.com.key;
    #...
}

In NGINX version 0.7.13 and earlier, SSL cannot be enabled selectively for individual listening sockets, as shown above. SSL can only be enabled for the entire server using the ssl directive, making it impossible to set up a single HTTP/HTTPS server. The ssl parameter to the listen directive was added to solve this issue. The ssl directive therefore is deprecated in version 0.7.14 and later.

Name-Based HTTPS Servers

A common issue arises when two or more HTTPS servers are configured to listen on a single IP address:

server {
    listen          443 ssl;
    server_name     www.example.com;
    ssl_certificate www.example.com.crt;
    #...
}

server {
    listen          443 ssl;
    server_name     www.example.org;
    ssl_certificate www.example.org.crt;
    #...
}

With this configuration, a browser receives the default server’s certificate. In this case, it is www.example.com regardless of the requested server name. This is caused by the behavior of the SSL protocol itself. The SSL connection is established before the browser sends an HTTP request and NGINX does not know the name of the requested server. Therefore, it may only offer the default server’s certificate.

The best way to solve this issue is to assign a separate IP address to every HTTPS server:

server {
    listen          192.168.1.1:443 ssl;
    server_name     www.example.com;
    ssl_certificate www.example.com.crt;
    #...
}

server {
    listen          192.168.1.2:443 ssl;
    server_name     www.example.org;
    ssl_certificate www.example.org.crt;
    #...
}

Note that there are also some specific proxy settings for HTTPS upstreams (proxy_ssl_ciphers , proxy_ssl_protocols , and proxy_ssl_session_reuse ) which can be used for fine‑tuning SSL between NGINX and upstream servers. You can read more about these in the HTTP proxy module documentation .

An SSL Certificate With Several Names

There are other ways to share a single IP address among several HTTPS servers. However, all of them have drawbacks. One way is to use a certificate with several names in the SubjectAltName certificate field, for example, www.example.com and www.example.org. However, the length of the SubjectAltName field is limited.

Another way is to use a certificate with a wildcard name, for example, *.example.org. A wildcard certificate secures all subdomains of the specified domain, but only on one level. This certificate matches www.example.org, but does not match example.org or www.sub.example.org. These two methods can also be combined. A certificate may contain exact and wildcard names in the SubjectAltName field. For example, example.org and *.example.org.

It is better to place a certificate file with several names and its private key file at the http level of your configuration so that they inherit the single memory copy across all servers:

ssl_certificate     common.crt;
ssl_certificate_key common.key;

server {
    listen          443 ssl;
    server_name     www.example.com;
    #...
}

server {
    listen          443 ssl;
    server_name     www.example.org;
    #...
}

Server Name Indication

A more generic solution for running several HTTPS servers on a single IP address is the TLS Server Name Indication  (SNI) extension (RFC 6066 ), which allows a browser to pass a requested server name during the SSL handshake. With this solution, the server will know which certificate it should use for the connection. However, SNI has limited browser support. Currently it is supported starting with the following browser versions:

  • Opera 8.0
  • MSIE 7.0 (but only on Windows Vista or higher)
  • Firefox 2.0 and other browsers using Mozilla Platform rv:1.8.1
  • Safari 3.2.1 (Windows version supports SNI on Vista or higher)
  • Chrome (Windows version supports SNI on Vista or higher, too)

Only domain names can be passed in SNI. However, some browsers will pass the IP address of the server as its name if a request includes a literal IP address. It is best not to rely on this.

In order to use SNI in NGINX, it must be supported in both the OpenSSL library with which the NGINX binary has been built, as well as the library with which it is being dynamically linked at runtime. OpenSSL supports SNI since the version 0.9.8f if it was built with configuration option --enable-tlsext. Since OpenSSL version 0.9.8j, this option is enabled by default. If NGINX was built with SNI support, NGINX shows the following when run with the -V switch:

$ nginx -V
...
TLS SNI support enabled
...

However, if the SNI-enabled NGINX is linked dynamically to an OpenSSL library without SNI support, NGINX displays the warning:

NGINX was built with SNI support, however, now it is linked
dynamically to an OpenSSL library which has no tlsext support,
therefore SNI is not available

Compatibility Notes

  • The SNI support status has been shown by the -V switch since versions 0.8.21 and 0.7.62.
  • The ssl parameter to the listen directive has been supported since version 0.7.14. Prior to version 0.8.21 it could only be specified along with the default parameter.
  • SNI has been supported since version 0.5.23.
  • The shared SSL session cache has been supported since version 0.5.6.
  • Version 1.9.1 and later: the default SSL protocols are TLSv1, TLSv1.1, and TLSv1.2 (if supported by the OpenSSL library).
  • From versions 0.7.65 and 0.8.19 and later, the default SSL protocols are SSLv3, TLSv1, TLSv1.1, and TLSv1.2 (if supported by the OpenSSL library).
  • In versions 0.7.64 and 0.8.18 and earlier, the default SSL protocols are SSLv2, SSLv3, and TLSv1.
  • In version 1.0.5 and later, the default SSL ciphers are HIGH:!aNULL:!MD5.
  • In versions 0.7.65 and 0.8.20 and later, the default SSL ciphers are HIGH:!ADH:!MD5.
  • From version 0.8.19 the default SSL ciphers are ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM.
  • From version 0.7.64, 0.8.18 and earlier the default SSL ciphers are ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP.

What’s on this Page

You May Also Like

密码保护：linux and some

TE

Wireshark TCPDUMP

TE 0

清华质谱 AMiner –AI帮你理解科学

TE 0

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注