概述

Nginx对于用户来说最强大的是它的自定义模块，用户可以很方便地用C开发自己想要的功能，本文实践了handle和filter 2种模块的开发。

practice

build form src

git clone git@github.com:nginx/nginx.git -b branches/stable-1.24
cd nginx/
./auto/configure --help
./auto/configure
make
sudo make install

test

将nginx/sbin添加进PATH

user: 修改bash配置文件
sudo: 修改/etc/sudoers, Defaults secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/nginx/sbin"

$ sudo nginx -t
nginx: the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/nginx/conf/nginx.conf test is successful

$ cd /usr/local/nginx/conf 
$ sed -i 's/listen\s*80;/listen 8080;/g' nginx.conf
$ sudo nginx
$ sudo nginx -c /usr/local/nginx/confnginx.conf
$ curl localhost:8080

<title>Welcome to nginx!</title>

$ ps aux | grep nginx

root     3775822  0.0  0.0   4292   376 ?        Ss   18:03   0:00 nginx: master process nginx
nobody   3775823  0.0  0.0   4740  2136 ?        S    18:03   0:00 nginx: worker process

log

$ ll logs

-rw-r--r-- 1 root root 175 Jan 28 18:24 access.log
-rw-r--r-- 1 root root 388 Jan 28 18:24 error.log
-rw-r--r-- 1 root root   8 Jan 28 18:03 nginx.pid

nginx -s

sudo nginx -s stop     # 快速停止 Nginx
sudo nginx -s quit     # 优雅地关闭 Nginx
sudo nginx -s reload   # 重新加载 Nginx 配置文件
sudo nginx -s reopen   # 重新打开日志文件

modules

src/http/modules/ngx_http_static_module.c

hello world(handler)

命令:

mkdir hello_world_module
touch config
touch ngx_http_hello_module.c

cd $NGINX_SRC
# 如果有多个模块，使用多个--add-module，或者写在一个config里
auto/configure --add-module=$NGINX_MODULES/hello_world_module
sudo make install
sudo vim /usr/local/nginx/conf/nginx.conf

location = /hello {
        hello_string jizhao;
        hello_counter on;
}

sudo nginx -s stop
sudo nginx
curl localhost:8080
curl localhost:8080/hello

源码

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


typedef struct
{
        ngx_str_t hello_string;
        ngx_int_t hello_counter;
}ngx_http_hello_loc_conf_t;

static ngx_int_t ngx_http_hello_init(ngx_conf_t *cf);

static void *ngx_http_hello_create_loc_conf(ngx_conf_t *cf);

static char *ngx_http_hello_string(ngx_conf_t *cf, ngx_command_t *cmd,
        void *conf);
static char *ngx_http_hello_counter(ngx_conf_t *cf, ngx_command_t *cmd,
        void *conf);

static ngx_command_t ngx_http_hello_commands[] = {
   {
                ngx_string("hello_string"),
                NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS|NGX_CONF_TAKE1,
                ngx_http_hello_string,
                NGX_HTTP_LOC_CONF_OFFSET,
                offsetof(ngx_http_hello_loc_conf_t, hello_string),
                NULL },

        {
                ngx_string("hello_counter"),
                NGX_HTTP_LOC_CONF|NGX_CONF_FLAG,
                ngx_http_hello_counter,
                NGX_HTTP_LOC_CONF_OFFSET,
                offsetof(ngx_http_hello_loc_conf_t, hello_counter),
                NULL },

        ngx_null_command
};


