nginx开发_配置项
nginx开发笔记_配置项
模块的配置项即nginx.conf中的指令，HTTP模块指令可以分为三个级别：
- main级，直接写在http{}块中的指令
- server级，写在server{}块中的指令
- location级，写在location{}块中的指令
配置项定义模板
在自定义模块中使用配置项，需要配置ngx_module_t的commands属性以及ctx属性，并需要定义一个结构体用于存放配置信息。
常用的模板如下：
/* 存放配置信息的自定义结构体 */
typedef struct
{
ngx_flag_t my_flag;
} ngx_http_mytest_conf_t;
/* 模块声明 */
ngx_module_t ngx_http_mytest_module =
{
NGX_MODULE_V1,
&ngx_http_mytest_module_ctx, /* module context */
ngx_http_mytest_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_http_module_t ngx_http_mytest_module_ctx =
{
ngx_http_mytest_pre_conf, /* preconfiguration */
ngx_http_mytest_post_conf, /* postconfiguration */
ngx_http_mytest_create_main_conf, /* create main configuration */
ngx_http_mytest_init_main_conf, /* init main configuration */
ngx_http_mytest_create_srv_conf, /* create server configuration */
ngx_http_mytest_merge_srv_conf, /* merge server configuration */
ngx_http_mytest_create_loc_conf, /* create location configuration */
ngx_http_mytest_merge_loc_conf /* merge location configuration */
};
/* 自定义的配置项 */
static ngx_command_t ngx_http_mytest_commands[] =
{
{
ngx_string("test_flag"),
NGX_HTTP_LOC_CONF | NGX_CONF_FLAG,
ngx_conf_set_flag_slot,
NGX_HTTP_LOC_CONF_OFFSET,
offsetof(ngx_http_mytest_conf_t, my_flag),
NULL
},
ngx_null_command
};
配置项信息
配置项信息通过ngx_command_t类型指定
struct ngx_command_s {
ngx_str_t name;
ngx_uint_t type;
char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
ngx_uint_t conf;
ngx_uint_t offset;
void *post;
};
-
name 命令名称
-
type 设置配置项允许在哪些配置块中使用、配置项携带的参数个数、参数形式信息。具体可以参考ngx_conf_file.h和<深入理解Nginx 第2版>P116 表4-1。常用选项如下
/*
* AAAA number of arguments
* FF command flags
* TT command type, i.e. HTTP "location" or "server" command
*/
#define NGX_HTTP_MAIN_CONF 0x02000000
#define NGX_HTTP_SRV_CONF 0x04000000
#define NGX_HTTP_LOC_CONF 0x08000000
#define NGX_CONF_BLOCK 0x00000100
#define NGX_CONF_FLAG 0x00000200
#define NGX_CONF_ANY 0x00000400
#define NGX_CONF_1MORE 0x00000800
#define NGX_CONF_2MORE 0x00001000
#define NGX_CONF_NOARGS 0x00000001
#define NGX_CONF_TAKE1 0x00000002
#define NGX_CONF_TAKE2 0x00000004
#define NGX_CONF_TAKE3 0x00000008
#define NGX_CONF_TAKE4 0x00000010
- set属性指定配置项解析函数，ngx提供了12个常用的解析函数如下所示，解析的格式可以参考<深入理解Nginx 第2版>P118 表4-2 。也可以实现自定义的解析函数。
char *ngx_conf_set_flag_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_str_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_str_array_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_keyval_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_num_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_size_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_off_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_msec_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_sec_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_bufs_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_enum_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
char *ngx_conf_set_bitmask_slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
-
conf 用于指定配置项的偏移，与后文的create_xxx_conf回调函数有关。例如配置项是通过create_loc_conf函数创建的，此处的配置就应该为NGX_HTTP_LOC_CONF_OFFSET。
可选参数如下:
#define NGX_HTTP_MAIN_CONF_OFFSET offsetof(ngx_http_conf_ctx_t, main_conf)
#define NGX_HTTP_SRV_CONF_OFFSET offsetof(ngx_http_conf_ctx_t, srv_conf)
#define NGX_HTTP_LOC_CONF_OFFSET offsetof(ngx_http_conf_ctx_t, loc_conf)
- offset 用于指定配置项关联的结构体字段的偏移，一般使用offsetof宏设置。
- post指针，传递给set函数的参数，具体含义根据set函数而定。
配置项创建与合并
配置项创建与合并主要通过ngx_http_module_t的回调函数实现。
typedef struct {
ngx_int_t (*preconfiguration)(ngx_conf_t *cf);
ngx_int_t (*postconfiguration)(ngx_conf_t *cf);
void *(*create_main_conf)(ngx_conf_t *cf);
char *(*init_main_conf)(ngx_conf_t *cf, void *conf);
void *(*create_srv_conf)(ngx_conf_t *cf);
char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf);
void *(*create_loc_conf)(ngx_conf_t *cf);
char *(*merge_loc_conf)(ngx_conf_t *cf, void *prev, void *conf);
} ngx_http_module_t;
其中preconfiguration与postconfiguration相对好理解，在配置项创建整体前后分别回调。
create_main_conf、create_srv_conf、create_loc_conf三个函数的回调次数与nginx中具体的配置有关。以如下配置为例：
http {
test_str SUPERMAN;
server {
server_name HOST1;
location /HOST1_loc1 {
test_str loc1_BANANA;
}
location /HOST1_loc2 {
}
}
server {
server_name HOST2;
test_str CAR;
location /index {
test_str FOCUS;
}
location /test {
test_str PLANE;
}
location = /50x.html {
}
}
}
HTTP模块遇到http{}配置块时将调用create_main_conf、create_srv_conf、create_loc_conf三个函数，遇到server{}块时将调用create_srv_conf、create_loc_con两个函数、遇到location{}块时将调用create_loc_con函数。所以以上配置create_main_conf将被调用1次，create_srv_conf被调用3次，create_loc_conf被调用8次。一般HTTP模块都仅使用loc级的配置。
create_xxx_conf函数中一般的内容为创建自定义配置结构体，并设置初始值。常见如下：
static void *
ngx_http_sub_create_conf(ngx_conf_t *cf)
{
ngx_http_sub_loc_conf_t *slcf;
slcf = ngx_pcalloc(cf->pool, sizeof(ngx_http_sub_loc_conf_t));
if (slcf == NULL) {
return NULL;
}
slcf->once = NGX_CONF_UNSET;
slcf->last_modified = NGX_CONF_UNSET;
return slcf;
}
上文中提到在http{}和server{}中都会调用create_loc_conf，那么在具体处理请求时将使用那个级别的的配置，则由init_main_conf、merge_srv_conf、merge_loc_conf回调函数决定。已merge_loc_conf为例
(merge_loc_conf)(ngx_conf_t *cf, void *prev, void *conf);
prev指针为父级配置的结构体，conf为子级配置的结构体。一个常用的思路时：如果子级没有配置则复用父级的，常用方式如下：
static char *
ngx_http_mytest_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
ngx_http_mytest_conf_t *prev = (ngx_http_mytest_conf_t *)parent;
ngx_http_mytest_conf_t *conf = (ngx_http_mytest_conf_t *)child;
ngx_conf_merge_str_value(conf->my_str, prev->my_str, "defaultstr");
return NGX_CONF_OK;
}
ngx_conf_merge_str_value是合并str类型的宏，其他宏还包括
#define ngx_conf_merge_value(conf, prev, default)
#define ngx_conf_merge_ptr_value(conf, prev, default)
#define ngx_conf_merge_uint_value(conf, prev, default)
#define ngx_conf_merge_msec_value(conf, prev, default)
#define ngx_conf_merge_sec_value(conf, prev, default)
#define ngx_conf_merge_size_value(conf, prev, default)
#define ngx_conf_merge_off_value(conf, prev, default)
#define ngx_conf_merge_str_value(conf, prev, default)
#define ngx_conf_merge_bufs_value(conf, prev, default_num, default_size)
#define ngx_conf_merge_bitmask_value(conf, prev, default)
注意merge_loc_conf与create_loc_conf类似，在三个级别中会被调用多次，以上文的配置示例来说，merge_loc_conf会被调用7次，比create_loc_conf少1次，因为http{}不需要merge。
【此处的设计逻辑个人还没想理解十分明白，初步理解分三层配置用于一个模块中http{}srv{}loc{}需要定义使用不同conf_t结构体的场景，反复调用create函数是为了实现可以选择是否复用（merge）父级的功能。】
配置项获取
一般可以通过ngx_http_request_t *r变量或者ngx_conf_t *cf变量获取配置项的内容。常用的接口如下
#define ngx_http_get_module_main_conf(r, module)
#define ngx_http_get_module_srv_conf(r, module)
#define ngx_http_get_module_loc_conf(r, module)
#define ngx_http_conf_get_module_main_conf(cf, module)
#define ngx_http_conf_get_module_srv_conf(cf, module)
#define ngx_http_conf_get_module_loc_conf(cf, module)
示例代码如下:
static ngx_int_t
ngx_http_addition_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
...
ngx_http_addition_conf_t *conf;
...
conf = ngx_http_get_module_loc_conf(r, ngx_http_addition_filter_module);
}
