# Config directive inheritance: docs and rules (was: Config variable inheritance)

**URL:** <https://www.ruby-forum.com/t/config-directive-inheritance-docs-and-rules-was-config-variable-inheritance/218538>\
**Category:** NGINX\
**Created:** [April 3, 2012, 7:21pm UTC](https://www.ruby-forum.com/t/config-directive-inheritance-docs-and-rules-was-config-variable-inheritance/218538 "2012-04-03T19:21:06Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![luislavena](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/0ea827/32.png) [@luislavena](https://www.ruby-forum.com/u/luislavena)\
**Post date:** [April 3, 2012, 7:21pm UTC](https://www.ruby-forum.com/t/config-directive-inheritance-docs-and-rules-was-config-variable-inheritance/218538/1 "2012-04-03T19:21:06Z")

</div>

Hi all -

[Problem with inheriting fastcgi params - NGINX - Ruby-Forum](http://www.ruby-forum.com/topic/188742) seems to contain some  
information I’ve not found explicitly stated anywhere else: that  
config directive inheritance is an all or nothing mechanism. Have I  
missed some docs somewhere?

Following on from this, I’d like to understand if there’s anything I  
can reliably determine from a directive’s name about the impact that  
defining it will have on _other_ directives’ inheritability.

Can I, for instance, assume that defining an xyx\_ prefixed directive in  
a sub-scope will affect _only_ the inheritance of other xyz\_ prefixed  
directives? Or can there be inheritance side-effects between, say,  
directive “abc” and “def” that I can’t possibly determine without  
documentation or trial and error?

Equally, can I assume that _all_ xyz\_ prefixed directives will have  
their inheritance affected by the sub-scope definition of any _other_  
xyz\_ prefixed directive? Or are there examples where defining  
“xyz\_foo” does _not_ impact the inheritance of “xyz\_bar”?

I’m thinking specifically of proxy\_\* directives, whereas the thread I  
link to above is talking about multiple fastcgi\_param directives.  
Here, I’m interested in how, say, proxy\_set\_header affects the  
inheritance of higher scope’s proxy\_pass directive - i.e. where the  
prefix matches but they’re _not_ the same directive. Does nginx (core)  
derive or imply anything relating to the name-spacing of directives  
before (in my example) the proxy module sees the config, or is it  
entirely down to how each module implements the configuration  
aggregation/inheritance?

## Many thanks, Jonathan

Jonathan M.  
London, Oxford, UK  
[http://www.jpluscplusm.com/contact.html](http://www.jpluscplusm.com/contact.html)

---

<div class="post-metadata">

**Author:** ![jonathan2000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/fbc32d/32.png) [@jonathan2000](https://www.ruby-forum.com/u/jonathan2000)\
**Post date:** [April 4, 2012, 2:41pm UTC](https://www.ruby-forum.com/t/config-directive-inheritance-docs-and-rules-was-config-variable-inheritance/218538/2 "2012-04-04T14:41:14Z")

</div>

On Tue, Apr 03, 2012 at 06:20:13PM +0100, Jonathan M. wrote:

Hi there,

> [Problem with inheriting fastcgi params - NGINX - Ruby-Forum](http://www.ruby-forum.com/topic/188742) seems to contain some  
> information I’ve not found explicitly stated anywhere else: that  
> config directive inheritance is an all or nothing mechanism. Have I  
> missed some docs somewhere?

That refers to inheritance of a _single_ directive.

> Following on from this, I’d like to understand if there’s anything I  
> can reliably determine from a directive’s name about the impact that  
> defining it will have on _other_ directives’ inheritability.

Yes: it will have no impact on other directives.

> Can I, for instance, assume that defining an xyx\_ prefixed directive in  
> a sub-scope will affect _only_ the inheritance of other xyz\_ prefixed  
> directives?

No. It will affect no other xyz\_ prefixed directives.

It may make a difference to the _applicability_ of other directives –  
for example, if fastcgi\_pass is not set, then it doesn’t really matter  
whether fastcgi\_param is inherited or not, because it’s not going to be  
used. But fastcgi\_pass does not affect whether fastcgi\_param is  
inherited.

> Or can there be inheritance side-effects between, say,  
> directive “abc” and “def” that I can’t possibly determine without  
> documentation or trial and error?

No, it will have no impact on other directives.

> Equally, can I assume that _all_ xyz\_ prefixed directives will have  
> their inheritance affected by the sub-scope definition of any _other_  
> xyz\_ prefixed directive?

No: it will have no impact on other directives.

> Or are there examples where defining  
> “xyz\_foo” does _not_ impact the inheritance of “xyz\_bar”?

Yes: every example.

> I’m thinking specifically of proxy\_\* directives, whereas the thread I  
> link to above is talking about multiple fastcgi\_param directives.

Using a directive sets the value of that directive. It does not set the  
value of different directives.

“Not using” a directive means the value of that directive is either  
unset/default, or is the same value as the upper level.

> Here, I’m interested in how, say, proxy\_set\_header affects the  
> inheritance of higher scope’s proxy\_pass directive - i.e. where the  
> prefix matches but they’re _not_ the same directive.

No impact at all.

> Does nginx (core)  
> derive or imply anything relating to the name-spacing of directives  
> before (in my example) the proxy module sees the config, or is it  
> entirely down to how each module implements the configuration  
> aggregation/inheritance?

It’s entirely down to how each module implements it. But if a module  
implements inheritance of a directive as something other than “replace”  
or “no inheritance”, then that should probably be considered a bug.

## f

Francis D. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid)

---

<div class="post-metadata">

**Author:** ![jonathan2000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/fbc32d/32.png) [@jonathan2000](https://www.ruby-forum.com/u/jonathan2000)\
**Post date:** [April 4, 2012, 3:59pm UTC](https://www.ruby-forum.com/t/config-directive-inheritance-docs-and-rules-was-config-variable-inheritance/218538/3 "2012-04-04T15:59:27Z")

</div>

Hello!

On Wed, Apr 04, 2012 at 01:40:40PM +0100, Francis D. wrote:

> No. It will affect no other xyz\_ prefixed directives.  
> Not really, there are cases where it will. Examples include (not  
> sure if there are others):

1. allow and deny directives of access module create an array of  
allow/deny rules, and this array is inherited as a whole;

2. recently introduced xslt\_param and xslt\_string\_param do the  
same thing with xslt parameters.

All such cases are more or less obvious though.

[…]

Maxim D.

---

<div class="post-metadata">

**Author:** ![jonathan2000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/fbc32d/32.png) [@jonathan2000](https://www.ruby-forum.com/u/jonathan2000)\
**Post date:** [April 4, 2012, 6:55pm UTC](https://www.ruby-forum.com/t/config-directive-inheritance-docs-and-rules-was-config-variable-inheritance/218538/4 "2012-04-04T18:55:42Z")

</div>

On Wed, Apr 04, 2012 at 05:58:46PM +0400, Maxim D. wrote:

> On Wed, Apr 04, 2012 at 01:40:40PM +0100, Francis D. wrote:
> 
> > On Tue, Apr 03, 2012 at 06:20:13PM +0100, Jonathan M. wrote:

Hi there,

> allow/deny rules, and this array is inherited as a whole;
> 
> 1. recently introduced xslt\_param and xslt\_string\_param do the  
> same thing with xslt parameters.

Ah, thank you for the correction.

For the original poster: I was wrong, you _do_ need to check or test  
each  
time. So read “never” and “always” as “almost never” and “almost  
always”.

Sorry about that.

I’ve done a quick analysis of the 1.1.18 codebase, to see if I can find  
the current complete list (excluding 3rd party modules, of course).

The configuration directives are stored in a struct:

struct ngx\_command\_s {  
ngx\_str\_t name;  
ngx\_uint\_t type;  
char \*(\*set)(ngx\_conf\_t \*cf, ngx\_command\_t \*cmd, void  
\*conf);  
ngx\_uint\_t conf;  
ngx\_uint\_t offset;  
void \*post;  
};

“name” is the directive name; “\*set” is the function to set the value  
of the directive, and “offset” is the position relative to “conf” where  
the value is stored.

I see 67 arrays of that struct (grep for “static ngx\_command\_t”).

I see 449 “ngx\_string” within those arrays.

110 have unique \*set values.

Of the ones with non-unique \*set values, the few that have the same  
“offset” value are:

ngx\_event\_connections - worker\_connections, connections; one deprecated  
ngx\_mail\_block - mail, imap; one deprecated  
ngx\_conf\_set\_sec\_slot - open\_file\_cache\_valid, open\_file\_cache\_retest;  
one deprecated

ngx\_http\_core\_root - root, alias: single-valued, only one at a level  
ngx\_http\_access\_rule - allow, deny; both are valid  
ngx\_http\_xslt\_param - xslt\_param, xslt\_string\_param; both are valid.

And separate from that, the directives which have a duplicate “offset”  
value of “offsetof(something)” (as in, not-0 or a predefined constant),  
are:

open\_file\_cache\_valid, open\_file\_cache\_retest - one deprecated  
satisfy, satisfy\_any - one deprecated  
optimize\_server\_names, server\_name\_in\_redirect - one deprecated

If that’s an adequate analysis, it suggests that

allow/deny and xslt\_param/xslt\_string\_param

are the only distributed directives which don’t follow the  
replace-or-inherit-this-directive-only method.

> All such cases are more or less obvious though.

I wonder, is it worth having a note in the documentation for these  
exceptions to the common case?

I see that there is such a note at

[Module ngx\_http\_xslt\_module](http://nginx.org/en/docs/http/ngx_http_xslt_module.html#xslt_param),

but not (yet) at

> **[Module ngx\_http\_access\_module](http://nginx.org/en/docs/http/ngx_http_access_module.html#allow)**
>
> The ngx\_http\_access\_module module allows limiting access to certain client addresses.

Thanks,

## f

Francis D. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid)

---

<div class="post-metadata">

**Author:** ![jonathan2000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/fbc32d/32.png) [@jonathan2000](https://www.ruby-forum.com/u/jonathan2000)\
**Post date:** [April 4, 2012, 8:19pm UTC](https://www.ruby-forum.com/t/config-directive-inheritance-docs-and-rules-was-config-variable-inheritance/218538/5 "2012-04-04T20:19:32Z")

</div>

Hello!

On Wed, Apr 04, 2012 at 05:54:44PM +0100, Francis D. wrote:

[…]

> If that’s an adequate analysis, it suggests that
> 
> allow/deny and xslt\_param/xslt\_string\_param
> 
> are the only distributed directives which don’t follow the  
> replace-or-inherit-this-directive-only method.

Mechanical analisys of the codebase might miss some cases with  
custom directive handlers used. But I suppose the result is  
correct as it matches one from my memory. 🙂

> [Module ngx\_http\_access\_module](http://nginx.org/en/docs/http/ngx_http_access_module.html#allow)

Yes, this surely deserves a note.

Maxim D.