Problem

You need to clean up bulky configuration files to keep your configurations logically grouped into modular configuration sets.

Solution

Use the include directive to reference configuration files, directories, or masks:

http {
    include config.d/compression.conf;
    include sites-enabled/*.conf
}

The include directive takes a single parameter of either a path to a file or a mask that matches many files. This directive is valid in any context.

Discussion

By using include statements you can keep your NGINX configuration clean and concise. You’ll be able to logically group your configurations to avoid configuration files that go on for hundreds of lines. You can create modular configuration files that can be included in multiple places throughout your configuration to avoid duplication of configurations. Take the example fastcgi_param configuration file provided in most package management installs of NGINX. If you manage multiple FastCGI virtual servers on a single NGINX box, you can include this configuration file for any location or context where you require these parameters for FastCGI without having to duplicate this configuration. Another example is SSL configurations. If you’re running multiple servers that require similar SSL configurations, you can simply write this configuration once and include it wherever needed. By logically grouping your configurations together, you can rest assured that your configurations are neat and organized. Changing a set of configuration files can be done by editing a single file rather than changing multiple sets of configuration blocks in multiple locations within a massive configuration file. Grouping your configurations into files and using include statements is good practice for your sanity and the sanity of your colleagues.

Problem

You’re getting unexpected results from your NGINX server.

Solution

Debug your configuration, and remember these tips:

• NGINX processes requests looking for the most specific matched rule. This makes stepping through configurations by hand a bit harder, but it’s the most efficient way for NGINX to work. There’s more about how NGINX processes requests in the documentation link in the section “Also See”.

• You can turn on debug logging. For debug logging, you’ll need to ensure that your NGINX package is configured with the --with-debug flag. Most of the common packages have it; but if you’ve built your own or are running a minimal package, you may want to at least double-check. Once you’ve ensured you have debug, you can set the error_log directive’s log level to debug: error_log /var/log/nginx/error.log debug.

• You can enable debugging for particular connections. The debug_connection directive is valid inside the events context and takes an IP or CIDR range as a parameter. The directive can be declared more than once to add multiple IP addresses or CIDR ranges to be debugged. This may be helpful to debug an issue in production without degrading performance by debugging all connections. 

• You can debug for only particular virtual servers. Because the error_log directive is valid in the main HTTP, mail, stream, server, and location contexts, you can set the debug log level in only the contexts you need it. 

• You can enable core dumps and obtain backtraces from them. Core dumps can be enabled through the operating system or through the NGINX configuration file. You can read more about this from the admin guide in the section “Also See”.

• You’re able to log what’s happening in rewrite statements with the rewrite_log directive on: rewrite_log on.

Discussion

The NGINX platform is vast, and the configuration enables you to do many amazing things. However, with the power to do amazing things, there’s also the power to shoot your own foot. When debugging, make sure you know how to trace your request through your configuration; and if you have problems, add the debug log level to help. The debug log is quite verbose but very helpful in finding out what NGINX is doing with your request and where in your configuration you’ve gone wrong.

Also See

How NGINX Processes Requests
Debugging Admin Guide
Rewrite Log