Mercurial > hg > nginx-site
diff xml/en/docs/http/request_processing.xml @ 0:61e04fc01027
Initial import of the nginx.org website.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 11 Aug 2011 12:19:13 +0000 |
parents | |
children | 9d544687d02c |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/request_processing.xml @@ -0,0 +1,292 @@ +<!DOCTYPE digest SYSTEM "../../../../dtd/article.dtd"> + +<article title="How nginx processes a request" + link="/en/docs/http/request_processing.html" + lang="en" + author="Igor Sysoev" + editor="Brian Mercer"> + + +<section title="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 <dirname>default_server</dirname> parameter +in the <dirname>listen</dirname> directive: + +<programlisting> +server { + listen 80 <b>default_server</b>; + server_name nginx.net www.nginx.net; + ... +} +</programlisting> + +<note> +The <dirname>default_server</dirname> parameter has been available since +version 0.8.21. +In earlier versions the <dirname>default</dirname> 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 name="how_to_prevent_undefined_server_names" + title="How to prevent processing requests with undefined server names"> + +<para> +If you do not want to process requests with undefined “Host” +header lines, you may define a default server that just drops the requests: + +<programlisting> +server { + listen 80 default_server; + server_name _; + return 444; +} +</programlisting> + +We have chosen the non-existent domain name “_” +as the server name and returned nginx’s special non-standard +code 444 that closes the connection. +Note that you should set a name for this server, +otherwise nginx will use the <i>hostname</i>. +</para> + +</section> + + +<section name="mixed_name_ip_based_servers" + title="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 <dirname>listen</dirname> directives +of the <dirname>server</dirname> blocks. It then tests the “Host” +header line of the request against the <dirname>server_name</dirname> +entries of the <dirname>server</dirname> 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 name="simple_php_site_configuration" + title="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 <path>/</path> 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 <path>/logo.gif</path> is matched by the literal location +<dirname>/</dirname> first and then by the regular expression +<dirname>\.(gif|jpg|png)$</dirname>, +therefore, it is handled by the latter location. +Using the directive <dirname>root /data/www</dirname> 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 <path>/index.php</path> is also matched by the literal location +<dirname>/</dirname> first and then by the regular expression +<dirname>\.(php)$</dirname>. Therefore, it is handled by the latter location +and the request is passed to a FastCGI server listening on localhost:9000. +The <dirname>fastcgi_param</dirname> directive sets the FastCGI parameter +SCRIPT_FILENAME to <path>/data/www/index.php</path>, +and the FastCGI server executes the file. +The variable $document_root is equal to +the value of the <dirname>root</dirname> directive and +the variable $fastcgi_script_name is equal to the request URI, +i.e. <path>/index.php</path>. +</para> +</item> + +<item> +<para> +A request <path>/about.html</path> is matched by the literal location +<dirname>/</dirname> only, therefore, it is handled in this location. +Using the directive <dirname>root /data/www</dirname> 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 <path>/</path> is more complex. +It is matched by the literal location <dirname>/</dirname> only, +therefore, it is handled by this location. +Then the <dirname>index</dirname> directive tests for the existence +of an index file according to its parameters and +the <dirname>root /data/www</dirname> directive. +If a file <path>/data/www/index.php</path> exists, +then the directive does an internal redirect to <path>/index.php</path>, 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>