nginx中文文档-ngx_http_autoindex_module

ngx_http_autoindex_module模块处理以“/”结尾的请求,并生成一个目录列表。通常当ngx_http_index_module模块找不到索引文件时会将请求传给ngx_http_autoindex_module模块。

实例配置

location / {
    autoindex on;
}

autoindex

语法:autoindex on | off
默认:autoindex off
上下文:http, server, location

开启或禁用列目录功能。

autoindex_exact_size

语法:autoindex_exact_size on | off
默认:autoindex_exact_size on
上下文:http, server, location

对于HTML格式,定义文件大小显示大小为确切的值还是近似用G、M、K表示的值。

autoindex_format

语法:autoindex_format html | xml | json | jsonp
默认:autoindex_format html
上下文:http, server, location
版本:1.7.9+

设置列目录的格式。
当使用JSONP格式时,回调函数名通过请求的callback参数指定,如果不指定参数或参数为空,则会使用JSON格式。
XML输出可以通过ngx_http_xslt_module模块改变。

autoindex_localtime

语法:autoindex_localtime on | off
默认:autoindex_localtime off
上下文:http, server, location

对于HTML格式,定义时间的显示是使用本地时间还是UTC时间。

nginx中文文档-ngx_http_auth_request_module

本文介绍ngx_http_auth_request_module模块的相关指令。

ngx_http_auth_request_module模块(1.5.4+)实现了基于子请求结果的客户端认证。如果子请求返回2xx状态码,访问将被允许。如果返回401或403访问将被阻止。子请求返回的其他状态码被视为错误。
401错误时,客户端可以收到来自自球球响应的“WWW-Authenticate”头。
该模块并非默认构建,需要通过–with-http_auth_request_module编译参数开启。
该模块可以结合其他访问许可模块,如ngx_http_access_module和 ngx_http_auth_basic_module,通过satisfy指令来实现。
在1.7.3版本以前,响应的认证子请求不能被缓存。
实例配置

location /private/ {
    auth_request /auth;
    ...
}

