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

annotate xml/en/docs/http/request_processing.xml @ 580:be54c443235a

Added copyright markers to documentation sources.

author	Ruslan Ermilov <ru@nginx.com>
date	Tue, 10 Jul 2012 12:59:42 +0000
parents	3481a91d46ab
children	764fbac1b8b4

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"
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	11 author="Igor Sysoev"
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	12 editor="Brian Mercer">
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	13
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 74 diff changeset	14 <section name="Name-based virtual servers">
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	15
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	16 <para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	17 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	18 Let’s start with a simple configuration
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	19 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	20 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	21 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	22 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	23 server_name example.org www.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	24 ...
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 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	28 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	29 server_name example.net www.example.net;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	30 ...
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 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	34 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	35 server_name example.com www.example.com;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	36 ...
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 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	39
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	40 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	41
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	42 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	43 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	44 <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	45 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	46 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	47 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	48 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	49 one—which is nginx’s standard default behaviour.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	50 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	51 with the <literal>default_server</literal> parameter
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	52 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	53 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	54 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	55 listen 80 <b>default_server</b>;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	56 server_name example.net www.example.net;
0 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 }
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	59 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	60
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	61 <note>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	62 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	63 version 0.8.21.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	64 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	65 instead.
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	66 </note>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	67 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	68 and not of the server name.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	69 More about this later.
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	70 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	71
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	72 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	73
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	74
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 74 diff changeset	75 <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	76 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	77
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	78 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	79 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	80 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	81 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	82 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	83 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	84 server_name "";
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	85 return 444;
73 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 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	88 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	89 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	90 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	91 is returned that closes the connection.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	92 <note>
73 6327603448e2 Updated the "How to prevent processing requests with undefined server names" Ruslan Ermilov <ru@nginx.com> parents: 50 diff changeset	93 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	94 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	95 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	96 a default server name.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	97 </note>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	98 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	99
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	100 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	101
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	102
121 49443032011c Unified <section> syntax for "article" and "module" documents. Ruslan Ermilov <ru@nginx.com> parents: 74 diff changeset	103 <section id="mixed_name_ip_based_servers"
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	104 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	105
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	106 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	107 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	108 where some virtual servers listen on different addresses:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	109 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	110 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	111 listen 192.168.1.1:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	112 server_name example.org www.example.org;
0 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 }
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 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	117 listen 192.168.1.1:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	118 server_name example.net www.example.net;
0 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 }
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 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	123 listen 192.168.1.2:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	124 server_name example.com www.example.com;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	125 ...
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 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	128 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	129 of the request against the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	130 <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	131 of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	132 <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	133 It then tests the <header>Host</header>
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	134 header field of the request against the
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	135 <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	136 entries of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	137 <link doc="ngx_http_core_module.xml" id="server"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	138 blocks that matched
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	139 the IP address and port.
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>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	149 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	150 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	151 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	152 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	153 listen 192.168.1.1:80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	154 server_name example.org www.example.org;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	155 ...
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 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	159 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	160 server_name example.net www.example.net;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	161 ...
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 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	165 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	166 server_name example.com www.example.com;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	167 ...
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 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	170
0 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"
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 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>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	180 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	181 for a typical, simple PHP site:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	182 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	183 server {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	184 listen 80;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	185 server_name example.org www.example.org;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	186 root /data/www;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	187
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	188 location / {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	189 index index.html index.php;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	190 }
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 location ~* \.(gif\|jpg\|png)$ {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	193 expires 30d;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	194 }
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 location ~ \.php$ {
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	197 fastcgi_pass localhost:9000;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	198 fastcgi_param SCRIPT_FILENAME
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	199 $document_root$fastcgi_script_name;
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	200 include fastcgi_params;
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	201 }
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 </programlisting>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	204
0 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>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	208 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	209 literal strings regardless of the listed order.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	210 In the configuration above
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	211 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	212 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	213 Then nginx checks locations given by
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	214 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	215 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	216 location.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	217 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	218 the most specific prefix location found earlier.
0 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
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	221 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	222 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	223 without arguments.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	224 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	225 several ways, for example:
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	226 <programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	227 /index.php?user=john&page=1
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	228 /index.php?page=1&user=john
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	229 </programlisting>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	230 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	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>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	234
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	235 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	236
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	237 <para>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	238 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	239 in the configuration above:
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	240 <list type="bullet" compact="no">
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>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	243 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	244 “<literal>/</literal>” first and then by the regular expression
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	245 “<literal>\.(gif\|jpg\|png)$</literal>”,
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	246 therefore, it is handled by the latter location.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	247 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	248 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	249 is sent to the client.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	250 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	251
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	252 <listitem>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	253 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	254 “<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	255 “<literal>\.(php)$</literal>”.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	256 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	257 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	258 The
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	259 <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	260 directive sets the FastCGI parameter
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	261 <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	262 and the FastCGI server executes the file.
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	263 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	264 the value of the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	265 <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	266 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	267 the request URI, i.e. “<literal>/index.php</literal>”.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	268 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	269
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	270 <listitem>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	271 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	272 “<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	273 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	274 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	275 to the client.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	276 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	277
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	278 <listitem>
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	279 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	280 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	281 therefore, it is handled by this location.
271 4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	282 Then the
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	283 <link doc="ngx_http_index_module.xml" id="index"/>
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	284 directive tests for the existence
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	285 of index files according to its parameters and
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	286 the “<literal>root /data/www</literal>” directive.
3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	287 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	288 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	289 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	290 and nginx searches the locations again
4c6d2c614d2c Cleaned up XML tag mess: Ruslan Ermilov <ru@nginx.com> parents: 148 diff changeset	291 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	292 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	293 by the FastCGI server.
461 6135f3c95bf6 Unified markup for lists. Ruslan Ermilov <ru@nginx.com> parents: 271 diff changeset	294 </listitem>
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	295
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	296 </list>
521 3481a91d46ab Minor revision in preparation for translation. Ruslan Ermilov <ru@nginx.com> parents: 490 diff changeset	297
0 61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	298 </para>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	299
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	300 </section>
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	301
61e04fc01027 Initial import of the nginx.org website. Ruslan Ermilov <ru@nginx.com> parents: diff changeset	302 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/http/request_processing.xml @ 580:be54c443235a