Nginx Learning (4)

Configuring NGINX Plus as a Web Server

At a high level, configuring NGINX Plus as a web server is a matter of defining which URLs it handles and how it processes HTTP requests for resources at those URLs. At a lower level, the configuration defines a set of virtual servers that control the processing of requests for particular domains or IP addresses.

Setting Up Virtual Servers

If a port is omitted, the standard port is used. Likewise, if an address is omitted, the server listens on all addresses.

If there are several servers that match the IP address and port of the request, NGINX Plus tests the request’s Host header field against the server_name directives in the server blocks.

The parameter to server_name can be a full (exact) name, a wildcard, or a regular expression. A wildcard is a character string that includes the asterisk (*) at its beginning, end, or both; the asterisk matches any sequence of characters.

If the Host header field does not match a server name, NGINX Plus routes the request to the default server for the port on which the request arrived. The default server is the first one listed in the nginx.conf file, unless you include the default_server parameter to the listen directive to explicitly designate a server as the default.

Configuring Locations

There are two types of parameter to the location directive: prefix strings (pathnames) and regular expressions. For a request URI to match a prefix string, it must start with the prefix string.

A regular expression is preceded with the tilde (~) for case-sensitive matching, or the tilde-asterisk (~*) for case-insensitive matching.

To find the location that best matches a URI, NGINX Plus first compares the URI to the locations with a prefix string. It then searches the locations with a regular expression.

TODO

server {
    location /images/ {
        root /data;
    }

    location / {
        proxy_pass http://www.example.com;
    }
}

The root directive specifies the file system path in which to search for the static files to serve. The request URI associated with the location is appended to the path to obtain the full name of the static file to serve. In the example above, in response to a request for /images/example.png, NGINX Plus delivers the file /data/images/example.png.

Returning Specific Status Codes

The first parameter of return is a response code. The optional second parameter can be the URL of a redirect (for codes 301, 302, 303, and 307) or the text to return in the response body.

location /permanently/moved/url {
    return 301 http://www.example.com/moved/here;
}

Rewriting URIs in Requests

A request URI can be modified multiple times during request processing through the use of the rewrite directive, which has one optional and two required parameters. The first (required) parameter is the regular expression that the request URI must match. The second parameter is the URI to substitute for the matching URI. The optional third parameter is a flag that can halt processing of further rewrite directives or send a redirect (code 301 or 302).

关于last和break

(ref: https://serverfault.com/questions/131474/nginx-url-rewriting-difference-between-break-and-last)

You may have different sets of rewrite rules for different locations. When rewrite module meets last, it stops processing the current set and the rewritten request is passed once again to find the appropriate location (and the new set of rewriting rules). If the rule ends with break, the rewriting also stops, but the rewritten request is not passed to another location.

That is, if there are two locations: loc1 and loc2, and there's a rewriting rule in loc1 that changes loc1 to loc2 AND ends with last, the request will be rewritten and passed to location loc2. If the rule ends with break, it will belong to location loc1.

Rewriting HTTP Responses

Sometimes you need to rewrite or change the content in an HTTP response, substituting one string for another. You can use the sub_filter directive to define the rewrite to apply.

Another example changes the method from http:// to http_s_:// and replaces the localhost address to the host name from the request header field. The sub_filter_once directive tells NGINX to apply sub_filter directives consecutively within a location:

location / {
    sub_filter     'href="http://127.0.0.1:8080/'    'href="https://$host/';
    sub_filter     'img src="http://127.0.0.1:8080/' 'img src="https://$host/';
    sub_filter_once on;
}

Note that the part of the response already modified with the sub_filter will not be replaced again if another sub_filter match occurs.

Handling Errors

In the following example, when NGINX Plus cannot find a page, it substitutes code 301 for code 404, and redirects the client to http:/example.com/new/path.html. This configuration is useful when clients are still trying to access a page at its old URI.

location /old/path.html {
    error_page 404 =301 http:/example.com/new/path.html;
}