Mercurial > hg > nginx-site
view xml/en/docs/http/request_processing.xml @ 322:099ee546b04e
Revision.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 16 Jan 2012 13:42:12 +0000 |
parents | 4c6d2c614d2c |
children | 6135f3c95bf6 |
line wrap: on
line source
<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> <article name="How nginx processes a request" link="/en/docs/http/request_processing.html" lang="en" author="Igor Sysoev" editor="Brian Mercer"> <section name="Name-based virtual servers"> <para> nginx first decides which <i>server</i> should process the request. Let’s start with a simple configuration where all three virtual servers listen on port *:80: <programlisting> server { listen 80; server_name nginx.org www.nginx.org; ... } server { listen 80; server_name nginx.net www.nginx.net; ... } server { listen 80; server_name nginx.com www.nginx.com; ... } </programlisting> </para> <para> In this configuration nginx tests only the request’s header line “Host” to determine which server the request should be routed to. If the “Host” header line does not match any server name, or the request does not contain this line at all, then nginx will route the request to the default server. In the configuration above, the default server is the first one—which is nginx’s standard default behaviour. If you do not want the first server listed to be the default server, you may set it explicitly with the <literal>default_server</literal> parameter in the <link doc="ngx_http_core_module.xml" id="listen"/> directive: <programlisting> server { listen 80 <b>default_server</b>; server_name nginx.net www.nginx.net; ... } </programlisting> <note> The <literal>default_server</literal> parameter has been available since version 0.8.21. In earlier versions the <literal>default</literal> parameter should be used instead. </note> Note that the default server is a property of the listen port and not of the server name. More about this later. </para> </section> <section id="how_to_prevent_undefined_server_names" name="How to prevent processing requests with undefined server names"> <para> If you do not want to process requests without the <header>Host</header> header line, you may define a server that just drops the requests: <programlisting> server { listen 80; server_name ""; return 444; } </programlisting> Here, the server name is set to an empty string which will match requests without the <header>Host</header> header line, and a special nginx’s non-standard code 444 is returned that closes the connection. Since version 0.8.48, this is the default setting for the server name, so the <literal>server_name ""</literal> can be omitted. In earlier versions, the machine's <i>hostname</i> was used as a default server name. </para> </section> <section id="mixed_name_ip_based_servers" name="Mixed name-based and IP-based virtual servers"> <para> Let’s look at a more complex configuration where some virtual servers listen on different addresses: <programlisting> server { listen 192.168.1.1:80; server_name nginx.org www.nginx.org; ... } server { listen 192.168.1.1:80; server_name nginx.net www.nginx.net; ... } server { listen 192.168.1.2:80; server_name nginx.com www.nginx.com; ... } </programlisting> In this configuration, nginx first tests the IP address and port of the request against the <link doc="ngx_http_core_module.xml" id="listen"/> directives of the <link doc="ngx_http_core_module.xml" id="server"/> blocks. It then tests the “Host” header line of the request against the <link doc="ngx_http_core_module.xml" id="server_name"/> entries of the <link doc="ngx_http_core_module.xml" id="server"/> blocks that matched the IP address and port. If the server name is not found, the request will be processed by the default server. For example, a request for <url>www.nginx.com</url> received on the 192.168.1.1:80 port will be handled by the default server of the 192.168.1.1:80 port, i.e., by the first server, since there is no <url>www.nginx.com</url> defined for this port. </para> <para> As already stated, a default server is a property of the listen port and different default servers may be defined for different listen ports: <programlisting> server { listen 192.168.1.1:80; server_name nginx.org www.nginx.org; ... } server { listen 192.168.1.1:80 default_server; server_name nginx.net www.nginx.net; ... } server { listen 192.168.1.2:80 default_server; server_name nginx.com www.nginx.com; ... } </programlisting> </para> </section> <section id="simple_php_site_configuration" name="A simple PHP site configuration"> <para> Now let’s look at how nginx chooses a <i>location</i> to process a request for a typical, simple PHP site: <programlisting> server { listen 80; server_name nginx.org www.nginx.org; root /data/www; location / { index index.html index.php; } location ~* \.(gif|jpg|png)$ { expires 30d; } location ~ \.php$ { fastcgi_pass localhost:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } } </programlisting> </para> <para> nginx first searches for the most specific location given by literal strings regardless of the listed order. In the configuration above the only literal location is “<literal>/</literal>” and since it matches any request it will be used as a last resort. Then nginx checks locations given by regular expression in the order listed in the configuration file. The first matching expression stops the search and nginx will use this location. If no regular expression matches a request, then nginx uses the most specific literal location found earlier. </para> <para> Note that locations of all types test only a request URI part without a query string. This is done because arguments in the query string may be given in several ways, for example: <programlisting> /index.php?user=john&page=1 /index.php?page=1&user=john </programlisting> Besides, anyone may request anything in the query string: <programlisting> /index.php?page=1&something+else&user=john </programlisting> </para> <para> Now let’s look at how requests would be processed in the configuration above: <list> <item> <para> A request “<literal>/logo.gif</literal>” is matched by the literal location “<literal>/</literal>” first and then by the regular expression “<literal>\.(gif|jpg|png)$</literal>”, therefore, it is handled by the latter location. Using the directive “<literal>root /data/www</literal>” the request is mapped to a file <path>/data/www/logo.gif</path>, and the file is sent to the client. </para> </item> <item> <para> A request “<literal>/index.php</literal>” is also matched by the literal location “<literal>/</literal>” first and then by the regular expression “<literal>\.(php)$</literal>”. Therefore, it is handled by the latter location and the request is passed to a FastCGI server listening on localhost:9000. The <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_param"/> directive sets the FastCGI parameter SCRIPT_FILENAME to “<literal>/data/www/index.php</literal>”, and the FastCGI server executes the file. The variable $document_root is equal to the value of the <link doc="ngx_http_core_module.xml" id="root"/> directive and the variable $fastcgi_script_name is equal to the request URI, i.e. “<literal>/index.php</literal>”. </para> </item> <item> <para> A request “<literal>/about.html</literal>” is matched by the literal location “<literal>/</literal>” only, therefore, it is handled in this location. Using the directive “<literal>root /data/www</literal>” the request is mapped to the file <path>/data/www/about.html</path>, and the file is sent to the client. </para> </item> <item> <para> Handling a request “<literal>/</literal>” is more complex. It is matched by the literal location “<literal>/</literal>” only, therefore, it is handled by this location. Then the <link doc="ngx_http_index_module.xml" id="index"/> directive tests for the existence of an index file according to its parameters and the “<literal>root /data/www</literal>” directive. If a file <path>/data/www/index.php</path> exists, then the directive does an internal redirect to “<literal>/index.php</literal>”, and nginx searches the locations again as if the request had been sent by a client. As we saw before, the redirected request will eventually be handled by the FastCGI server. </para> </item> </list> </para> </section> </article>