location = /auth {
    proxy_pass ...
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

auth_request

语法:auth_request uri | off
默认:auth_request off
上下文: http, server, location

开启基于子请求的权限认证,并设置发送子请求的URI。

auth_request_set

语法:auth_request_set variable value
默认:—
上下文:http, server, location

设置在认证请求完成后给变量设的值。值可以包含认证请求的变量,如$upstream_http_*。

nginx中文文档-ngx_http_auth_basic_module

ngx_http_auth_basic_module模块允许通过HTTP基础认证方式使用用户名密码来限制对资源的访问。访问同样可以通过地址和子请求结果进行限制。同时通过地址和密码限制访问可以由satisfy指令进行控制。

示例配置

location / {
    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

auth_basic

语法:auth_basic string | off
默认:auth_basic off
上下文:http, server, location, limit_except

允许通过HTTP基础认证协议验证用户名和密码。定义的参数使用realm,参数值可以包含变量(1.3.10+, 1.2.7+)。off值会取消由上层继承下来的auth_basic值。

auth_basic_user_file

语法:auth_basic_user_file file
默认:—
上下文:http, server, location, limit_except

定义保存用户名和密码的文件,格式如下:

# comment
name1:password1
name2:password2:comment
name3:password3

文件名可以包含变量。
支持以下密码类型:

  • crypt函数加密的密码。可以通过Apache服务器的“htpasswd”应用或“openssl passwd”命令生成。
  • Apache基于MD5算法的变体哈希算法,可通过同一个工具生成
  • 通过“{scheme}data”语法定义(1.0.3+),详细描述见RFC 2307。目前实现的模式有PLAIN(举例,不应该使用)、SHA(1.3.13+)(plain SHA-1不应使用)、SSHA(加盐SHA-1)

添加对SHA模式的支持,只是便于从其他服务器的迁移。不应该用于新的密码,因为不加盐的SHA-1哈希算法易受彩虹表攻击。

nginx中文文档-ngx_http_addition_module

ngx_http_addition_module模块是一个在请求前后增加内容的过滤器。默认情况下,该模块不会构建,必须在编译时添加参数–with-http_addition_module才能开启。

示例配置

location / {
    add_before_body /before_action;
    add_after_body  /after_action;
}

add_before_body

语法:add_before_body uri
默认:—
上下文:http, server, location

在响应体之前添加一段子请求返回的文本,如果参数是个空字符串“”,则取消其他层级中继承的数值。

add_after_body

语法:add_after_body uri
默认:—
上下文:http, server, location

在响应体之后添加一段子请求返回的文本,如果参数是个空字符串“”,则取消其他层级中继承的数值。

addition_types

语法:addition_types mime-type
默认:addition_types text/html
上下文:http, server, location
版本:0.7.9+

为附加内容文本设置允许的MIME类型,如果是“*”表示任何的MIME类型(0.8.29+)。

nginx中文文档-ngx_http_access_module

本文介绍nginx的请求许可模块。

ngx_http_access_module模块允许通过地址限制客户端的访问权限。
访问权可以通过密码或子请求的方式进行限制。同时通过密码和地址限制访问使用satisfy指令控制。
示例配置

location / {
    deny  192.168.1.1;
    allow 192.168.1.0/24;
    allow 10.1.1.0/16;
    allow 2001:0db8::/32;
    deny  all;
}

检测原则是按顺序匹配到第一条符合的规则即可,在这个例子中,只允许IPv4地址段192.168.1.0/24和10.1.1.0/16并且不包括192.168.1.1的客户端访问,只允许2001:0db8::/32段的IPv6地址客户端访问。为防止使用很多IP地址进行配置,可以用ngx_http_geo_module模块进行更好的配置。

allow

语法:allow address | CIDR | unix: | all;
默认:—
上下文:http, server, location, limit_except

定义一个网络或地址的可访问权限,如果使用unix:(1.5.1+),则允许所有UNIX-domain的socket连接

deny

语法:deny address | CIDR | unix: | all;
默认:—
上下文:http, server, location, limit_except

定义一个网络或地址的禁止访问权限,如果使用unix:(1.5.1+),则禁止所有UNIX-domain的socket连接

nginx http_core模块内嵌变量

此页面版本:2016-06-15
本文介绍nginx的http_core模块的内嵌变量

ngx_http_core_module模块支持内嵌变量与Apache服务器变量名称一致。首先,这些变量体现请求头域,如$http_user_agent,$http_cookie等。还有其他的变量:

$arg_name
在请求中name参数


$args
请求的所有参数


$binary_remote_addr
客户端地址的二进制形式,值的长度总是4个字节


$body_bytes_sent
发送到客户端的字节数,不算响应头。这个变量与Apache的mod_log_config模块的“%B”参数兼容。


$bytes_sent
发送到带客户端的字节数(1.3.8+,1.2.5+)


$connection
连接序列号(1.3.8+,1.2.5+)


$connection_requests
当前连接中的请求数(1.3.8+,1.2.5+)


$content_length
请求头中的“Content-Length”


$content_type
请求头中的“Content-Type”


$cookie_name
名称为name的cookie的值


$document_root
当前请求的root或alias指令的值


$document_uri
同$uri


$host
按此优先级:请求中的Host字段,或服务器名称匹配请求的值


$hostname
主机名


$http_name
任意请求头域,变量名的最后一部分name是将域转为小写并将“-”替换为“_”


$https
如果通过SSL连接则值为“on”,否则是空字符串


$is_args
如果请求有参数则值为“?”,否则是空字符串


$limit_rate
设置此值开启响应的限速


$msec
当前时间的秒数,精确到毫秒(1.3.9+, 1.2.6+)


$nginx_version
nginx版本


$pid
工作进程的PID


$pipe
如果请求是流水线(pipelined)值为“p”,否则为“.”(1.3.12+, 1.2.7+)


$proxy_protocol_addr
代理协议头中的客户端地址,如果没有则为空字符串(1.5.12+)
代理协议必须提前在listen指令的proxy_protocol参数开启。


$proxy_protocol_port
代理协议头中的客户端端口号,如果没有则为空字符串(1.11.0+)
代理协议必须提前在listen指令的proxy_protocol参数开启。


$query_string
同$args


$realpath_root
将一个绝对路径与符号连接解析成相对路径


$remote_addr
客户端地址


$remote_port
客户端端口


$remote_user
Basic验证的用户名


$request
完整的请求行


$request_body
请求内容


$request_body_file
带有请求内容的临时文件名称


$request_completion
如果请求完成了,值为“OK”,否则为空字符串


$request_filename
当前请求的文件路径,基于root和alias指令与请求URI


$request_id
唯一的请求标识符,从16个随机字节生成,为16进制(1.11.0)


$request_length
请求长度(包括请求行、头部、正文内容)(1.3.12+, 1.2.7+)


$request_method
请求方法,通常是“GET”或“POST”


$request_time
处理请求的时间秒数,精确到毫秒(1.3.9+, 1.2.6+)


$request_uri
完整的请求URI(带参数)


$scheme
请求模式,“http”或“https”


$sent_http_name
任意响应头域,最后一部分name将名称转为小写并将“-”替换为“_”


$server_addr
服务器接收请求的地址
计算该变量的值需要一次系统调用,要避免系统调用,listen指令必须定义地址并使用bind参数


$server_name
处理请求的服务器名称


$server_port
处理请求的服务器端口


$server_protocol
请求协议,通常是“HTTP/1.0”,“HTTP/1.1”或“HTTP/2.0”


$status
响应状态码(1.3.2+, 1.2.2+)


$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space
客户端TCP连接的信息,在支持TCP_INFO socket选项的系统中可用


$time_iso8601
ISO 8601格式的本地时间(1.3.12+, 1.2.7+)


$time_local
普通日志格式的本地时间(1.3.12+, 1.2.7+)


$uri
当前请求的标准化URI
$uri的值在处理请求时可能会发生变化,如内部重定向或使用索引文件

Nginx中文文档-ngx_http_core_module(T-V)

本文档包含以下指令:tcp_nodelay、tcp_nopush、try_files、types、types_hash_bucket_size、types_hash_max_size、underscores_in_headers、variables_hash_bucket_size、variables_hash_max_size

tcp_nodelay

语法:tcp_nodelay on | off
默认:tcp_nodelay on
上下文: http, server, location

启用或禁用TCP_NODELAY选项。该功能仅在连接已过渡到keep-alive状态下有效。

tcp_nopush

语法:tcp_nopush on | off
默认:tcp_nopush off
上下文:http, server, location

启用或禁用tcp_nopush功能,在FreeBSD系统上通过TCP_NOPUSH socket选项实现,在Linux通过TCP_CORK socket选项实现。只有在sendfile生效状态下才能启用。启用该选项将允许:

  • Linux和FreeBSD 4.*系统下在一个包中发送响应头和文件开头
  • 在满包中发送一个文件

try_files

语法:try_files fileuri;
try_files file … =code;
默认:—
上下文:server, location

按指定顺序检测文件是否存在,并返回第一个找到的文件,该过程在当前上下文中执行。文件的路径是由root和alias指令以及file参数构成。有可能会通过在名字后面添加“/”检测目录是否存在,例如“$uri/”。如果没有找到任何的文件,则会产生一个内部重定向到最后一个参数uri指定的文件:

location /images/ {
    try_files $uri /images/default.gif;
}

location = /images/default.gif {
    expires 30s;
}

最后一个参数可以指向一个location,如下面的例子所示。从0.7.51版本开始,最后一个参数也可以是一个code

location / {
    try_files $uri $uri/index.html $uri.html =404;
}

代理Mongrel的例子:

location / {
    try_files /system/maintenance.html
              $uri $uri/index.html $uri.html
              @mongrel;
}

location @mongrel {
    proxy_pass http://mongrel;
}

Drupal/FastCGI举例:

location / {
    try_files $uri $uri/ @drupal;
}

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME     $fastcgi_script_name;
    fastcgi_param QUERY_STRING    $args;

    ... other fastcgi_param's
}

location @drupal {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    fastcgi_param SCRIPT_NAME     /index.php;
    fastcgi_param QUERY_STRING    q=$uri&$args;

    ... other fastcgi_param's
}

下面的例子中,

location / {
    try_files $uri $uri/ @drupal;
}

try_files指令等价于:

location / {
    error_page 404 = @drupal;
    log_not_found off;
}

下面的例子,

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;

    ...
}

