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

annotate xml/en/docs/http/request_processing.xml @ 490:9913f1d51c07

Replaced "nginx" domain names with example domains.

author	Ruslan Ermilov <ru@nginx.com>
date	Thu, 19 Apr 2012 12:30:24 +0000
parents	6135f3c95bf6
children	3481a91d46ab

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

Mercurial > hg > nginx-site

annotate xml/en/docs/http/request_processing.xml @ 490:9913f1d51c07