nginx-site: xml/en/docs/http/request

annotate xml/en/docs/http/request_processing.xml @ 3083:3b5594157fab

Documented max_headers directive.

author	Maxim Dounin <mdounin@mdounin.ru>
date	Fri, 24 May 2024 01:16:29 +0300
parents	130fad6dc1b4
children

rev	line source
580 be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 521 diff changeset	1 <!--
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 521 diff changeset	2 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 521 diff changeset	3 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 521 diff changeset	4 -->
be54c443235a Added copyright markers to documentation sources. Ruslan Ermilov <ru@nginx.com> parents: 521 diff changeset	5
50 9d544687d02c Fixed DOCTYPE declaration. Ruslan Ermilov <ru@nginx.com> parents: 0 diff changeset	6 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	7
123 7db449e89e92 Unified the use of the "name" attribute instead of "title". Ruslan Ermilov <ru@nginx.com> parents: 121 diff changeset	8 <article name="How nginx processes a request"
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	9 link="/en/docs/http/request_processing.html"
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	10 lang="en"
589 764fbac1b8b4 Added document revision. Ruslan Ermilov <ru@nginx.com> parents: 580 diff changeset	11 rev="1"
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	12 author="Igor Sysoev"
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	13 editor="Brian Mercer">
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	14
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 74 diff changeset	15 <section name="Name-based virtual servers">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	16
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	17 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	18 nginx first decides which <i>server</i> should process the request.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	19 Let’s start with a simple configuration
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	20 where all three virtual servers listen on port *:80:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	21 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	22 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	23 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	24 server_name example.org www.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	25 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	26 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	27
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	28 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	29 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	30 server_name example.net www.example.net;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	31 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	32 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	33
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	34 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	35 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	36 server_name example.com www.example.com;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	37 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	38 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	39 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	40
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	43 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	44 In this configuration nginx tests only the request’s header field
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	45 <header>Host</header> to determine which server the request should be routed to.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	46 If its value does not match any server name,
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	47 or the request does not contain this header field at all,
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	48 then nginx will route the request to the default server for this port.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	49 In the configuration above, the default server is the first
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	50 one—which is nginx’s standard default behaviour.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	51 It can also be set explicitly which server should be default,
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	52 with the <literal>default_server</literal> parameter
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	53 in the <link doc="ngx_http_core_module.xml" id="listen"/> directive:
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	54 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	55 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	56 listen 80 <b>default_server</b>;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	57 server_name example.net www.example.net;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	58 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	59 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	60 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	61
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	62 <note>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	63 The <literal>default_server</literal> parameter has been available since
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	64 version 0.8.21.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	65 In earlier versions the <literal>default</literal> parameter should be used
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	66 instead.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	67 </note>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	68 Note that the default server is a property of the listen port
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	69 and not of the server name.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	70 More about this later.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	71 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	72
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	73 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	74
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	75
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 74 diff changeset	76 <section id="how_to_prevent_undefined_server_names"
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	77 name="How to prevent processing requests with undefined server names">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	78
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	79 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	80 If requests without the <header>Host</header> header field should not be
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	81 allowed, a server that just drops the requests can be defined:
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	82 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	83 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	84 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	85 server_name "";
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	86 return 444;
73 6327603448e2 Updated the "How to prevent processing requests with undefined server names" Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	87 }
6327603448e2 Updated the "How to prevent processing requests with undefined server names" Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	88 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	89 Here, the server name is set to an empty string that will match
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	90 requests without the <header>Host</header> header field,
73 6327603448e2 Updated the "How to prevent processing requests with undefined server names" Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	91 and a special nginx’s non-standard code 444
6327603448e2 Updated the "How to prevent processing requests with undefined server names" Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	92 is returned that closes the connection.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	93 <note>
73 6327603448e2 Updated the "How to prevent processing requests with undefined server names" Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	94 Since version 0.8.48, this is the default setting for the
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	95 server name, so the <literal>server_name ""</literal> can be omitted.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	96 In earlier versions, the machine’s <i>hostname</i> was used as
73 6327603448e2 Updated the "How to prevent processing requests with undefined server names" Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	97 a default server name.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	98 </note>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	99 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	100
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	101 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	102
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	103
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 74 diff changeset	104 <section id="mixed_name_ip_based_servers"
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	105 name="Mixed name-based and IP-based virtual servers">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	106
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	107 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	108 Let’s look at a more complex configuration
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	109 where some virtual servers listen on different addresses:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	110 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	111 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	112 listen 192.168.1.1:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	113 server_name example.org www.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	114 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	115 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	116
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	117 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	118 listen 192.168.1.1:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	119 server_name example.net www.example.net;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	120 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	121 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	122
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	123 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	124 listen 192.168.1.2:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	125 server_name example.com www.example.com;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	126 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	127 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	128 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	129 In this configuration, nginx first tests the IP address and port
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	130 of the request against the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	131 <link doc="ngx_http_core_module.xml" id="listen"/> directives
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	132 of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	133 <link doc="ngx_http_core_module.xml" id="server"/> blocks.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	134 It then tests the <header>Host</header>
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	135 header field of the request against the
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	136 <link doc="ngx_http_core_module.xml" id="server_name"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	137 entries of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	138 <link doc="ngx_http_core_module.xml" id="server"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	139 blocks that matched
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	140 the IP address and port.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	141 If the server name is not found, the request will be processed by
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	142 the default server.
593 130fad6dc1b4 Replaced the uses of "url" element with "literal". Ruslan Ermilov <ru@nginx.com> parents: 589 diff changeset	143 For example, a request for <literal>www.example.com</literal> received on
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	144 the 192.168.1.1:80 port will be handled by the default server
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	145 of the 192.168.1.1:80 port, i.e., by the first server,
593 130fad6dc1b4 Replaced the uses of "url" element with "literal". Ruslan Ermilov <ru@nginx.com> parents: 589 diff changeset	146 since there is no <literal>www.example.com</literal> defined for this port.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	147 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	148
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	149 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	150 As already stated, a default server is a property of the listen port,
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	151 and different default servers may be defined for different ports:
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	152 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	153 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	154 listen 192.168.1.1:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	155 server_name example.org www.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	156 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	157 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	158
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	159 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	160 listen 192.168.1.1:80 <b>default_server</b>;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	161 server_name example.net www.example.net;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	162 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	163 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	164
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	165 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	166 listen 192.168.1.2:80 <b>default_server</b>;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	167 server_name example.com www.example.com;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	168 ...
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	169 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	170 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	171
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	172 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	173
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	174 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	175
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	176
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 74 diff changeset	177 <section id="simple_php_site_configuration"
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	178 name="A simple PHP site configuration">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	179
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	180 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	181 Now let’s look at how nginx chooses a <i>location</i> to process a request
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	182 for a typical, simple PHP site:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	183 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	184 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	185 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	186 server_name example.org www.example.org;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	187 root /data/www;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	188
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	189 location / {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	190 index index.html index.php;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	191 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	192
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	193 location ~* \.(gif\|jpg\|png)$ {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	194 expires 30d;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	195 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	196
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	197 location ~ \.php$ {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	198 fastcgi_pass localhost:9000;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	199 fastcgi_param SCRIPT_FILENAME
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	200 $document_root$fastcgi_script_name;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	201 include fastcgi_params;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	202 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	203 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	204 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	205
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	206 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	207
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	208 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	209 nginx first searches for the most specific prefix location given by
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	210 literal strings regardless of the listed order.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	211 In the configuration above
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	212 the only prefix location is “<literal>/</literal>” and since it matches
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	213 any request it will be used as a last resort.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	214 Then nginx checks locations given by
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	215 regular expression in the order listed in the configuration file.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	216 The first matching expression stops the search and nginx will use this
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	217 location.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	218 If no regular expression matches a request, then nginx uses
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	219 the most specific prefix location found earlier.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	220 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	221
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	222 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	223 Note that locations of all types test only a URI part of request line
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	224 without arguments.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	225 This is done because arguments in the query string may be given in
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	226 several ways, for example:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	227 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	228 /index.php?user=john&page=1
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	229 /index.php?page=1&user=john
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	230 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	231 Besides, anyone may request anything in the query string:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	232 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	233 /index.php?page=1&something+else&user=john
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	234 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	235
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	236 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	237
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	238 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	239 Now let’s look at how requests would be processed
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	240 in the configuration above:
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	241 <list type="bullet" compact="no">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	242
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	243 <listitem>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	244 A request “<literal>/logo.gif</literal>” is matched by the prefix location
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	245 “<literal>/</literal>” first and then by the regular expression
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	246 “<literal>\.(gif\|jpg\|png)$</literal>”,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	247 therefore, it is handled by the latter location.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	248 Using the directive “<literal>root /data/www</literal>” the request
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	249 is mapped to the file <path>/data/www/logo.gif</path>, and the file
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	250 is sent to the client.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	251 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	252
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	253 <listitem>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	254 A request “<literal>/index.php</literal>” is also matched by the prefix location
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	255 “<literal>/</literal>” first and then by the regular expression
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	256 “<literal>\.(php)$</literal>”.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	257 Therefore, it is handled by the latter location
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	258 and the request is passed to a FastCGI server listening on localhost:9000.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	259 The
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	260 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_param"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	261 directive sets the FastCGI parameter
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	262 <literal>SCRIPT_FILENAME</literal> to “<literal>/data/www/index.php</literal>”,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	263 and the FastCGI server executes the file.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	264 The variable <var>$document_root</var> is equal to
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	265 the value of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	266 <link doc="ngx_http_core_module.xml" id="root"/>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	267 directive and the variable <var>$fastcgi_script_name</var> is equal to
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	268 the request URI, i.e. “<literal>/index.php</literal>”.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	269 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	270
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	271 <listitem>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	272 A request “<literal>/about.html</literal>” is matched by the prefix location
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	273 “<literal>/</literal>” only, therefore, it is handled in this location.
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	274 Using the directive “<literal>root /data/www</literal>” the request is mapped
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	275 to the file <path>/data/www/about.html</path>, and the file is sent
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	276 to the client.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	277 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	278
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	279 <listitem>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	280 Handling a request “<literal>/</literal>” is more complex.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	281 It is matched by the prefix location “<literal>/</literal>” only,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	282 therefore, it is handled by this location.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	283 Then the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	284 <link doc="ngx_http_index_module.xml" id="index"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	285 directive tests for the existence
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	286 of index files according to its parameters and
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	287 the “<literal>root /data/www</literal>” directive.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	288 If the file <path>/data/www/index.html</path> does not exist,
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	289 and the file <path>/data/www/index.php</path> exists,
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	290 then the directive does an internal redirect to “<literal>/index.php</literal>”,
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	291 and nginx searches the locations again
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	292 as if the request had been sent by a client.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	293 As we saw before, the redirected request will eventually be handled
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	294 by the FastCGI server.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	295 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	296
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	297 </list>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	298
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	299 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	300
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	301 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	302
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	303 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/request_processing.xml @ 3083:3b5594157fab