try_files指令在将请求发送到FastCGI服务器之前检测文件是否存在。
Wordpress 和 Joomla的例子:

location / {
    try_files $uri $uri/ @wordpress;
}

location ~ \.php$ {
    try_files $uri @wordpress;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    ... other fastcgi_param's
}

location @wordpress {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    ... other fastcgi_param's
}

types

语法:types { … }
默认:types {
text/html html;
image/gif gif;
image/jpeg jpg;
}
上下文:http, server, location

响应的MIME与文件扩展的对照表,大小写不敏感。多个扩展名可以映射为同一个类型:

types {
    application/octet-stream bin exe dll;
    application/octet-stream deb;
    application/octet-stream dmg;
}

在conf/mime.types文件中定义了一个比较完整的映射表。
要定义一个特殊的location,所有的MIME类型都是application/octet-stream,可以用下面的配置:

location /download/ {
    types        { }
    default_type application/octet-stream;
}

types_hash_bucket_size

语法:types_hash_bucket_size size
默认:types_hash_bucket_size 64
上下文:http, server, location

设置一个类型哈希表的大小。1.5.13版本之前,默认值的大小取决于CPU缓存行。

types_hash_max_size

语法:types_hash_max_size size
默认:types_hash_max_size 1024
上下文:http, server, location

设置类型哈希表最大的大小。

underscores_in_headers

语法:underscores_in_headers on | off
默认:underscores_in_headers off
上下文:http, server

启用或禁用客户端请求头域中的下划线。如果禁用了此功能,客户端请求头域中的下划线会被认为是无效的。
如果该指令定义在sever块中,只对默认的服务器有效。该值同样作用于监听了同一端口和IP的虚拟主机。

