Nginx Wiki (aktuell: http://nginxorg/en/docs/)

SynopsisDieses Modul ermöglicht es, Anfragen an einen anderen Server zu übertragen.Beispiel:

<span>location</span> / <span>{</span>
  proxy_pass        <span>http</span>://localhost:<span>8000</span><span>;</span>
  proxy_set_header  X-Real-IP  <span>$remote_addr</span><span>;</span><span>}</span>

Beachten Sie, dass bei Verwendung des HTTP-Proxy-Moduls (oder sogar bei Verwendung von FastCGI) die gesamte Client-Anfrage in Nginx gepuffert wird, bevor sie an die Backend-Proxy-Server weitergeleitet wird. Daher funktionieren die Upload-Fortschrittsanzeigen nicht ordnungsgemäß, wenn sie funktionieren durch Messen der von den Backend-Servern empfangenen Daten.Anweisungenproxy_bindSyntax: proxy_bind-AdresseStandard: keineKontext: http, Server, OrtVersion: ≥ 0.8.22Beispiel:

proxy_bind  192.168.1.1<span>;</span>

Diese Direktive bindet jeden Upstream-Socket an eine lokale Adresse, bevor connect() aufgerufen wird. Dies kann nützlich sein, wenn der Host über mehrere Schnittstellen/Aliase verfügt und Sie ausgehende Verbindungen von einer bestimmten Schnittstelle/Adresse weiterleiten möchten.proxy_buffer_size Syntax: proxy_buffer_size size Default: 4k|8k Context: http
server
location Reference: proxy_buffer_size Syntax: proxy_buffer_size size td> Standard: 4k|8k Kontext: http
Server
Standort Referenz: proxy_buffer_size
Diese Direktive legt die Puffergröße fest, in die der erste Teil der Antwort eingelesen wird, der vom Proxy-Server erhalten wird.In diesem Teil der Antwort wird der kleine In der Regel befindet sich der Antwortheader.Standardmäßig entspricht die Puffergröße der Größe eines Puffers in der Direktive proxy_buffers; Es ist jedoch möglich, es einzustellen zu weniger.proxy_buffering Syntax: proxy_buffering on | off Default: on Context: http
server
location Reference: proxy_buffering Syntax: proxy_buffering on | aus Standard: ein Kontext: httpServerStandort Referenz: proxy_buffering
Diese Anweisung aktiviert die Antwortpufferung des Proxy-Servers.Wenn die Pufferung aktiviert ist, liest nginx die Antwort so schnell wie möglich vom Proxy-Server und speichert sie der Puffer, wie durch die Anweisungen proxy_buffer_size und proxy_buffers konfiguriert. Passt die Antwort nicht in den Speicher, werden Teile davon auf die Festplatte geschrieben.Wenn die Pufferung ausgeschaltet ist, wird die Antwort sofort beim Empfang synchron an den Client übertragen. Nginx versucht nicht, die gesamte Antwort vom Proxy-Server zu lesen. Die maximale Datengröße, die Nginx vom Server akzeptieren kann, beträgt Wird durch die Direktive festgelegt proxy_buffer_size.Beachten Sie außerdem, dass das Zwischenspeichern von Upstream-Proxy-Antworten nicht funktioniert, wenn „proxy_buffering“ deaktiviert ist.Für Comet-Anwendungen, die auf Long-Polling basieren, ist es wichtig, dies festzulegen Proxy_buffering auf „off“, andernfalls wird die asynchrone Antwort gepuffert und der Comet funktioniert nicht.Die Pufferung kann auf Einzelanforderungsbasis festgelegt werden, indem der X-Accel-Buffering Header in der Proxy-Antwort festgelegt wird. proxy_buffers Syntax: proxy_buffers number size Default: 8 4k|8k Context: http
server
location Reference: proxy_buffers Syntax: proxy_buffers 
Zahlengröße Standard: 8 4k|8k Syntax: proxy_busy_buffers_size size Default: 8k|16k Context: http
server
location Reference: proxy_busy_buffers_size Kontext:httpServerStandort Referenz: td> proxy_buffers Diese Direktive legt die Anzahl und die Größe der Puffer fest, in die eingelesen wird Die vom Proxy-Server erhaltene Antwort entspricht standardmäßig der Größe der Seite. Je nach Plattform beträgt diese entweder 4K oder 8K.proxy_busy_buffers_size Syntax: proxy_busy_buffers_size size Standard: 8k|16k Kontext: httpServerStandort Referenz: proxy_busy_buffers_size
proxy_cache Syntax: proxy_cache zone | off Default: off Context: http
server
location Reference: proxy_cache Syntax: proxy_cache 
zone | off Default: aus Kontext: httpServerStandort Referenz: proxy_cache

Diese Direktive legt den Namen der Zone für das Caching fest. Dieselbe Zone kann an mehreren Orten verwendet werden.

Der Cache berücksichtigt seit Version 0.7 die Backend-Header „Expires“, „Cache-Control: no-cache“ und „Cache-Control: max-age=XXX“. .48. Seit Version 7.66 werden auch „private“ und „no-store“ berücksichtigt. Nginx verarbeitet beim Caching keine „Vary“-Header. Um sicherzustellen Damit private Elemente nicht unbeabsichtigt vom Cache an alle Benutzer bereitgestellt werden, kann das Back-End „no-cache“ oder „max-age=0“ festlegen oder der proxy_cache_key muss enthalten benutzerspezifische Daten wie $cookie_xxx. Die Verwendung von Cookie-Werten als Teil von 

proxy_cache_key

 kann jedoch die Vorteile des Cachings für öffentliche Elemente zunichte machen. Trennen Sie daher Standorte mit unterschiedlichen 

proxy_cache_key Werten Möglicherweise ist es erforderlich, private und öffentliche Elemente zu trennen.Der Cache hängt von Proxy-Puffer ab und funktioniert nicht, wenn „proxy_buffers“ auf „off“ gesetzt ist.Die folgenden Antwortheader kennzeichnen eine Antwort als nicht zwischenspeicherbar, sofern nicht Sie werden ignoriert: Syntax: proxy_cache_bypass string ... Default:   Context: http
server
location Reference: proxy_cache_bypass Set-CookieCache-Control mit „no-cache“, „no-store“, „private“ oder einem „max-age“ mit ein nicht numerischer oder 0-WertLäuft mit einem Zeitpunkt in der Vergangenheit abX-Accel-Expires: 0proxy_cache_bypass Syntax: proxy_cache_bypass string .. . Standard:   Kontext: httpServerStandort Referenz: proxy_cache_bypass td>
The directive specifies the conditions under which the answer will not be taken from the cache. If at least one of a string variable is not empty and not equal to "0", the answer is not taken from the cache:

 proxy_cache_bypass <span>$cookie_nocache</span><span>$arg_nocache</span><span>$arg_comment</span><span>;</span>
 proxy_cache_bypass <span>$http_pragma</span><span>$http_authorization</span><span>;</span>

Note that the response from the back-end is still eligible for caching. Thus one way of refreshing an item in the cache is sending a request with a header you pick yourself, e.g. "My-Secret-Header: 1", then having a proxy_cache_bypass line like:

proxy_cache_bypass <span>$http_my_secret_header</span><span>;</span>

Can be used in conjunction with the directive proxy_no_cache.proxy_cache_key Syntax: proxy_cache_key string Default: $scheme$proxy_host$request_uri Context: http
server
location Reference: proxy_cache_key
The directive specifies what information is included in the key for caching, for example

proxy_cache_key <span>"$host$request_uri$cookie_user"</span><span>;</span>

Note that by default, the hostname of the server is not included in the cache key. If you are using subdomains for different locations on your website, you need to include it, e.g. by changing the cache key to something like

proxy_cache_key <span>"$scheme$host$request_uri"</span><span>;</span>

proxy_cache_lock Syntax: proxy_cache_lock on | off Default: off Context: http
server
location Appeared in: 1.1.12 Reference: proxy_cache_lock When enabled, only one request at a time will be allowed to populate a new cache element identified according to the proxy_cache_key directive by passing a request to a proxied server. Other requests of the same cache element will either wait for a response to appear in the cache or the cache lock for this element to be released, up to the time set by the proxy_cache_lock_timeout directive. Similar effect for updating cache entry (this directive works only for inserting new cache element) can be archieved by using proxy_cache_use_stale updating directive.proxy_cache_lock_timeout Syntax: proxy_cache_lock_timeout time Default: 5s Context: http
server
location Appeared in: 1.1.12 Reference: proxy_cache_lock_timeout
proxy_cache_methodssyntax: proxy_cache_methods [GET HEAD POST];default: proxy_cache_methods GET HEAD;context: http, server, locationGET/HEAD is syntax sugar, i.e. you can not disable GET/HEAD even if you set just

proxy_cache_methods POST<span>;</span>

proxy_cache_min_uses Syntax: proxy_cache_min_uses number Default: 1 Context: http
server
location Reference: proxy_cache_min_uses
Anzahl der Abfragen, nach denen die Antwort zwischengespeichert wird.proxy_cache_path Syntax: proxy_cache_path path [ levels = levels ] keys_zone = name : size [ inactive = time ] [ max_size = size ] [ loader_files = number ] [ loader_sleep = time ] [ loader_threshold = time ] Default:   Context: http Reference: proxy_cache_path Syntax: proxy_cache_path path [ levels = levels ] keys_zone = name : size [ inaktiv Code> = Zeit ] [ max_size = size ] [ loader_files = number  ] [ loader_sleep = time ] [ loader_threshold = time  ] Standard:   Kontext: http Referenz: proxy_cache_path
This directive sets the cache path and other cache parameters. Cached data is stored in files. An MD5 hash of the proxied URL is used as the key for the cache entry, and is also used as the filename in the cache path for the response contents and metadata. The levels parameter sets the number of subdirectory levels in cache. For example:

proxy_cache_path  /data/nginx/cache/one  levels<span>=</span><span>1</span>:<span>2</span>   keys_zone<span>=</span>one:10m<span>;</span>

In this cache, file names will be like the following:

<span>/</span>data<span>/</span>nginx<span>/</span>cache<span>/</span>c<span>/</span><span>29</span><span>/</span>b7f54b2df7773722d382f4809d65029c

You may use any combination of 1 and 2 in the level formats: X, X:X, or X:X:X e.g.: "2", "2:2", "1:1:2". There can be at most 3 levels.All active keys and metadata is stored in shared memory. Zone name and the size of the zone is defined via the keys_zone parameter.Note that each defined zone must have a unique path. For example:

proxy_cache_path  /data/nginx/cache/one    levels<span>=</span><span>1</span>      keys_zone<span>=</span>one:10m<span>;</span>
proxy_cache_path  /data/nginx/cache/two    levels<span>=</span><span>2</span>:<span>2</span>    keys_zone<span>=</span>two:100m<span>;</span>
proxy_cache_path  /data/nginx/cache/three  levels<span>=</span><span>1</span>:<span>1</span>:<span>2</span>  keys_zone<span>=</span>three:1000m<span>;</span>

If cached data is not requested for time defined by the inactive parameter, than that data is removed from the cache. The inactive parameter defaults to 10 minutes (10m).A special process, called "cache manager", is created to control the on-disk cache. It is responsible for removing inactive items and enforcing the size of the cache, as defined by the parameter max_size. When the total size of the cache exceeds the maximum size set by max_size, the least recently used data in the cache is deleted to make room for a new cache entry (a LRU replacement policy).Zone size should be set proportional to number of pages to cache. The size of the metadata for one page (file) depends on the OS; currently it is 64 bytes for FreeBSD/i386, and 128 bytes for FreeBSD/amd64.The directories specified by proxy_cache_path and proxy_temp_path should be located on the same filesystem.proxy_cache_use_stale Syntax: proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_404 | off ... Default: off Context: http
server
location Reference: proxy_cache_use_stale
Diese Anweisung teilt Nginx mit, wann ein veraltetes Element aus dem Proxy-Cache bereitgestellt werden soll. Die Parameter für diese Anweisung ähneln denen von „proxy_next_upstream“. der Zusatz „updating“.Um Cache-Stampedes zu verhindern (wenn mehrere Threads gleichzeitig versuchen, den Cache zu aktualisieren), können Sie den Parameter „updating“ angeben. Dies führt dazu, dass ein Thread den Cache aktualisiert und während die Aktualisierung ausgeführt wird, werden alle anderen Threads bedient die veraltete Version dessen, was sich im Cache befindet.proxy_cache_valid Syntax: proxy_cache_valid [ code ...] time Default:   Context: http
server
location Reference: proxy_cache_valid Syntax: proxy_cache_valid [ code . ..] Zeit Standard:   Kontext: httpServerStandort Referenz: proxy_cache_valid
This directive sets the time for caching different replies. Example:

proxy_cache_valid  <span>200</span><span>302</span>  10m<span>;</span>
proxy_cache_valid  <span>404</span>      1m<span>;</span>

sets 10 minutes cache time for replies with code 200 and 302, and 1 minute for 404s.If only time is specified:

proxy_cache_valid 5m<span>;</span>

then only replies with codes 200, 301 and 302 will be cached.Also it is possible to cache any replies with parameter "any":

proxy_cache_valid  <span>200</span><span>302</span> 10m<span>;</span>
proxy_cache_valid  <span>301</span> 1h<span>;</span>
proxy_cache_valid  any 1m<span>;</span>

Upstream cache-related directives have priority over proxy_cache_valid value, in particular the order is (from Igor):

X-Accel-Expires

Expires/Cache-Control

proxy_cache_valid

The order in which your backend return HTTP headers change cache behaviour. Read this post for details.You may ignore the headers using

proxy_ignore_headers X-Accel-Expires Expires Cache-Control<span>;</span>

Concerning If-Modified / Last-Modified since behaviour, please remember that by default nginx sends 304 only if L-M == I-M-S. Controlled by directive if_modified_since [off|exact|before]Note: you must set this option for any persistent caching to occur.proxy_connect_timeout Syntax: proxy_connect_timeout time Default: 60s Context: http
server
location Reference: proxy_connect_timeout
Diese Direktive weist einen Timeout für die Verbindung zum Upstream-Server zu. Es ist zu beachten, dass dieses Timeout nicht mehr als 75 Sekunden betragen darf.Dies ist nicht die Zeit, bis der Server die Seiten zurückgibt, sondern die proxy_read_timeout Anweisung. Wenn Ihr Wenn der Upstream-Server aktiv ist, aber hängen bleibt (z. B. weil er nicht über genügend Threads verfügt, um Ihre Anfrage zu verarbeiten, sodass Sie in den Pool von Verbindungen aufgenommen werden, mit denen Sie sich später befassen müssen), hilft diese Anweisung nicht weiter, da die Verbindung zum Server hergestellt wurde. proxy_cookie_domain Syntax: proxy_cookie_domain off 
proxy_cookie_domain domain replacement Default: off Context: http
server
location Appeared in: 1.1.15 Reference: proxy_cookie_domain Syntax: proxy_cookie_domain off 
proxy_cookie_domain Domain-Ersatz Standard: Syntax: proxy_cookie_path off 
proxy_cookie_path path replacement Default: off Context: http
server
location Appeared in: 1.1.15 Reference: proxy_cookie_path aus Kontext: http ServerStandort Erschien in: 1.1.15 Referenz:proxy_cookie_domain proxy_cookie_path Syntax: proxy_cookie_path off proxy_cookie_path Pfad-Ersetzung Standard: aus Kontext: http ServerStandort Erschien in: 1.1.15 Referenz:proxy_cookie_path
proxy_headers_hash_bucket_sizeSyntax: proxy_headers_hash_bucket_size size;Standard: proxy_headers_hash_bucket_size 64;Kontext: http, Server, Standort, wennDiese Direktive legt die Bucket-Größe der Header-Hash-Tabelle fest. 
Dies bestimmt die Grenze des Header-Namens. Wenn Sie Header-Namen mit mehr als 64 Zeichen verwenden, erhöhen Sie diese.proxy_headers_hash_max_sizeSyntax: proxy_headers_hash_max_size size;Standard: proxy_headers_hash_max_size 512;Kontext: http, Server, Standort, wennDiese Direktive legt die maximale Größe der Header-Hash-Tabelle fest. 
Sollte nicht kleiner sein als die Anzahl der Header, die Ihr Backend festlegt.proxy_hide_header Syntax: proxy_hide_header field Default:   Context: http
server
location Reference: proxy_hide_header Syntax: proxy_hide_header field td> Standard:   Kontext: httpServerStandort Referenz: proxy_hide_header
nginx does not transfer the "Date", "Server", "X-Pad" and "X-Accel-..." header lines from the proxied server response. The proxy_hide_header directive allows to hide some additional header lines. But if on the contrary the header lines must be passed, then the proxy_pass_header should be used. For example if you want to hide the MS-OfficeWebserver and the AspNet-Version:

<span>location</span> / <span>{</span>
  proxy_hide_header X-AspNet-Version<span>;</span>
  proxy_hide_header MicrosoftOfficeWebServer<span>;</span><span>}</span>

This directive can also be very helpful when using X-Accel-Redirect. For example, you may have one set of backend servers which return the headers for a file download, which includes X-Accel-Redirect to the actual file, as well as the correct Content-Type. However, the Redirect URL points to a files erver which hosts the actual file you wish to serve, and that server sends its own Content-Type header, which might be incorrect, and overrides the header sent by the original backend servers. You can avoid this by adding the proxy_hide_header directive to the fileserver. Example:

<span>location</span> / <span>{</span>
  proxy_pass <span>http</span>://backend_servers<span>;</span><span>}</span>
 
<span>location</span> /files/ <span>{</span>
  proxy_pass <span>http</span>://fileserver<span>;</span>
  proxy_hide_header Content-Type<span>;</span><span>}</span>

proxy_http_version Syntax: proxy_http_version 1.0 | 1.1 Default: 1.0 Context: http
server
location Appeared in: 1.1.4 Reference: proxy_http_version
proxy_ignore_client_abort Syntax: proxy_ignore_client_abort on | off Default: off Context: http
server
location Reference: proxy_ignore_client_abort
Verhindert den Abbruch der Anfrage an den Proxy, falls der Client selbst die Anfrage abbricht.proxy_ignore_headers Syntax: proxy_ignore_headers field ... Default:   Context: http
server
location Reference: proxy_ignore_headers Syntax: proxy_ignore_headers 
field .. . Standard:   Kontext: httpServerStandort Syntax: proxy_intercept_errors on | off Default: off Context: http
server
location Reference: proxy_intercept_errors Referenz: proxy_ignore_headers td>
Verhindert die Verarbeitung der Headerzeilen aus der Antwort des Proxyservers.Es kann die Zeichenfolge angeben als „X-Accel-Redirect“, „X-Accel-Expires“, „Expires“, „Cache-Control“ oder „Set-Cookie“. nginx speichert keine Anfragen mit Set-Cookie zwischen.onerror_pageproxy_intercept_errorserror_page Syntax: proxy_intercept_errors  Syntax: proxy_max_temp_file_size size Default: 1024m Context: http
server
location Reference: proxy_max_temp_file_size  | aus Standard: aus Kontext: httpServerStandort Referenz: proxy_intercept_errors Dies Die Direktive entscheidet, ob Nginx Antworten mit HTTP-Statuscodes von 400 und höher abfängt.Standardmäßig werden alle Antworten unverändert vom Proxyserver gesendet.Wenn Sie dies auf  dann fängt Nginx Statuscodes ab, die explizit von einer  Direktive behandelt werden. Antworten mit Statuscodes, die nicht mit einer  Anweisung übereinstimmen, werden unverändert vom Proxyserver gesendet.proxy_max_temp_file_size Syntax: proxy_max_temp_file_size Größe td> Standard: 1024m Kontext: httpServerStandort Referenz: proxy_max_temp_file_size
The maximum size of a temporary file when the content is larger than the proxy buffer. If file is larger than this size, it will be served synchronously from upstream server rather than buffered to disk.If proxy_max_temp_file_size is equal to zero, temporary files usage will be disabled.proxy_methodsyntax: proxy_method [method];default: Nonecontext: http, server, locationAllows you to override the HTTP method of the request to be passed to the backend server. If you specify POST for example, all requests forwarded to the backend server will be POST requests.Example:

proxy_method POST<span>;</span>

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 Context: http
server
location Reference: proxy_next_upstream
Directive determines in what cases the request will be transmitted to the next server:

error — an error has occurred while connecting to the server, sending a request to it, or reading its response;

timeout — occurred timeout during the connection with the server, transfer the request or while reading response from the server;

invalid_header — server returned a empty or incorrect answer;

http_500 — server returned answer with code 500

http_502 — server returned answer with code 502

http_503 — server returned answer with code 503

http_504 — server returned answer with code 504

http_404 — server returned answer with code 404

off — it forbids the request transfer to the next server

Transferring the request to the next server is only possible when nothing has been transferred to the client -- that is, if an error or timeout arises in the middle of the transfer of the request, then it is not possible to retry the current request on a different server.proxy_no_cache Syntax: proxy_no_cache string ... Default:   Context: http
server
location Reference: proxy_no_cache
Specifies in what cases a response will not be cached, e.g.

proxy_no_cache <span>$cookie_nocache</span><span>$arg_nocache</span><span>$arg_comment</span><span>;</span>
proxy_no_cache <span>$http_pragma</span><span>$http_authorization</span><span>;</span>

The response is marked uncacheable if any of the arguments expand to anything other than "0" or the empty string. For instance, in the above example, the response will never be cached if the cookie "nocache" is set in the request.proxy_pass Syntax: proxy_pass URL Default:   Context: location
if in location
limit_except Reference: proxy_pass
This directive sets the address of the proxied server and the URI to which location will be mapped. Address may be given as hostname or address and port, for example,

proxy_pass <span>http</span>://localhost:<span>8000</span>/uri/<span>;</span>

or as unix socket path:

proxy_pass <span>http</span>://unix:/path/to/backend.socket:/uri/<span>;</span>

path is given after the word unix between two colons.By default, the Host header from the request is not forwarded, but is set based on the proxy_pass statement. To forward the requested Host header, it is necessary to use:

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

While passing request nginx replaces URI part which corresponds to location with one indicated in proxy_pass direct