Why use the location directive?
The location directive enables us to divide up the content according to “folder” like paths. As you can use plain text and regular expressions it is powerful and subtle.
Location enables:
- Different technologies to be aggregated.
- Different types of content to be served.
- Multiple folders to be used. Some businesses use this to enable pseudo “vanity URLs” for clients.
- Multiple services to be aggregated so they appear as a single coherent whole.
One might think it is relatively simple to define a folder like structure and then implement this. However there are intricacies that determine how the location definition is processed. The directive is actually composed of two parts:
- An optional modifier
- The prefix path or regular expression itself
We should expect multiple locations to be defined. Certainly on the host computer, but possibly within individual configuration files. Debian and Ubuntu use a “sites-enabled/sites-available” structure that means that many files have to be inspected to work out the actual result.
How to use the optional modifier?
The option modifiers are:
| Modifier | Processing Order | What is supposed to happen |
| None | 1 | This means the following path will be treated as a plain text prefix. So / means all paths. /app means everything underneath /app e.g. /app/v1, /app/v2 , /app/help. ACCEPT the longest matching path (there may be a number of possibilities), and REMEMBER it. Then proceed to check the regular expression modifier paths (order = 2 in this table). If a regular expression matches use this in preference to the REMEMBERED plain text prefix |
| = | 1 | treat the following path as plain text and accept ONLY if it matches exactly. If a match is found DON’T search for any other matching paths |
| ^~ | 1 | treat the following path as plain text. If the longest matching prefix path has this modifier DON’T search any of the regular expressions. i.e. Ignore the processing order 2. |
| ~ | 2 | treat the following path as a CASE SENSITIVE regular expression. |
| ~* | 2 | treat the following path as a CASE INSENSITIVE regular expression |
Wrinkles to watch for
- Location blocks can conflict with one another. The block nginx picks may not be the one you want.
- The location block may have or omit a root directive.
- The processing order explained above can mean that the expected location block isn’t the one nginx actually uses.
- The optional modifier can mislead. It looks somewhat like regular expression type syntax.
- Syntactically correct regular expressions may not produce the results you want.
- Capture blocks (referred afterwards as $1, $2 etc.) in the regular expressions can make the effects harder to predict.
The interplay amongst multiple location blocks with plain text and regular expressions can be subtle.
How to debug?
There are basic questions that afflict most cloud engineers trying to get “their configuration to work”. The engineer needs an answer to
- Is the configuration correct?
- Which parts of the configuration may be giving problems.
- Are one or more services alive or playing dead?
We’ve designed the configuration clinic to help you separate these. Pasting your configuration file into the diagnosis will
- enable you to see the structure of the configuration file without the complexities that may be required in production by real services
- provide a pared back configuration file that you can test with a real copy of nginx and browser.
The principle is that we will get nginx to return codes according to which location block has been matched and used. So you can send a list of URLs to the webserver and monitor the returned codes.
Insights from others
Watch this space.
What directives are typically seen alongside location?
try_files
proxy_pass
root