Splitting a Large Nginx Configuration File

1. Overview

Nginx is a popular web server that we can also use as a proxy and load balancer. Notably, it has many customization options to help meet our needs. To leverage those, we can change the server’s behavior with directives that we enter into configuration files. Moreover, Nginx provides ways to split such files when they become too large or mixed.

In this tutorial, we’ll learn ways to split a large configuration file into smaller ones. In addition, we’ll display the results with some examples.

2. The include Directive

The include directive adds the contents of one configuration file to another. In particular, it’s the main way to split a large file into smaller ones.

To include a single file, we append a specific path to the directive:

include /etc/nginx/mime.types;

Here, the mime.types file becomes part of our current configuration. Of course, any included content should have the correct syntax.

Instead of using a single file path, we can set a pattern that may match multiple files:

include /etc/nginx/conf.d/*.conf;

In this example, all .conf files in /etc/nginx/conf.d become part of the current configuration. This is a handy feature because we can add settings without editing an existing file.

3. Splitting Files With the include Directive

The main Nginx configuration file is nginx.conf that’s at/etc/nginx/nginx.conf on Ubuntu systems. In it, we can define virtual servers, listening ports, local directories to serve static content, log files, and others. Naturally, we can also modify nginx.conf to include the content of another file.

For our example, we’ll create a new file and save it under the /etc/nginx directory as my-vserver.conf:

server {
   listen 8080;
   location /my-vserver {
      alias /data/my-vserver;
   }
}

Here, we created a new virtual server that does these:

• listens to the 8080 port
• matches requests with URLs starting with the my-vserver string
• serves content from the /data/my-vserver directory

Next, we’ll add an include directive to the nginx.conf file:

include /etc/nginx/my-vserver.conf;

In this case, we supply the /etc/nginx/my-vserver.conf file path to the include directive. In addition, include itself should be nested in the HTTP block of nginx.conf.

For testing, we create a simple echo.json JSON file in the /data/my-vserver directory:

$ mkdir /data /data/my-vserver
$ echo "{ 'message' : 'Hello from my-vserver' }" | sudo tee /data/my-vserver/echo.json

After that, we reload our configuration:

$ sudo nginx -s reload

Notably, we use the -s option of Nginx to send the reload signal, reloading all configuration files.

Finally, we send an HTTP request to our server and check the output:

$ curl http://localhost:8080/my-vserver/echo.json
{ 'message' : 'Hello from my-vserver' }

As expected, we got the echo.json file. So, the server loaded my-vserver.conf successfully.

4. Adding Files to the conf.d Directory

The default nginx.conf file also provides the means to include other configuration files. We may open it and search for existing include directives.

Usually, there may be a general pattern:

include /etc/nginx/conf.d/*.conf;

The above directive loads all files in the conf.d directory. So, instead of including files on our own, we may copy them to the conf.d directory. Again, the above include command is nested in the http block of the nginx.conf file.

An alternative to storing our files in the conf.d directory is to create links to their original location. This is useful if we want to keep the files in our separate directory. Let’s create a link to the my-vserver.conf file:

$ sudo ln -s /etc/nginx/my-vserver.conf /etc/nginx/conf.d/my-vserver.conf

Of course, we should remove the include directive we had previously.

Next, we can reload and send an HTTP request to our server:

$ sudo nginx -s reload
$ curl http://localhost:8080/my-vserver/echo.json
{ 'message' : 'Hello from my-vserver' }

As expected, we received the echo.json file. So, the server loaded our file successfully.

In fact, this method is useful when there is more than one maintainer of the Nginx server configuration. This way we can isolate individual configurations. As a result, we avoid getting the main nginx.conf file corrupted.

5. Sites Available and Sites Enabled

Another way to split and handle virtual servers and their configuration is to create two distinct directories:

• sites-available – configuration files
• sites-enabled – links to some or all files of sites-available

Next, we include only the sites-enabled directory in the nginx.conf file.

This scheme is common on Debian-based systems. The notion is that we have several available virtual server configurations, but we enable or disable only a subset of them. To do this, we simply add or remove links in the sites-enabled directory.

To use this scheme, we should see whether our nginx.conf file contains an include instruction for sites-enabled:

include /etc/nginx/sites-enabled/*;

If it doesn’t, we may add it. Next, we can move my-vserver.conf to the sites-available directory. Then, we create a link to the file in the sites-enabled directory:

$ sudo ln -s /etc/nginx/sites-available/my-vserver.conf /etc/nginx/sites-enabled/my-vserver.conf

Finally, we can reload and test:

$ sudo nginx -s reload
$ curl http://localhost:8080/my-vserver/echo.json
{ 'message' : 'Hello from my-vserver' }

As expected, the server responded with the echo.json file. This means that our virtual server is enabled through a separate file structure, which allows easy toggling.

6. Conclusion

In this article, we learned how to split our Nginx configuration files. We discussed the include directive and saw how we can use the conf.d directory. Finally, we examined the available and enabled sites scheme.