Mercurial > hg > nginx-site

annotate xml/en/docs/http/request_processing.xml @ 74:e9948ec6286b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Removed the pre-0.7.11 tip for "How to prevent processing requests with undefined server names".
author Ruslan Ermilov <ru@nginx.com>
date Mon, 10 Oct 2011 09:39:11 +0000
parents 6327603448e2
children 49443032011c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <article title="How nginx processes a request"
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
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 <section title="Name-based virtual servers">
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&rsquo;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;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 server_name nginx.org www.nginx.org;
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;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 server_name nginx.net www.nginx.net;
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;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32 server_name nginx.com www.nginx.com;
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&rsquo;s header line
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
40 &ldquo;Host&rdquo; 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 &ldquo;Host&rdquo; 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&mdash;which is nginx&rsquo;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,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 you may set it explicitly with the <dirname>default_server</dirname> parameter
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 in the <dirname>listen</dirname> directive:
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>;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53 server_name nginx.net www.nginx.net;
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>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59 The <dirname>default_server</dirname> parameter has been available since
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 version 0.8.21.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61 In earlier versions the <dirname>default</dirname> parameter should be used
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
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72 <section name="how_to_prevent_undefined_server_names"
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 title="How to prevent processing requests with undefined server names">
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
6327603448e2 Updated the "How to prevent processing requests with undefined server names"
Ruslan Ermilov <ru@nginx.com>
parents: 50
diff changeset
92 server name, so the <code>server_name ""</code> can be omitted.
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
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
100 <section name="mixed_name_ip_based_servers"
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101 title="Mixed name-based and IP-based virtual servers">
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&rsquo;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;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110 server_name nginx.org www.nginx.org;
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;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
116 server_name nginx.net www.nginx.net;
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;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
122 server_name nginx.com www.nginx.com;
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
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
128 of the request against the <dirname>listen</dirname> directives
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
129 of the <dirname>server</dirname> blocks. It then tests the &ldquo;Host&rdquo;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
130 header line of the request against the <dirname>server_name</dirname>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131 entries of the <dirname>server</dirname> blocks that matched
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132 the IP address and port.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
134 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
135 the default server.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
136 For example, a request for <url>www.nginx.com</url> received on
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
137 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
138 of the 192.168.1.1:80 port, i.e., by the first server,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 since there is no <url>www.nginx.com</url> defined for this port.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143 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
144 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
145
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148 listen 192.168.1.1:80;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
149 server_name nginx.org www.nginx.org;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
150 ...
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
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 default_server;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155 server_name nginx.net www.nginx.net;
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.2:80 default_server;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161 server_name nginx.com www.nginx.com;
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 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 </section>
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 <section name="simple_php_site_configuration"
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
171 title="A simple PHP site configuration">
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 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
174 Now let&rsquo;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
175 for a typical, simple PHP site:
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
177 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
178 server {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
179 listen 80;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 server_name nginx.org www.nginx.org;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
181 root /data/www;
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 location / {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184 index index.html index.php;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
185 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
186
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
187 location ~* \.(gif|jpg|png)$ {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
188 expires 30d;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
189 }
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 location ~ \.php$ {
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
192 fastcgi_pass localhost:9000;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
193 fastcgi_param SCRIPT_FILENAME
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 $document_root$fastcgi_script_name;
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
195 include fastcgi_params;
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 }
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
198 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
199 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
200
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
201 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
202 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
203 regardless of the listed order. In the configuration above
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
204 the only literal location is <path>/</path> and since it matches
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
205 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
206 Then nginx checks locations given by
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
207 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
208 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
209 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
210 the most specific literal location found earlier.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
211 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
212
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
213 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
214 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
215 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
216 several ways, for example:
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
217
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
218 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
219 /index.php?user=john&amp;page=1
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
220 /index.php?page=1&amp;user=john
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
221 </programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
222
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
223 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
224
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
225 <programlisting>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
226 /index.php?page=1&amp;something+else&amp;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 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
230 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
231 Now let&rsquo;s look at how requests would be processed
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
232 in the configuration above:
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
233
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
234 <list>
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 <item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
237 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
238 A request <path>/logo.gif</path> is matched by the literal location
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
239 <dirname>/</dirname> first and then by the regular expression
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
240 <dirname>\.(gif|jpg|png)$</dirname>,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241 therefore, it is handled by the latter location.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242 Using the directive <dirname>root&nbsp;/data/www</dirname> the request
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 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
244 is sent to the client.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
245 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
246 </item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
248 <item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
249 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
250 A request <path>/index.php</path> is also matched by the literal location
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
251 <dirname>/</dirname> first and then by the regular expression
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
252 <dirname>\.(php)$</dirname>. Therefore, it is handled by the latter location
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
253 and the request is passed to a FastCGI server listening on localhost:9000.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
254 The <dirname>fastcgi_param</dirname> directive sets the FastCGI parameter
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
255 SCRIPT_FILENAME to <path>/data/www/index.php</path>,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
256 and the FastCGI server executes the file.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
257 The variable $document_root is equal to
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
258 the value of the <dirname>root</dirname> directive and
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
259 the variable $fastcgi_script_name is equal to the request URI,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
260 i.e. <path>/index.php</path>.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
261 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
262 </item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
263
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
264 <item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
265 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
266 A request <path>/about.html</path> is matched by the literal location
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
267 <dirname>/</dirname> only, therefore, it is handled in this location.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
268 Using the directive <dirname>root /data/www</dirname> the request is mapped
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
269 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
270 to the client.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
271 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
272 </item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
273
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
274 <item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
275 <para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
276 Handling a request <path>/</path> is more complex.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
277 It is matched by the literal location <dirname>/</dirname> only,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
278 therefore, it is handled by this location.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
279 Then the <dirname>index</dirname> directive tests for the existence
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
280 of an index file according to its parameters and
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
281 the <dirname>root&nbsp;/data/www</dirname> directive.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
282 If a file <path>/data/www/index.php</path> exists,
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
283 then the directive does an internal redirect to <path>/index.php</path>, and
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
284 nginx searches the locations again as if the request had been sent by a client.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
285 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
286 by the FastCGI server.
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
287 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
288 </item>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
289
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
290 </list>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
291 </para>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
292
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
293 </section>
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
294
61e04fc01027 Initial import of the nginx.org website.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
295 </article>