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

[Francis Daly]

On Wed, Apr 04, 2012 at 05:58:46PM +0400, Maxim Dounin wrote:
> On Wed, Apr 04, 2012 at 01:40:40PM +0100, Francis Daly wrote:
> > On Tue, Apr 03, 2012 at 06:20:13PM +0100, Jonathan Matthews wrote:

Hi there,

> > > 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.
> 
> 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.

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
 
http://nginx.org/en/docs/http/ngx_http_xslt_module.html#xslt_param,

but not (yet) at

http://nginx.org/en/docs/http/ngx_http_access_module.html#allow

Thanks,

	f
-- 
Francis Daly        francis at daoine.org