variables_hash_bucket_size

语法:variables_hash_bucket_size size
默认:variables_hash_bucket_size 64
上下文:http

设置一个变量哈希表的大小。

variables_hash_max_size

语法:variables_hash_max_size size
默认:variables_hash_max_size 1024
上下文:http

设置最大的变量哈希表大小。1.5.13版本以前,默认值是512.

Nginx中文文档-ngx_http_core_module(R-S)

本文档包含以下指令:read_ahead、recursive_error_pages、request_pool_size、reset_timedout_connection、resolver、resolver_timeout、root、satisfy、send_lowat、send_timeout、sendfile、sendfile_max_chunk、server、server_name、server_name_in_redirect、server_names_hash_bucket_size、server_names_hash_max_size、server_tokens

read_ahead

语法:read_ahead size
默认:read_ahead 0
上下文:http, server, location

设置内核预读取文件的数量。
在linux系统上,使用posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)系统调用,所以size参数被忽略。
在FreeBSD系统上,使用fcntl(O_READAHEAD, size)系统调用,从FreeBSD9.0开始可用,FreeBSD 7需要安装补丁。

recursive_error_pages

语法:recursive_error_pages on | off
默认:recursive_error_pages off
上下文:http, server, location

启用或禁用使用error_page指令产生的重定向,重定向的次数会有限制。

request_pool_size

语法:request_pool_size size
默认:request_pool_size 4k
上下文: http, server

精确调整每个请求的内存配额,这个指令对性能影响极小,一般不使用。

reset_timedout_connection

语法:reset_timedout_connection on | off
默认:reset_timedout_connection off
上下文:http, server, location

启用或禁用重置超时连接,重置表现如下。在关闭一个SOCKET前,SO_LINGER选项被设置成超时时间0。当SOCKET已经关闭时,RST标识会发送到客户端,该SOCKET的所有相关内存被释放。这有助于避免一个已经关闭了的SOCKET在FIN_WAIT1状态保持很长时间。
注意,超时的keep-alive连接会正常关闭。

resolver

语法:resolver address… [valid=time] [ipv6=on|off]
默认:—
上下文: http, server, location

配置了上游服务器的域名解析服务器,例如:
resolver 127.0.0.1 [::1]:5353;
address可以定义成域名或IP地址,和可选的端口号(1.3.1, 1.2.2)。
如果端口号没有定义,使用默认的53端口。域名服务器会采用轮询机制。
在1.1.7之前,只能配置一个服务器,服务器名称从1.3.1和1.2.2版本开始支持IPv6。
默认情况下,nginx在解析名称时会同时查找IPv4和IPv6,如果不需要IPv6,可以使用ipv6=off关闭。
解析IPv6的地址从1.5.8版本起开始支持。
默认情况下,nginx使用TTL对结果进行缓存,可以通过可选参数valid改变它:
resolver 127.0.0.1 [::1]:5353 valid=30s;
在1.1.9之前,不能改变缓存时间,nginx总是会缓存5分钟。

resolver_timeout

语法:resolver_timeout time
默认:resolver_timeout 30s
上下文:http, server, location

设置解析的超时时间,例如:
resolver_timeout 5s;

root

语法:root path
默认:root html
上下文:http, server, location, if in location

设置请求的根目录,例如下面的配置:

location /i/ {
    root /data/w3;
}

/data/w3/i/top.gif文件会作为“/i/top.gif”请求的响应发送出去。
path的值可以包含变量,除了$document_root 和 $realpath_root
文件路径只是简单的将URI跟在root指令设置的根目录之后,如果URI需要改变,需要使用alias指令。

satisfy

语法:satisfy all | any
默认:satisfy all
上下文:http, server, location

设置由ngx_http_access_module、ngx_http_auth_basic_module及ngx_http_auth_request_module指令制定的访问规则需要全部匹配(all)还是只要匹配一个(any)即可。
例子:

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

send_lowat

语法:send_lowat size
默认:send_lowat 0
上下文:http, server, location

如果设置非零的值,nginx会尝试通过kqueue方法的NOTE_LOWAT标识或SO_SNDLOWAT socket选项的方式将发送到客户端的socket数降到最低。这两种情况都要用到定义的size
该指令在Linux, Solaris, 和 Windows系统上会被忽略。

send_timeout

语法:send_timeout time
默认:send_timeout 60s
上下文: http, server, location

设置客户端传输超时时间。超时时间只作用于两次成功的写请求之间,并非是整个的响应之间的传输时间。如果客户端在超时时间已到还没有收到任何数据,就会关闭连接。

sendfile

语法:sendfile on | off
默认:sendfile off
上下文: http, server, location, if in location

开启或禁用sendfile函数的使用。
从0.8.12版本开始在FreeBSD 5.2.1,aio通过sendfile函数预加载数据:

