Various Prefixes for Ngxin’s Location Directive
Thursday, November 3rd, 2011Often we need to create short, more expressive URLs. If you are using Nginx as a reverse proxy, one easy way to create short URLs is to define different locations under the respective server directive and then do a permanent rewrite to the actual URL in the Nginx conf file as follows:
http { .... server { listen 80; server_name www.agilefaqs.com agilefaqs.com; server_name_in_redirect on; port_in_redirect on; location ^~ /training { rewrite ^ http://agilefaqs.com/a/long/url/$uri permanent; } location ^~ /coaching { rewrite ^ http://agilecoach.in$uri permanent; } location = /blog { rewrite ^ http://blogs.agilefaqs.com/show?action=posts permanent; } location / { root /path/to/static/web/pages; index index.html; } location ~* ^.+\.(gif|jpg|jpeg|png|css|js)$ { add_header Cache-Control public; expires max; root /path/to/static/content; } } } |
I’ve been using this feature of Nginx for over 2 years, but never actually fully understood the different prefixes for the location directive.
If you check Nginx’s documentation for the syntax of the location directive, you’ll see:
location [=|~|~*|^~|@] /uri/ { ... } |
The URI can be a literal string or a regular expression (regexp).
For regexps, there are two prefixes:
- “~” for case sensitive matching
- “~*” for case insensitive matching
If we have a list of locations using regexps, Nginx checks each location in the order its defined in the configuration file. The first regexp to match the requested url will stop the search. If no regexp matches are found, then it uses the longest matching literal string.
For example, if we have the following locations:
location ~* /.*php$ { rewrite ^ http://content.agilefaqs.com$uri permanent; } location ~ /.*blogs.* { rewrite ^ http://blogs.agilefaqs.com$uri permanent; } location /blogsin { rewrite ^ http://agilecoach.in/blog$uri permanent; } location /blogsinphp { root /path/to/static/web/pages; index index.html; } |
If the requested URL is http://agilefaqs.com/blogs/index.php, Nginx will permanently redirect the request to http://content.agilefaqs.com/blogs/index.php. Even though both regexps (/.*php$ and /.*blogs.*) match the requested URL, the first satisfying regexp (/.*php$) is picked and the search is terminated.
However let’s say the requested URL was http://agilefaqs.com/blogsinphp, Nginx will first consider /blogsin location and then /blogsinphp location. If there were more literal string locations, it would consider them as well. In this case, regexp locations would be skipped since /blogsinphp is the longest matching literal string.
If you want to slightly speed up this process, you should use the “=” prefix. .i.e.
location = /blogsinphp { root /path/to/static/web/pages; index index.html; } |
and move this location right at the top of other locations. By doing so, Nginx will first look at this location, if its an exact literal string match, it would stop right there without looking at any other location directives.
However note that if http://agilefaqs.com/my/blogsinphp is requested, none of the literal strings will match and hence the first regexp (/.*php$) would be picked up instead of the string literal.
And if http://agilefaqs.com/blogsinphp/my is requested, again, none of the literal strings will match and hence the first matching regexp (/.*blogs.*) is selected.
What if you don’t know the exact string literal, but you want to avoid checking all the regexps?
We can achieve this by using the “^~” prefix as follows:
location = /blogsin { rewrite ^ http://agilecoach.in/blog$uri permanent; } location ^~ /blogsinphp { root /path/to/static/web/pages; index index.html; } location ~* /.*php$ { rewrite ^ http://content.agilefaqs.com$uri permanent; } location ~ /.*blogs.* { rewrite ^ http://blogs.agilefaqs.com$uri permanent; } |
Now when we request http://agilefaqs.com/blogsinphp/my, Nginx checks the first location (= /blogsin), /blogsinphp/my is not an exact match. It then looks at (^~ /blogsinphp), its not an exact match, however since we’ve used ^~ prefix, this location is selected by discarding all the remaining regexp locations.
However if http://agilefaqs.com/blogsin is requested, Nginx will permanently redirect the request to http://agilecoach.in/blog/blogsin even without considering any other locations.
To summarize:
- Search stops if location with “=” prefix has an exact matching literal string.
- All remaining literal string locations are matched. If the location uses “^~” prefix, then regexp locations are not searched. The longest matching location with “^~” prefix is used.
- Regexp locations are matched in the order they are defined in the configuration file. Search stops on first matching regexp.
- If none of the regexp matches, the longest matching literal string location is used.
Even though the order of the literal string locations don’t matter, its generally a good practice to declare the locations in the following order:
- start with all the “=” prefix,
- followed by “^~” prefix,
- then all the literal string locations
- finally all the regexp locations (since the order matters, place them with the most likely ones first)
BTW adding a break directive inside any of the location directives has not effect.
