Understanding Nginx Configuration Parsing: Data Structures, ngx_conf_parse, and HTTP Block Processing

In the previous part we introduced ngx_init_cycle, the most critical step in Nginx startup that creates the ngx_cycle_t structure and its four‑level pointer conf_ctx which stores all module configuration data. This section explains how Nginx reads nginx.conf, maps each directive to the appropriate place in conf_ctx, and stores HTTP, server, and location configurations.

1. Advanced Data Structures

Before discussing configuration parsing we need to know two high‑level structures provided by Nginx. The first is ngx_conf_t, whose simplified definition is:

struct ngx_conf_s {</code><code>    char                 *name;   // current directive name</code><code>    ngx_array_t          *args;   // all arguments of the directive</code><code>    ngx_cycle_t          *cycle;  // associated ngx_cycle_t</code><code>    ngx_pool_t           *pool;</code><code>    void                 *ctx;    // directive context</code><code>    ngx_conf_handler_pt   handler; // custom handler for the directive</code><code>    … …</code><code>};

ngx_conf_t

records each directive’s attributes; when a directive is encountered its name is stored in name, arguments in args, context in ctx, and the optional custom handler is invoked.

The second important structure is ngx_command_t, which describes the directives a module can handle:

struct ngx_command_s {</code><code>    ngx_str_t             name;   // directive name</code><code>    ngx_uint_t            type;   // where the directive may appear and its argument type/count</code><code>    char               *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); // handler</code><code>    ngx_uint_t            conf;   // offset of the configuration in memory</code><code>    ngx_uint_t            offset; // byte offset of the directive within the configuration structure</code><code>    … …</code><code>};

The set function pointer is the callback each module implements to process its directives.

2. The Parsing Tool – ngx_conf_parse

Because Nginx configuration files are flexible, support nesting, includes, and repeated directives, Nginx provides a universal parser called ngx_conf_parse. The function can parse any configuration with a single call. Its workflow is roughly:

1. Parsing classification : Nginx classifies the current input as file parsing, block parsing, or token parsing. File parsing handles whole files (e.g., the initial nginx.conf or an include file). Block parsing deals with sections delimited by {} such as http{}, server{}, location{}. Token parsing processes a single directive.

2. Token extraction : The core function ngx_conf_read_token is called in a loop; each call returns a token (directive plus its arguments) which is stored in the args array of a ngx_conf_t instance.

3. Configuration handling : After a token is read, Nginx iterates over ngx_modules[] to find a module whose ngx_command_t matches the directive name, then invokes that module’s set handler (e.g., ngx_set_worker_processes for worker_processes).

4. The process repeats until the whole file or block is consumed.

3. HTTP Configuration Parsing

When the parser encounters the http token, it hands control to the core HTTP module ( ngx_http_module) which calls ngx_http_block. The HTTP framework then creates a container ngx_http_conf_ctx_t to hold configuration structures for all HTTP modules:

typedef struct {</code><code>    void        **main_conf;  // main (http) level configuration</code><code>    void        **srv_conf;   // server level configuration</code><code>    void        **loc_conf;   // location level configuration</code><code>} ngx_http_conf_ctx_t;

Each HTTP module implements create_main_conf, create_srv_conf, and create_loc_conf. The framework iterates over ngx_modules[], calls these creators, and stores the returned structures in the appropriate arrays of the newly created ngx_http_conf_ctx_t. This step is often called “registering the household register”.

After the context is ready, ngx_conf_parse is invoked again (now with type=parse_block) to parse the directives inside the http block. The same mechanism recurs for server and location blocks, each time creating a new ngx_http_conf_ctx_t that inherits the higher‑level main_conf and srv_conf pointers as needed.

4. Resolving Configuration Conflicts

Directives such as error_log or root can appear in multiple scopes (main, server, location). Nginx resolves conflicts using the merge_srv_conf and merge_loc_conf callbacks that each HTTP module may implement. After all directives are parsed, the framework walks through the modules and calls these merge functions to combine higher‑level defaults with lower‑level overrides, allowing modules to decide which value finally takes effect.

5. Chapter Summary

This chapter introduced the two high‑level data structures ngx_conf_t and ngx_command_t, presented the universal parser ngx_conf_parse, and walked through the parsing flow of the most common http configuration, including memory layout, context creation, and conflict resolution. The goal was to give readers a clear picture of Nginx’s configuration‑parsing architecture during the startup phase.