location /video/ {
    sendfile       on;
    tcp_nopush     on;
    aio            on;
}

在这个配置中,sendfile函数如果带着SF_NODISKIO标识会引起磁盘I/O不会阻塞,数据不在内存里,nginx会初始化异步读取一个字节的数据。首次读取时FreeBSD会读取128K字节的数据到内存中,再次读取时会读取16K字节的块。可以在read_ahead指令中改变。
1.7.11版本之前,预加载可以通过aio sendfile开启。

sendfile_max_chunk

语法:sendfile_max_chunk size
默认:sendfile_max_chunk 0
上下文:http, server, location

当设置为一个非零的值,会限制调用一次sendfile函数能够传输的数据量。如果不限制,工作进程会被一个最快的连接完全抢占。

server

语法:server { … }
默认:—
上下文:http

设置一个虚拟主机。在基于IP和基于主机名的虚拟主机之间划分的界限并不明确。listen指令为服务器描述了所有应该接受请求的地址和端口,server_name指令列出了所有的服务器名称。

server_name

语法:server_name name
默认:server_name “”
上下文:server

设置虚拟主机的名称,例如:

server {
    server_name example.com www.example.com;
}

第一个名称是主要的名称。
服务器名称可以用星号“*”代替名称的一部分或几部分:

server {
    server_name example.com *.example.com www.example.*;
}

这些名称叫做通配符名称。
前两个可以合并成一个:

server {
    server_name .example.com;
}

可以在server_name中使用正则表达式,前面用“~”:

server {
    server_name www.example.com ~^www\d+\.example\.com$;
}

正则表达式从0.7.40版本开始支持捕获,捕获可以在之后用在其他指令中。

