Understanding the Nginx Configuration Inheritance Model

The nginx configuration model is a big improvement over the Apache HTTPd one.

But when you dive in deeper there are some quirks to be aware of. Without knowledge of the fundamentals it’s easy to run into situations where you get unexpected behaviour.

To make sure you always know how to wrangle nginx I’ve prepared this post to help you understand how it all works, read on!

To understand the inheritance model of nginx you first need to know that nginx operates with multiple blocks of configuration.

In nginx such a block is referred to as a context, for instance, a configuration directive placed in server context resides within a server { } block just like a directive placed in http context resides in the http { } block.

There are 6 possible contexts in nginx, here in top to bottom order:

• Global.
• Http.
• Server.
• If.
• Location.
  • Nested Location.
  • If in location.
  • limit_except.

The default inheritance model is that directives inherit downwards only. Never sideways and definitely never up. This includes scenarios where you rewrite a request internally from one location to another – every directive in the first location is forgotten and only the second location directives apply for the location context.When it comes to inheritance behaviour there are four types of configuration directives in nginx:

• Normal directive – One value per context, for example: “root” or “index”.
• Array directive – Multiple values per context, for example: “access_log” or “fastcgi_param”
• Action directive – Something which does not just configure, for example: “rewrite” or “fastcgi_pass”
• try_files directive.

Normal directives are by far the most common one and follows the default inheritance model without any surprises. Lets have a look at an example configuration that show cases the behaviour.

server {
    root /home/user/public_html;

    location /app {
        root /usr/share; # This results in /usr/share/app
                         # Full URI is ALWAYS appended.
    }

    location /app2 {
        // Server context root applies here.
    }
}

Array directives are a lot like normal directives in the sense that they follow the standard inheritance model of always inheriting downwards and replacing any directives specified in a higher context. What might be confusing about these is to assume that you add to the array. The behaviour of an array directive is that if you define multiple directives in the same context you will add to the values, but if you define multiple directives in different contexts then the lower context will replace the higher context ones. This means that you need to sometimes double define a value if you want it present in multiple context. An example of such a scenario.

server {
    access_log /var/log/nginx/access.log;
    include fastcgi.conf;

    location ~ ^/calendar/.+\.php$ {
        access_log /var/log/nginx/php-requests.log; # If this executes then server context one never does.

        fastcgi_param ENV debug; # This *overwrites* the higher context array.
        include fastcgi.conf     # Therefore we include it in *this* context again.
    }
}

Action directives are where it starts to get interesting. They are confined to one context and will never inherit downwards, they can however be specified in multiple contexts and in some cases will be executed for each context. The rewrite directive is an action directive that is allowed in server and location context where both contexts might be executed.

server {
    rewrite ^/booking(.*) /calendar$1 permanent; # Always executes.

    location /calendar {
        rewrite ^ /index.php; # Can execute in addition to and does not replace server context rewrites.
    }
}

Naturally, it’s not quite that simple. Within locations there are three possible contexts, a nested location, an if and limit_except. The behaviour of a directive is actually entirely up to the module that defines it. All the normal and array directives will inherit properly if they are allowed in that context. For action directives the story is a bit different. Generally they will not inherit into a nested location but it ultimately depends on how the module wants it to be and it can differ on a directive by directive basis. The nginx documentation is not of use here either so you’ll have to just try it and see if nginx complains. For good measure, lets have an example of the most common behaviour and how it affects rewrite :

server {
    location /calendar {
        rewrite ^ /static.php; # Executes unless inner location matches.

        location ~ \.php$ {
            fastcgi_pass backend; # Outer location context rewrite is not executed.	
        }
    }
}

The try_files directive is mostly like every other action directive mentioned above, the difference is that if placed in server context nginx actually creates a pseudo-location that is the least specific location possible. That means if a request matches a defined location the try_files directive will not be executed. This means that if you have location / defined then you have a location that matches every possible request and as such try_files will never actually execution. Therefore always place try_files in location context instead of server context if at all possible.

server {
    try_files $uri /index.php; # This never executes.

    location / {
        # Whatever here, or empty.
    }

    location ~ \.php$ {
        # If this location executes then try_files still does not execute.
        # Even if location / did not exist.
    }
}