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

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

Nginx中文文档-ngx_http_core_module(I-K)

本文档包含以下指令:if_modified_since、ignore_invalid_headers、internal、keepalive_disable、keepalive_requests、keepalive_timeout

if_modified_since

语法:if_modified_since off | exact | before;
默认:if_modified_since exact;
上下文: http, server, location
版本:0.7.24+

定义如何比较请求头中的“If-Modified-Since”时间:
off
忽略“If-Modified-Since”请求头(0.7.34版本起)
exact
精确匹配
before
响应的修改时间小于或等于请求头中的“If-Modified-Since”值

ignore_invalid_headers

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

控制头域中无效的名字是否需要被忽略。正确的名字是由英文字母、数字、连字符及可能的下划线(在underscores_in_headers指令中控制)组成。
当这个指令在server的上下文中定义,只有在server是一个默认的设置时才有效。指定的值同样对监听了相同的端口和地址的虚拟主机有效。

internal

语法:internal;
默认:–
上下文:location

定义指定的location只能被用于内部请求。对于外部的请求,会返回404错误码。内部请求有下面的这些:

  • 通过error_page、index、random_index和try_files指令重定向的请求
  • 根据上游服务器响应头中的“X-Accel-Redirect”进行重定向的请求
  • 通过ngx_http_ssi_module模块的“include virtual”命令及ngx_http_addition_module模块指令提交的子请求
  • 通过rewrite指令修改的请求

例子:

error_page 404 /404.html;

location /404.html {
    internal;
}

为了防止错误的配置导致循环重定向,每个请求的内部重定向限制在10次。如果达到了限制,会返回500错误码。这种情况下,可以在错误日志中看到“rewrite or internal redirection cycle”。

keepalive_disable

语法:keepalive_disable none | browser …;
默认:keepalive_disable msie6;
上下文:http, server, location

对非正常行为的浏览器禁用keep-alive连接。browser参数指定了哪些浏览器会被影响。msie6禁用了老版本的IE在收到post请求的keep-alive连接。safari值禁用了在Mac OS X及类Mac OS X操作系统上的Safari和类Safari浏览器的keep-alive连接。none值允许所有浏览器保持连接。
在1.1.18前,safari匹配所有操作系统上的Safari和类Safari浏览器,默认情况下禁用keep-alive。

keepalive_requests

语法:keepalive_requests number;
默认:keepalive_requests 100;
上下文:http, server, location
版本:0.8.0+

设置一个连接中最大的请求数。超过请求数最大值,连接将被关闭。

keepalive_timeout

语法:keepalive_timeout timeout [header_timeout];
默认:keepalive_timeout 75s;
上下文:http, server, location

第一个参数定义了客户端发起连接在服务端保持开启的超时时间。0值表示禁用客户端发起的连接的保持。第二个可选参数设置了响应头中“Keep-Alive: timeout=time” 的值。两个参数可能不同。
“Keep-Alive: timeout=time”头会被Mozilla和Konqueror浏览器识别,IE会在60秒后自动关闭连接。