Opened 4 months ago

Last modified 4 months ago

#2310 accepted defect

Document behaviour for all config statements in nested location blocks

Reported by: taladar@… Owned by:
Priority: minor Milestone:
Component: documentation Version:
Keywords: Cc: taladar@…
uname -a:
nginx -V: The documentation on your website, presumably the latest version


From my understanding each request is only ever handled in a single top level location block and some, but not all statements are inherited in nested location blocks. Each location may also only have exactly one block.

Ideally this could be changed to actually allow for modularity and reduced duplication of statements but since this system is unlikely to change for backwards compatibility reasons it would at least be useful to know which statements need to be duplicated in every nested location block and which are inherited.

I ran into this issue when some location blocks that were only meant to disable password protection for specific domains also disabled the reverse proxy for those locations. Presumably proxy_pass is what this post calls a command type directive

Change History (1)

comment:1 by Maxim Dounin, 4 months ago

Status: newaccepted
Version: 1.19.x

Thanks for the ticket. In general, all nginx configuration directives are inherited from the previous levels (unless redefined at the current level). There are very few exceptions, notably:

  • The rewrite module directives: break, if, return, rewrite, set. The rewrite module directives behaviour is explicitly documented.
  • Directives which configure final location handling: proxy_pass, fastcgi_pass, grpc_pass, scgi_pass, uwsgi_pass, memcached_pass, perl, empty_gif, flv, mp4, stub_status. These directives are only allowed at location level and weren't subject to inheritance at all till introduction of nested locations. This is probably not documented good enough, though the concept is quite obvious.
  • The try_files directive. Not really sure this is how it should work though, and might be considered to be a bug (see ticket #86 and ticket #633).
  • Block-level directives which introduce additional configuration contexts: notably location itself, limit_except, if in location (which is also a rewrite module directive).

Most of these exceptions are believed to be more or less obvious and intuitive, though it indeed might make sense to document all this more explicitly.

Note: See TracTickets for help on using tickets.