/*
static u_char ngx_hello_default_string[] = "Default String: Hello, world!";
*/
static int ngx_hello_visited_times = 0;

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

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

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

        ngx_http_hello_create_loc_conf, /* 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 ngx_int_t
ngx_http_hello_handler(ngx_http_request_t *r)
{
        ngx_int_t    rc;
        ngx_buf_t   *b;
        ngx_chain_t  out;
        ngx_http_hello_loc_conf_t* my_conf;
        u_char ngx_hello_string[1024] = {0};
        ngx_uint_t content_length = 0;

        ngx_log_error(NGX_LOG_EMERG, r->connection->log, 0, "ngx_http_hello_handler is called!");

        my_conf = ngx_http_get_module_loc_conf(r, ngx_http_hello_module);
        if (my_conf->hello_string.len == 0 )
        {
                ngx_log_error(NGX_LOG_EMERG, r->connection->log, 0, "hello_string is empty!");
                return NGX_DECLINED;
        }


        if (my_conf->hello_counter == NGX_CONF_UNSET
                || my_conf->hello_counter == 0)
        {
                ngx_sprintf(ngx_hello_string, "%s", my_conf->hello_string.data);
        }
        else
        {
                ngx_sprintf(ngx_hello_string, "%s Visited Times:%d", my_conf->hello_string.data,
                        ++ngx_hello_visited_times);
        }
        ngx_log_error(NGX_LOG_EMERG, r->connection->log, 0, "hello_string:%s", ngx_hello_string);
        content_length = ngx_strlen(ngx_hello_string);

        /* we response to 'GET' and 'HEAD' requests only */
        if (!(r->method & (NGX_HTTP_GET|NGX_HTTP_HEAD))) {
                return NGX_HTTP_NOT_ALLOWED;
        }

        /* discard request body, since we don't need it here */
        rc = ngx_http_discard_request_body(r);

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

        /* set the 'Content-type' header */
        /*
         *r->headers_out.content_type.len = sizeof("text/html") - 1;
         *r->headers_out.content_type.data = (u_char *)"text/html";
         */
        ngx_str_set(&r->headers_out.content_type, "text/html");


        /* send the header only, if the request type is http 'HEAD' */
        if (r->method == NGX_HTTP_HEAD) {
                r->headers_out.status = NGX_HTTP_OK;
                r->headers_out.content_length_n = content_length;

                return ngx_http_send_header(r);
        }

        /* allocate a buffer for your response body */
        b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));
        if (b == NULL) {
                return NGX_HTTP_INTERNAL_SERVER_ERROR;
        }

        /* attach this buffer to the buffer chain */
        out.buf = b;
        out.next = NULL;

        /* adjust the pointers of the buffer */
        b->pos = ngx_hello_string;
        b->last = ngx_hello_string + content_length;
        b->memory = 1;    /* this buffer is in memory */
        b->last_buf = 1;  /* this is the last buffer in the buffer chain */

        /* set the status line */
        r->headers_out.status = NGX_HTTP_OK;
        r->headers_out.content_length_n = content_length;

        /* send the headers of your response */
        rc = ngx_http_send_header(r);

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

        /* send the buffer chain of your response */
        return ngx_http_output_filter(r, &out);
}

static void *ngx_http_hello_create_loc_conf(ngx_conf_t *cf)
{
        ngx_http_hello_loc_conf_t* local_conf = NULL;
        local_conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_hello_loc_conf_t));
        if (local_conf == NULL)
        {
                return NULL;
        }

        ngx_str_null(&local_conf->hello_string);
        local_conf->hello_counter = NGX_CONF_UNSET;

        return local_conf;
}

/*
static char *ngx_http_hello_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
        ngx_http_hello_loc_conf_t* prev = parent;
        ngx_http_hello_loc_conf_t* conf = child;

        ngx_conf_merge_str_value(conf->hello_string, prev->hello_string, ngx_hello_default_string);
        ngx_conf_merge_value(conf->hello_counter, prev->hello_counter, 0);

        return NGX_CONF_OK;
}*/

static char *
ngx_http_hello_string(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{

        ngx_http_hello_loc_conf_t* local_conf;


        local_conf = conf;
        char* rv = ngx_conf_set_str_slot(cf, cmd, conf);

        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "hello_string:%s", local_conf->hello_string.data);

        return rv;
}


