Config variable inheritance: docs and rules

Francis Daly francis at
Tue Apr 3 15:52:03 UTC 2012

On Tue, Apr 03, 2012 at 02:13:57PM +0100, Jonathan Matthews wrote:

Hi there,

> seems to contain some
> information I've not found explicitly stated anywhere else: that
> config variable inheritance is an all or nothing mechanism. Have I
> missed some docs somewhere?

That thread refers to configuration directives, not variables.

The difference might not matter, but for clarity it's worth making sure
that we all understand the same thing.

In the above thread, the (wrong) expectation was that "fastcgi_param"
at one level would add to "fastcgi_param" from an enclosing level. In
fact, nginx doesn't add between levels.

That is how nginx configuration works.

Each request is handled by exactly one location.

Only the configuration in that location, and inherited into that location,
matters. Inheritance is global > http > server > location.

If a directive is used in that location, it overrides any
might-have-been-inherited values for that directive.

This is as true for single-valued directives like "root" as it is for
multi-valued directives like "fastcgi_param".

Whether a particular directive can be inherited depends on the module
that processes it -- which means "depends on the documentation". But if
it *can* be inherited, it should follow the above rules. (Or it's a bug.)

The rest of your mail talks specifically about defining variables;
I'm talking about directives. Someone else may be able to explain the
variable rules; if you do mean "directives", then the above should make
it clear what the answer in each case is.

There are some subtleties about what exactly is "a request"; and what
locations are involved when "if" is used; and how nested locations work.

But for trying to find what configuration applies to a particular
incoming http request, the "inherit or replace, but never add" rule
makes it straightforward to understand.

Francis Daly        francis at

More information about the nginx mailing list