Exploring Nginx Modules: A Guide to Custom Module Development

Nginx is a powerful, high-performance web server, reverse proxy server, and load balancer. It's well-known for its ability to handle a large number of connections and serve static files efficiently. One of the reasons behind its popularity is its modular architecture, which allows developers to extend its functionality by creating custom modules. In this blog post, we'll take an in-depth look at Nginx modules and guide you through the process of developing your custom module. We'll explore the different types of modules, their structure, and how to compile and install them. Let's dive in!

Understanding Nginx Modules

Nginx is designed with a modular architecture, which means its functionality is divided into smaller, independent components called modules. These modules can be enabled or disabled during the compilation process, allowing users to tailor Nginx to their specific needs. There are several types of modules in Nginx, including:

Core modules
Event modules
Protocol modules (like HTTP, Mail, and Stream)
HTTP modules
Mail modules
Stream modules

For this guide, we'll focus on developing custom HTTP modules since they're the most commonly used modules.

Setting Up the Development Environment

Before we start developing our custom module, let's set up a development environment. We'll need the following tools and dependencies:

A Linux-based operating system (we'll use Ubuntu in this guide)
Nginx source code
GCC (GNU Compiler Collection) and development tools
Text editor or IDE of your choice

First, install the necessary tools and dependencies:

sudo apt update
sudo apt install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev

Next, download the Nginx source code and extract it:

wget http://nginx.org/download/nginx-1.21.3.tar.gz
tar -xvf nginx-1.21.3.tar.gz
cd nginx-1.21.3

Creating a Custom Module

Now that our development environment is ready, let's create a simple "Hello, World!" module. We'll name it ngx_http_hello_module.

Step 1: Create the Module Directory and Source Files

Create a new directory for your module and navigate to it:

mkdir modules
cd modules
mkdir ngx_http_hello_module
cd ngx_http_hello_module

Next, create a new C source file named ngx_http_hello_module.c and open it in your favorite text editor or IDE.

Step 2: Define the Module's Structure

In the ngx_http_hello_module.c file, we'll start by including the necessary Nginx headers and defining the module's structure:

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>

static char *ngx_http_hello(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
static ngx_int_t ngx_http_hello_handler(ngx_http_request_t *r);

static ngx_command_t ngx_http_hello_commands[] = {
    { ngx_string("hello"),
      NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
      ngx_http_hello,
      0,
      0,
      NULL },

      ngx_null_command
};

static ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL,                                  /* preconfiguration */
    NULL,                                  /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};

ngx_module_t ngx_http_hello_module = {
    NGX_MODULE_V1,
    &ngx_http_hello_module_ctx,           /* module context */
    ngx_http_hello_commands,              /* module directives */
    NGX_HTTP_MODULE,                      /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};

static char *ngx_http_hello(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) {
    ngx_http_core_loc_conf_t *clcf;

    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
    clcf->handler = ngx_http_hello_handler;

    return NGX_CONF_OK;
}

static ngx_int_t ngx_http_hello_handler(ngx_http_request_t *r) {
    ngx_int_t rc;
    ngx_buf_t *b;
    ngx_chain_t out;

    rc = ngx_http_discard_request_body(r);

    if (rc != NGX_OK) {
        return rc;
    }

    r->headers_out.content_type.len = sizeof("text/plain") - 1;
    r->headers_out.content_type.data = (u_char *) "text/plain";
    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = sizeof("Hello, World!") - 1;

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }

    b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));

    if (b == NULL) {
        return NGX_HTTP_INTERNAL_SERVER_ERROR;
    }

    out.buf = b;
    out.next = NULL;

    b->pos = (u_char *) "Hello, World!";
    b->last = b->pos + sizeof("Hello, World!") - 1;
    b->memory = 1;
    b->last_buf = 1;

    return ngx_http_output_filter(r, &out);
}

In the code above, we defined a simple "Hello, World!" HTTP module. We started by including the required Nginx headers and defining the module's structure, commands, and context. Then, we implemented the ngx_http_hello and ngx_http_hello_handler functions to handle the hello directive and generate the response.

Compiling and Installing the Custom Module

Now that our custom module is ready, we need to compile and install it. First, navigate back to the Nginx source directory:

cd ../../

Next, configure the Nginx build with the --add-module option to include our custom module:

./configure --prefix=/usr/local/nginx --add-module=modules/ngx_http_hello_module

Compile and install Nginx:

make
sudo make install

Finally, start Nginx:

sudo /usr/local/nginx/sbin/nginx

Testing the Custom Module

To test our custom module, we'll need to modify the Nginx configuration file located at /usr/local/nginx/conf/nginx.conf. Open the file in your favorite text editor and add the following line inside the location / block:

hello;

Your configuration file should look like this:

...
http {
    ...
    server {
        ...
        location / {
            hello;
        }
    }
}
...

Restart Nginx to apply the changes:

sudo /usr/local/nginx/sbin/nginx -s reload

Now, visit http://localhost/ in your web browser or use a command-line tool like curl:

curl http://localhost/

You should see the "Hello, World!" message, indicating that our custom module is working as expected.

FAQ

1. Can I use third-party modules with the official Nginx package?

Yes, you can use third-party modules with the official Nginx package. However, you'll need to recompile Nginx with the --add-module or --add-dynamic-module options to include the third-party module.

2. What is the difference between a static module and a dynamic module?

A static module is compiled directly into the Nginx binary, while a dynamic module is compiled as a separate shared object file (.so) that can be loaded at runtime. Static modules are always available, whereas dynamic modules can be loaded or unloaded as needed.

3. Can I load my custom module without recompiling Nginx?

Yes, you can compile your custom module as a dynamic module and load it at runtime without recompiling Nginx. To do this, use the --add-dynamic-module option during the configuration step and add the load_module directive to your Nginx configuration file.

4. How do I debug my custom module?

You can use a debugger like GDB (GNU Debugger) to debug your custom module. You'll need to compile Nginx with the -g flag for debugging symbols and start Nginx with the gdb command. Additionally, you can add ngx_log_debug() statements in your module's code to print debug messages in the Nginx error log.

5. Are there any resources for learning more about Nginx module development?

Yes, there are several resources available for learning more about Nginx module development. Some recommended resources include:

The official Nginx Development Guide
The book "Nginx HTTP Server" by Clément Nedelcu
Various open-source Nginx modules on GitHub