static char *ngx_http_hello_counter(ngx_conf_t *cf, ngx_command_t *cmd,
        void *conf)
{
        ngx_http_hello_loc_conf_t* local_conf;

        local_conf = conf;

        char* rv = NULL;

        rv = ngx_conf_set_flag_slot(cf, cmd, conf);


        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "hello_counter:%d", local_conf->hello_counter);
        return rv;
}

static ngx_int_t
ngx_http_hello_init(ngx_conf_t *cf)
{
        ngx_http_handler_pt        *h;
        ngx_http_core_main_conf_t  *cmcf;

        cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);

        h = ngx_array_push(&cmcf->phases[NGX_HTTP_CONTENT_PHASE].handlers);
        if (h == NULL) {
                return NGX_ERROR;
        }

        *h = ngx_http_hello_handler;

        return NGX_OK;
}

config

ngx_addon_name=ngx_http_hello_module
HTTP_MODULES="$HTTP_MODULES ngx_http_hello_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_module.c"

总结

定义一个config结构（loc级别）: ngx_http_hello_loc_conf_t
定义ngx_command_t[]使用nginx内置能力解析配置（加一个ngx_null_command作为结尾）: ngx_http_hello_commands
定义处理request的hanler: ngx_http_hello_handler
将handler插入content_phase的函数: ngx_http_hello_init
定义config的初始化函数: ngx_http_hello_create_loc_conf
定义模块在加载时的行为ngx_http_module_t: ngx_http_hello_module_ctx，包含:
- postconfiguration: ngx_http_hello_init
- create location configuration: ngx_http_hello_create_loc_conf
定义模块结构体ngx_module_t: ngx_http_hello_module，包含
- module context: ngx_http_hello_module_ctx
- ngx_http_hello_commands: ngx_http_hello_commands
- 忽略其他hooks配置

body(filter)

命令:

cd $NGINX_MODULES/hello_world_module
touch ngx_http_filter_module.c

cd $NGINX_SRC
# 如果有多个模块，写在一个config里
auto/configure --add-module=$NGINX_MODULES/hello_world_module
sudo make install
sudo vim /usr/local/nginx/conf/nginx.conf

# conf
server {
        listen       8080;
        server_name  localhost;
        predix on;    

sudo nginx -s stop
sudo nginx
curl localhost:8080

源码

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

typedef struct {
	ngx_flag_t enable;
} ngx_http_filter_conf_t;

static ngx_str_t prefix = ngx_string("<h2>FLY. </h2>");

static ngx_http_output_header_filter_pt  ngx_http_next_header_filter;
static ngx_http_output_body_filter_pt    ngx_http_next_body_filter;

ngx_int_t ngx_http_fly_header_filter(ngx_http_request_t *r) {
	if (r->headers_out.status != NGX_HTTP_OK) {
		return ngx_http_next_header_filter(r);
	}
	r->headers_out.content_length_n += prefix.len;
	return ngx_http_next_header_filter(r);
}

ngx_int_t ngx_http_fly_body_filter(ngx_http_request_t *r, ngx_chain_t *chain) {
	ngx_buf_t *b = ngx_create_temp_buf(r->pool, prefix.len);
	b->start = b->pos = prefix.data;
	b->last = b->pos + prefix.len;

	ngx_chain_t *c1 = ngx_alloc_chain_link(r->pool);
	c1->buf = b;
	c1->next = chain;

	return ngx_http_next_body_filter(r, c1);
}

ngx_int_t ngx_http_fly_filter_init(ngx_conf_t *cf)
{
	ngx_http_next_header_filter = ngx_http_top_header_filter;
	ngx_http_top_header_filter = ngx_http_fly_header_filter;

	ngx_http_next_body_filter = ngx_http_top_body_filter;
	ngx_http_top_body_filter = ngx_http_fly_body_filter;

	return NGX_OK;
}

void  *ngx_http_fly_filter_create_loc_conf(ngx_conf_t *cf)
{
	ngx_http_filter_conf_t *conf = ngx_palloc(cf->pool, sizeof(ngx_http_filter_conf_t));
	if (conf == NULL)
		return NULL;

	conf->enable = NGX_CONF_UNSET;
	
	return conf;
}

char  *ngx_http_fly_filter_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
	ngx_http_filter_conf_t *prev = (ngx_http_filter_conf_t*)parent;
	ngx_http_filter_conf_t *next = (ngx_http_filter_conf_t*)child;
	
	ngx_conf_merge_value(next->enable, prev->enable, 0);

	return NGX_CONF_OK;
}