server {
    server_name ~^(www\.)?(.+)$;

    location / {
        root /sites/$2;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

名称中的正则表达式捕获创建的变量(0.8.25版本起)可以在之后的其他指令中使用:

server {
    server_name ~^(www\.)?(?.+)$;

    location / {
        root /sites/$domain;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

如果指令的参数设置成“$hostname”(0.9.4),机器的名称会被使用。
也可以定义空的名称(0.7.11):

server {
    server_name www.example.com "";
}

它允许服务器处理请求头不带Host域的请求。
0.8.48之前,默认使用机器的hostname。
在通过名称查找虚拟主机的过程中,如果名称匹配了超过一个变量(如通配符和正则都匹配了),会选择最先匹配的,使用下面的优先级:

  • 具体名称
  • 最长的以*开头的通配符,如“*.example.com”
  • 最长的以*结尾的通配符,如“mail.*”
  • 首先匹配的正则表达式(按在配置文件中出现的顺序)

server_name_in_redirect

语法:server_name_in_redirect on | off
默认:server_name_in_redirect off
上下文: http, server, location

开启或禁用在server_name指令中定义的主要服务器名称的重定向功能。当主要服务器名称禁用了,请求头域中的“Host”将被使用。如果当前没有这个域,会使用服务器的IP。

server_names_hash_bucket_size

语法:server_names_hash_bucket_size size
默认:server_names_hash_bucket_size 32|64|128
上下文: http

设置server_name一个bucket的哈希表的大小,默认值依赖于当前处理器的缓存行大小。

server_names_hash_max_size

语法:server_names_hash_max_size size
默认:server_names_hash_max_size 512
上下文:http

设置server_name哈希表最大的大小。

server_tokens

语法:server_tokens on | off | string
默认:server_tokens on
上下文: http, server, location

开启或关闭在nginx错误页和http响应头的Server域中的版本号。
从1.9.13开始这个值可以通过string变量进行定义,空字符串将禁用Server域的显示。

Nginx中文文档-ngx_http_core_module(M-P)

本文档包含以下指令:max_ranges、merge_slashes、msie_padding、msie_refresh、open_file_cache、open_file_cache_errors、open_file_cache_min_uses、open_file_cache_valid、output_buffers、port_in_redirect、postpone_output

max_ranges

语法:max_ranges number;
默认:—
上下文:http, server, location
版本:1.1.2+

限制请求中byte-range的最大数值,超过该值的请求会忽略byte-range。默认不限制该值,如果该值为0,则完全禁用byte-range功能。

merge_slashes

语法:merge_slashes on | off
默认:merge_slashes on
上下文:http, server

开启或禁用URI中的多个“/”的合并功能。
注意,对于正确的匹配前缀和正则表达式location,合并功能使必要的。如果不进行合并,“//scripts/one.php”请求将不会匹配以下location:

location /scripts/ {
    ...
}

还有可能被处理为一个静态文件。所以应该把它转换为“/scripts/one.php”。
如果一个URI包含了base64编码的参数,将合并功能关闭是必要的,因为在base64中“/”是一个合法的字符。但是,为了安全性考虑,最好不要将这个配置关闭。
如果该指令定义在server层级,这个值只能应用在带default的server中。这个值同样应用于所有监听同一个IP和端口的虚拟主机。

msie_padding

语法:msie_padding on | off
默认:msie_padding on
上下文: http, server, location

启用或禁用注释填充功能。当返回码大于400时,对于IE浏览器,是否需要填充注释信息,以便返回的内容达到512字节。(译者注:IE对于错误的网页状态码的处理有两种情况,如果经过gzip后小于512个字节,IE会出现默认的错误提示页;如果超过512个字节,则可以显示我们自己定义的错误页的内容,如个性化的404提示页)

msie_refresh

语法:msie_refresh on | off
默认:msie_refresh off
上下文: http, server, location

为IE开启或者关闭用页面刷新取代页面重定向的功能。

open_file_cache

语法:open_file_cache off
open_file_cache max=N [inactive=time]
默认:open_file_cache off
上下文:http, server, location

配置一个缓存,可以存储:

  • 打开文件描述符,包括文件大小、修改时间
  • 目录的信息
  • 文件查找错误,如“找不到文件”、“无权限读取文件”

错误数据的缓存可以单独通过open_file_cache_errors指令开启。
该指令有以下参数:
max
设置缓存中元素的最多个数;当缓存满了的时候,会用LRU方式删除最近最少使用的元素。
inactive
定义了多长时间没有使用到的缓存就被清除,默认是60秒。
off
关闭缓存
例子:

open_file_cache          max=1000 inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

open_file_cache_errors

语法:open_file_cache_errors on | off
默认:open_file_cache_errors off
上下文:http, server, location

开启或关闭文件查找错误缓存功能,该功能是open_file_cache定义的。

open_file_cache_min_uses

语法:open_file_cache_min_uses number
默认:open_file_cache_min_uses 1
上下文: http, server, location

设置在由open_file_cache指令的inactive参数配置的超时时间内, 文件应该被访问的最小number。如果访问次数大于等于此值,文件描述符会保留在缓存中,否则从缓存中删除。

open_file_cache_valid

语法:open_file_cache_valid time
默认:open_file_cache_valid 60s
上下文:http, server, location

设置open_file_cache指令中的元素检测的时间间隔。

output_buffers

语法:output_buffers number size
默认:output_buffers 2 32k
上下文:http, server, location

设置读取磁盘文件缓存的数量和大小。
在1.9.5版本之前,默认值为1 32k。

port_in_redirect

语法:port_in_redirect on | off
默认:port_in_redirect on
上下文:http, server, location

开启或关闭nginx发起重定向时指定端口。
重定向中首要主机名的使用由server_name_in_redirect指令控制。

postpone_output

语法:postpone_output size
默认:postpone_output 1460
上下文:http, server, location

如果可能,到客户端的数据将被推迟发送,直到nginx需要发送的数据至少有size字节。 设置为0将关闭推迟发送的功能。

Nginx中文文档-ngx_http_core_module(L)

本文档包含以下指令:large_client_header_buffers、limit_except、limit_rate、limit_rate_after、lingering_close、lingering_time、lingering_timeout、listen、location、log_not_found、log_subrequest

large_client_header_buffers

语法:large_client_header_buffers number size;
默认:large_client_header_buffers 4 8k;
上下文:http, server

设置读取大请求头最大的缓存数和缓冲区大小。一个请求不能超过缓冲区,否则会返回414状态码(请求URI过长)。一个请求头域也不能超过一个缓冲区的大小,否则会返回400状态码。缓冲区只有在需要的时候才会被分配。默认情况下,缓冲区大小为8K。如果请求处理完成后进入了keep-alive状态,缓冲区会被释放。

limit_except

语法:limit_except method … { … }
默认:–
上下文:location

限制一个location中允许的HTTP方法。method参数可以是以下之一:GET、HEAD、POST、PUT、DELETE、MKCOL、COPY、MOVE、OPTIONS、PROPFIND、PROPPATCH、LOCK、UNLOCK及PATCH。允许GET方式会同时允许HEAD方法。其他的可以通过ngx_http_acces_module及ngx_http_auth_basic_module指令访问:

limit_except GET {
    allow 192.168.1.0/32;
    deny  all;
}

请注意,这将限制除了GET和HEAD方法之外的所有请求。

limit_rate

语法:limit_rate rate;
默认:limit_rate 0;
上下文:http, server, location, if in location

限制响应数据传输速率。rate定义了每秒的字节数。0值表示不限制速度。限制针对于一个请求,如果客户端同时打开2个连接,整体速度会是设置值的2倍。
速度限制也可以在$limit_rate变量中设置。一般用于在特定情况下进行不同限速:

server {

    if ($slow) {
        set $limit_rate 4k;
    }

    ...
}

限速还可以在代理服务器的响应头的X-Accel-Limit-Rate中设置。该功能可以使用proxy_ignore_headers、fastcig_ignore_headers、uwsgi_ignore_headers和scgi_ignore_headers指令中禁用。

limit_rate_after

语法:limit_rate_after size;
默认:limit_rate_after 0;
上下文:http, server, location, if in location
版本:0.8.0+

设置初始值,响应传输的数据量超过这个初始值后,就会进行限速。
例子:

location /flv/ {
    flv;
    limit_rate_after 500k;
    limit_rate       50k;
}

lingering_close

语法:lingering_close off | on | always;
默认:lingering_close on;
上下文:http, server, location
版本:1.1.0,1.0.6

控制nginx如何关闭客户端连接。
默认值on通知nginx在完全关闭连接前等待并处理额外的数据,如果客户端仍然在传输数据。
always值会使nginx无条件的等待和处理客户端的额外数据。
off值告诉nginx不要等待更多的数据,立即关闭连接。这种行为破坏了协议,不应该在正式的环境中使用。

lingering_time

语法:lingering_time time;
默认:lingering_time 30s;
上下文: http, server, location

当lingering_close生效时,定义了nginx最长处理额外数据的时间。超过这个时间,连接就会被关闭,即使还有更多的数据。

lingering_timeout

语法:lingering_timeout time;
默认:lingering_timeout 5s;
上下文:http, server, location

当lingering_close生效时,该指令定义了等待客户端传输更多数据的最大等待时间。如果这个期间内没有数据接收到,连接将被关闭。否则nginx继续接收处理数据。“等待-读取-忽略”循环将会重复,不会比lingering_time指令中定义的长。

listen

语法:listen address[:port] [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

listen port [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

listen unix:path [default_server] [ssl] [http2 | spdy] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
默认:listen *:80 | *:8000;
上下文:server

设置接受请求的IP的地址和端口,或UNIX域的socket路径。可以同时指定address和port也可以只指定port或只指定address。地址可以是一个主机名,举个例子:

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPv6地址(0.7.36版本起)需要在方括号中指定:

listen [::]:8000;
listen [::1];

UNIX socket(0.8.21版本起)定义以unix:开头:
listen unix:/var/run/nginx.sock;
如果只设置了address,会使用80端口。
如果当前指令不存在,80被占用,nginx使用超级用户权限运行,则使用8000端口。
如果存在default_server参数,这个server会成为默认的server。如果所有的指令中都没有定义default_server参数,则第一个会成为默认的。
在0.8.21之前这个参数叫做default
ssl参数(0.7.14版本起)允许定义所有该端口的连接只会接收SSL模式的。这可以使服务器同时处理HTTP和HTTPS请求的配置更简洁。
http2参数(1.9.5版本起)配置了允许HTTP2连接的端口。一般地,这个参数与ssl一同定义,但nginx可以不配置SSL单独接受HTTP2请求。(译者注:目前所有浏览器只支持SSL的http2协议)
spdy参数(1.3.15版本-1.9.4版本)允许本端口接收SPDY连接。一般会同时定义ssl参数,但nginx支持不使用SSL只开启SPDY。(译者注:建议改用HTTP2)
proxy_protocol参数(1.5.12版本起)允许所有通过到本端口的连接使用PROXY协议。
listen指令可以有很多附加的参数定义socket相关的系统调用。这些参数可以定义在任何一个listen指令中,但只能有一个地址端口对。
0.8.21前,只能在listen指令中有default参数时定义。
setfib=number
该参数(0.8.44版本起)为监听的socket设置了相关的路由表、FIB(SO_SETFIB选项)。目前只在FreeBSD系统中可用。
fastopen=number
为监听的socket开启TCP快速开启功能(1.5.8版本起),并限制了未完成三次握手的连接队列的最大长度。
不要开启这个功能,除非服务器可以处理超过一次收到相同的SYN数据包。
backlog=number
设置等待连接队列的最大长度。默认情况下,该参数在FreeBSD、DragonFly BSD及Mac OS X系统中为-1,其他系统中是511。
rcvbuf=size
设置socket接收缓冲区(SO_RCVBUF选项)大小。
sndbuf=size
设置socket发送缓冲区(SO_SNDBUF选项)大小。
accept_filter=filter
设置socket可接受的过滤器(SO_ACCEPTFILTER选项)名称,过滤器是在连接进入传给accept函数前工作。只有FreeBSD和NetBSD 5.0以上版本系统可以使用。可能的值是dataready和httpready。
deferred
在Linux系统上使用延迟接受函数(TCP_DEFER_ACCEPT选项)。
bind
为地址端口对分开调用bind函数。这个是很有用的,尤其是在多个listen指令用相同的端口但不同的地址,并且有一个listen指令监听所有地址的指定端口,nginx将会绑定*:port。需要注意的是,getsockname函数的系统调用决定了接受连接的地址。如果setfib、backlog、rcvbuf、sndbuf、accept_filter、deferred、ipv6only或so_keepalive参数使用了,则给定的地址端口对总会被分离调用bind函数。
ipv6only=on|off
该参数(0.7.42版本起)定义了(通过IPV6_V6ONLY socket选项)在通配符地址[::]是只接受IPv6连接还是IPv6和IPv4都支持。该参数默认是打开的。只能在启动时设置一次。
在1.3.4之前版本中,如果该参数没有给出,则操作系统的设置将影响socket连接。
reuseport
该参数(1.9.1版本起)指定了为每一个工作进程创建单独的socket监听(通过SO_REUSERPORT选项),允许内核将连接分配到不同的工作进程中。目前只在Linux 3.9以上版本及DragonFly BSD系统上可用。
错误的使用这个选项会有安全问题。
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
该参数(1.1.11版本起)配置了socket的“TCP keepalive”行为。如果该参数没有定义,则操作系统会影响socket的设置。如果开启了此功能,SO_KEEPALIVE选项将开启,否则将关闭。一些系统允许设置每一个socket的TCP的keepalive参数,通过TCP_KEEPIDLE、TCP_KEEPINTVL和TCP_KEEPCNT选项。在这些系统中(目前是Linux2.4以上、NetBSD 5以上以及FreeBSD 9.0稳定版),可以通过keepidle、keepintvl及keepcnt参数设置。如果忽略了1个或2个参数,系统默认值将影响socket的设置。例如,
so_keepalive=30m::10
将会设置空闲超时30分钟,探测间隔由系统默认值指定,探测数设为10。
例子:
listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

location

语法:location [ = | ~ | ~* | ^~ ] uri { … }
location @name { … }
默认:–
上下文:server, location

设置一个请求URI的配置项。
匹配是对一个标准URI经过解码,处理相对路径并且压缩2个或两个以上连续的斜杠为1个斜杠后的URI。
location可以由一个字符串前缀或正则表达式定义。正则表达式由“~*”(不区分大小写),或“~”(区分大小写)定义。为了检查location是否匹配请求,nginx首先检测定义的前缀字符串。其中,前缀字符串匹配最长的前缀会被选中并被记录。然后会检测正则表达式,按照出现在配置文件中的顺序进行检测。正则表达式搜索将会在第一次匹配成功后停止,相应的配置将被使用。如果没有找到正则表达式匹配的,就会在使用之前记录下来的前缀字符串。
location块可以被嵌套,有下面的几个例外。
在大小写不敏感的操作系统(如Mac OS X和Cygwin上),前缀字符串忽略大小写(0.7.7版本起)。匹配限制于一字节场景。
正则表达式可以包含捕获(0.7.40版本起),可以在其他的指令中使用。
如果最长的前缀匹配location,该location有“^~”修饰,正则表达式不会被检查。
同样,使用“=”修饰符,location会精确匹配URI。如果精确匹配到,则匹配将停止。例如,如果“/”频繁的请求,定义“location = /”会加快处理这些请求,因为匹配过程之后进行一次,就会停止。这种location显然不能包含内嵌location。
在0.7.1到0.8.41版本中,如果一个请求匹配的location前缀没有“=”和“^~”修饰符,搜索仍会终止,正则表达式不会被检测。
用几个例子来说明解释下:

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

“/”请求将匹配配置A,“/index.html”请求将匹配配置B,“/documents/document.html”将匹配配置C,“/images/1.gif”请求将匹配配置D,“/document/1.jpg”请求将匹配配置E。
“@”前缀定义了一个命名的location。这种location并不会应用于任何请求的处理,而是用于请求的重定向。它们不能被嵌套,也不能包括嵌套的location。
如果location由一个以斜杠结束的前缀字符串定义,请求被proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass或memcached_pass之一处理,特殊处理程序将运行。在响应URI等于这些字符串但并没有末尾的斜杠时,将会返回301状态码,重定向到带斜线的URI。如果不希望这样,需要定义一个精确匹配的location如下:

location /user/ {
    proxy_pass http://user.example.com;
}
location = /user {
    proxy_pass http://login.example.com;
}

log_not_found

语法:log_not_found on | off;
默认:log_not_found on;
上下文:http, server, location

启用或禁用记录找不到文件错误到错误日志中的功能。

log_subrequest

语法:log_subrequest on | off;
默认:log_subrequest off;
上下文:http, server, location

开启或关闭记录子请求到访问日志的功能。