// conf文件中的每一行都是一个指令指令
ngx_command_t ngx_http_fly_filter_module_cmd[] = {
	{
		ngx_string("predix"),
		// 指示name命令放的位置在哪里以及可以带多少个参数,NGX_CONF_FLAGE表示开关标志
		// predix on/off
		NGX_HTTP_MAIN_CONF | NGX_HTTP_SRV_CONF | NGX_HTTP_LOC_CONF | NGX_CONF_FLAG,
		// 命令解析,可以使用nginx内部的也可以自己实现
		ngx_conf_set_flag_slot,//ngx_http_fly_filter_set_slot,

		NGX_HTTP_LOC_CONF_OFFSET,
		// offsetof获取enable在结构体中的偏移位置
		offsetof(ngx_http_filter_conf_t,enable),
		NULL,
	},
	ngx_null_command
};

/*
// conf文件命令解析
char  *ngx_http_fly_filter_set_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
	char *p = conf;

	// 对应 ngx_http_fly_filter_create_loc_conf函数的conf->enable = NGX_CONF_UNSET;
	ngx_flag_t *flag = (p + cmd->offset);

	return NGX_CONF_OK;
}
*/

static ngx_http_module_t ngx_http_fly_filter_module_ctx = {
	NULL,
	ngx_http_fly_filter_init,

	NULL,
	NULL,

	NULL,
	NULL,

	ngx_http_fly_filter_create_loc_conf,
	ngx_http_fly_filter_merge_loc_conf
};

ngx_module_t ngx_http_fly_filter_module = {
	NGX_MODULE_V1,

	&ngx_http_fly_filter_module_ctx,
	ngx_http_fly_filter_module_cmd,

	// http的ascii值,指示是什么模块
	NGX_HTTP_MODULE,

	NULL,
	NULL,
	NULL,
	NULL,
	NULL,
	NULL,
	NULL,

	NGX_MODULE_V1_PADDING
};

config

ngx_addon_name=ngx_http_fly_filter_module
HTTP_FILTER_MODULES="$HTTP_FILTER_MODULES ngx_http_fly_filter_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_filter_module.c"

auto/confuguration

confuguration

auto/options: 将命令行的参数转化为shell变量
auto/init: 非常短，只是定义了obj目录下的一些文件对应的shell变量
auto/sources: 定义了C语言头文件和源文件对应的shell变量，主要分为
- CORE_DEPS/CORE_SRCS
- EVENT_DEPS/EVENT_SRCS
- SELECT/POLL/EPOLL
- UNIX_DEPS/UNIX_SRCS
- THREAD_POOL_DEPS/THREAD_POOL_SRCS
- 操作系统相关的
auto/have: 在 $NGX_AUTO_CONFIG_H里 `#define$ have 1`
auto/define: 在 $NGX_AUTO_CONFIG_H里 `#define$ have $value`
auto/feature: 生成一段C代码执行，以检查某些库是否存在
auto/lib/conf: 配置库
auto/modules: 生成 $NGX_MODULES_C/$ ngx_modules_c文件，代码比较复杂，需要一定脚本能力

. auto/options
. auto/init
. auto/sources

have=NGX_DEBUG . auto/have
have=NGX_PREFIX value="\"$NGX_PREFIX/\"" . auto/define

. auto/unix
. auto/feature

. auto/headers
. auto/include

. auto/threads
. auto/modules
. auto/lib/conf

Nginx模块开发实践

概述

practice

build form src

test

log

nginx -s

modules

hello world(handler)

源码

config

总结

body(filter)

源码

config

auto/confuguration

confuguration