Nginx模块参考手册:HTTP核心模块

15094S963-1.jpg

这些模块默认会全部编译进Nginx,除非手工指定某个模块在configure时排除。

摘要

Nginx处理HTTP的核心功能模块

指令

aio

语法:aio [on|off|sendfile] 

默认值:off

使用字段:http, server, location

这个指令在Linux内核2.6.1922以上版本可以使用,对于Linux内核,这个指令需要配合directio指令,使用这个指令将自动关闭sendfile支持。

location /video {
    aio on; 
    directio 512; 
    output_buffers 1 128k;
}

在FreeBSD5.2.1之前版本和Nginx0.8.12,你必须手工关闭sendfile:

location /video {
    aio on; 
    sendfile off;
    output_buffers 1 128k;
}

同样也可以和sendfile一起使用(FreeBSD5.2.1和Nginx0.8.12):

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

alias

语法:alias file-path|directory-path; 

默认值:no

使用字段:location

这个指令为一个location指定一个路径,注意它可能类似于root,但是document root没有改变,请求只是使用了别名目录的文件。这个location自身为“丢弃的”,具体请看下面的例子:

location  /i/ {
  alias  /spool/w3/images/;
}

上个例子总,请求”/i/top.gif”将返回这个文件: ”/spool/w3/images/top.gif”。正如你所看到的,uri中location后面的部分会追加到这个目录后面,而location自身是“丢弃的”,如果使用root指令的话会进行完整的追加,如上例中,如果使用root指令则返回:”/spool/w3/images/i/top.gif”

Alias同样可以用于带正则表达式的location,如:

location ~ ^/download/(.*)$ {
  alias /home/website/files/$1;
}

请求”/download/book.pdf”将返回”/home/website/files/book.pdf”。同样注意,uri中location后面的部分会追加到这个目录后面。

同样,也可以在别名目录字段中使用变量。

chunked_transfer_encoding

语法:chunked_transfer_encoding on|off; 

默认值:on

使用字段:http, server, location

指定是否在响应时启用chunked编码(只能使用于HTTP1.1版本以上的连接)。

client_body_in_file_only

语法:client_body_in_file_only on|off 

默认值:off 

使用字段:http, server, location 

这个指令始终存储一个连接请求实体到一个文件即使它只有0字节。

注意:如果这个指令打开,那么一个连接请求完成后,所存储的文件并不会删除。

这个指令可以用于debug调试和嵌入式Perl模块中的$r→request_body_file方法。

client_body_in_single_buffer

语法:client_body_in_single_buffer 

默认值:off 

使用字段:http, server, location 

这个指令(0.7.58版本)指定是否将客户端连接请求完整的放入一个缓冲区,当使用变量$request_body时推荐使用这个指令以减少复制操作。

如果无法将一个请求放入单个缓冲区,将会被放入磁盘。

client_body_buffer_size

语法:client_body_buffer_size the_size 

默认值:8k/16k 

使用字段:http, server, location 

这个指令可以指定连接请求实体的缓冲区大小。

如果连接请求超过缓存区指定的值,那么这些请求实体的整体或部分将尝试写入一个临时文件。

默认值为两个内存分页大小值,根据平台的不同,可能是8k或16k。

当请求头中的Content-Length字段小于指定的buffer size,那么Nginx将使用较小的一个,所以nginx并不总是为每一个请求分配这个buffer size大小的buffer。

client_body_temp_path

语法:client_body_temp_path dir-path [ level1 [ level2 [ level3 ] 

默认值:client_body_temp 

使用字段:http, server, location 

指令指定连接请求实体试图写入的临时文件路径。

可以指定三级目录结构,如:

client_body_temp_path  /spool/nginx/client_temp 1 2;那么它的目录结构可能是这样:/spool/nginx/client_temp/7/45/00000123457

client_body_timeout

语法:client_body_timeout time

默认值:60 

使用字段:http, server, location 

指令指定读取请求实体的超时时间。

这里的超时是指一个请求实体没有进入读取步骤,如果连接超过这个时间而客户端没有任何响应,Nginx将返回一个”Request time out” (408)错误

client_header_buffer_size

语法:client_header_buffer_size size 

默认值:1k 

使用字段:http, server 

指令指定客户端请求头部的缓冲区大小

绝大多数情况下一个请求头不会大于1k

不过如果有来自于wap客户端的较大的cookie它可能会大于1k,Nginx将分配给它一个更大的缓冲区,这个值可以在large_client_header_buffers里面设置。

client_header_timeout

语法:client_header_timeout time 

默认值:60 

使用字段:http, server 

指令指定读取客户端请求头标题的超时时间。

这里的超时是指一个请求头没有进入读取步骤,如果连接超过这个时间而客户端没有任何响应,Nginx将返回一个”Request time out” (408)错误。

client_max_body_size

语法:client_max_body_size size 

默认值:client_max_body_size 1m 

使用字段:http, server, location 

指令指定允许客户端连接的最大请求实体大小,它出现在请求头部的Content-Length字段。

如果请求大于指定的值,客户端将收到一个”Request Entity Too Large” (413)错误。

记住,浏览器并不知道怎样显示这个错误。

connection_pool_size

语法:connection_pool_size the_size 

默认值:connection_pool_size the_size 256 

使用字段:http (或许可以用到其他地方?) 

为每个请求分配的内存池,内存池用于小配额内存块,如果一个块大于内存池或者大于分页大小,那么它将被分配到内存池之外,如果位于内存池中较小的分配量没有足够的内存,那么将分配一个相同内存池大小的新块,这个指令仅有相当有限的效果(来源http://markmail.org/message/b2kmrluscevimpba)

default_type

语法: default_type MIME-type 

默认值:default_type text/plain 

使用字段:http, server, location 

某个文件在标准MIME视图没有指定的情况下的默认MIME类型。

参考types。

directio

语法:directio [size|off] 

默认值:directio off 

使用字段:http, server, location 

这个参数指定在读取文件大小大于指定值的文件时使用O_DIRECT(FreeBSD, Linux),F_NOCACHE(Mac OS X)或者调用directio()函数(Solaris),当一个请求用到这个参数时会禁用sendfile,通常这个参数用于大文件。

directio  4m;

error_page

语法:error_page code [ code… ] [ = | =answer-code ] uri | @named_location 

默认值:no 

使用字段:http, server, location, location 中的if字段 

这个参数可以为错误代码指定相应的错误页面

error_page   404          /404.html;
error_page   502 503 504  /50x.html;
error_page   403          http://example.com/forbidden.html;
error_page   404          = @fetch;同样,你也可以将原有的响应代码修改为另一个响应代码,例如:
error_page 404 =200 /empty.gif;
error_page 404 =403 /forbidden.gif;另外你可以使用等号(=)指定你自己编写的错误处理程序返回相应的响应代码:
error_page   404  =  /404.php;如果在重定向时不需要改变URI,可以将错误页面重定向到一个命名的location字段中:
location / (
    error_page 404 @fallback;
)
location @fallback (
    proxy_pass http://backend;
)

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”时间 

internal

语法:internal 

默认值:no 

使用字段: location 

internal指令指定某个location只能被“内部的”请求调用,外部的调用请求会返回”Not found” (404)

“内部的”是指下列类型:

指令error_page重定向的请求。 

ngx_http_ssi_module模块中使用include virtual指令创建的某些子请求。 

ngx_http_rewrite_module模块中使用rewrite指令修改的请求。 

一个防止错误页面被用户直接访问的例子:

error_page 404 /404.html;
location  /404.html {
  internal;
}

keepalive_disable

语法:keepalive_disable [ msie6 | safari | none ]…

默认值:msie6 safari 

使用字段:http, server, location 

为某些浏览器禁用keepalive(0.9.0后版本可用),在POST请求后的MS Internet Explorer (6.0sp2以前版本)与Safari在默认情况下会禁用keepalive。

keepalive_timeout

语法:keepalive_timeout [ time ] [ time ]

默认值:keepalive_timeout 75 

使用字段:http, server, location 

参数的第一个值指定了客户端与服务器长连接的超时时间,超过这个时间,服务器将关闭连接。

参数的第二个值(可选)指定了应答头中Keep-Alive: timeout=time的time值,这个值可以使一些浏览器知道什么时候关闭连接,以便服务器不用重复关闭,如果不指定这个参数,nginx不会在应答头中发送Keep-Alive信息。(但这并不是指怎样将一个连接“Keep-Alive”)参数的这两个值可以不相同。

下面列出了一些服务器如何处理包含Keep-Alive的应答头:

  • MSIE和Opera将Keep-Alive: timeout=N头忽略。 

  • MSIE保持一个连接大约60-65秒,然后发送一个TCP RST。 

  • Opera将一直保持一个连接处于活动状态。 

  • Mozilla将一个连接在N的基础上增加大约1-10秒。 

  • Konqueror保持一个连接大约N秒。

keepalive_requests

语法:keepalive_requests n 

默认值:keepalive_requests 100 

使用字段:http, server, location 

服务器保持长连接的请求数。

large_client_header_buffers

语法:large_client_header_buffers number size 

默认值:large_client_header_buffers 4 4k/8k 

使用字段:http, server 

指定客户端一些比较大的请求头使用的缓冲区数量和大小。

请求字段不能大于一个缓冲区大小,如果客户端发送一个比较大的头,nginx将返回”Request URI too large” (414)

同样,请求的头部最长字段不能大于一个缓冲区,否则服务器将返回”Bad request” (400)。缓冲区只在需求时分开。

默认一个缓冲区大小为操作系统中分页文件大小,通常是4k或8k,如果一个连接请求最终将状态转换为keep-alive,它所占用的缓冲区将被释放。

limit_except

语法:limit_except methods {…} 

默认值:no 

使用字段:location 

指令可以在location字段中做一些http动作的限制。

ngx_http_access_module和ngx_http_auth_basic_module模块有很强的访问控制功能。

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

limit_rate

语法:limit_rate speed 

默认值:no 

使用字段:http, server, location, location中的if字段 

限制将应答传送到客户端的速度,单位为字节/秒,限制仅对一个连接有效,即如果一个客户端打开2个连接,则它的速度是这个值乘以二。

由于一些不同的状况,可能要在server字段来限制部分连接的速度,那么这个参数并不适用,不过你可以选择设置$limit_rate变量的值来达到目的:

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

同样可以通过设置X-Accel-Limit-Rate头(NginxXSendfile)来控制proxy_pass返回的应答(http代理模块)。并且不借助X-Accel-Redirect头来完成。

limit_rate_after

语法:limit_rate_after time 

默认值:limit_rate_after 1m 

使用字段:http, server, location, location中的if字段 

在应答一部分被传递后限制速度:

limit_rate_after 1m;
limit_rate 100k;

lingering_close

语法:lingering_close on|off|always 

默认值:lingering_close on 

使用字段:http, server, location 

在socket上启用SO_LINGER 。

lingering_time

语法:lingering_time time

默认值:lingering_close 30s

使用字段:http, server, location

在socket上启用SO_LINGER 。

lingering_timeout

语法:lingering_timeout time

默认值:lingering_timeout 5s

使用字段:http, server, location

在socket上启用SO_LINGER 。

listen

语法: listen address:port [ default(0.8.21后已过时) | default_server | [ backlog=num | rcvbuf=size | sndbuf=size | accept_filter=filter | deferred | bind | ipv6only=[on|off] | ssl ] ] 

默认值:listen 80 

使用字段:server 

listen指令指定了server{…} 字段中可以被访问到的ip地址及端口号,可以只指定一个ip,一个端口,或者一个可解析的服务器名。

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 [fe80::1];在linux中默认使用IPv4 to IPv6视图地址格式使IPv6的socket同样对应IPv4的链路,例如, ::ffff:,示例, ::ffff:192.168.0.27对应192.168.0.27到一个IPv6地址。

如果你在listen指令中启用[::]:80IPv6地址格式监听80端口,在linux中默认它也会监听IPv4端口,也就意味着IPv4和IPv6的地址都会被监听,如果你在另外一个指令中指定IPv4的地址,你将会在重启nginx时得到一个“already bind address”错误。

在linux中,如果你想讲IPv4和IPv6地址分开监听,可以通过内核参数:net.ipv6.bindv6only,默认这个值是0。通过sysctl将这个值设置为1。

注意:nginx实例(进程)在你修改上述参数之后可能会继续IPv4链路的传输,你可能需要一个新的设置为IPv6和IPv4包处理方法,请修改nginx配置文件并且重启nginx。

如果在其他server块(vhost)中你想通过下面这个指令来监听IPv4的地址:

  • listen [::]:80;监听IPv4的地址将会失败,解决这个问题的方法是在listen中,当使用IPv6地址时增加ipv6only=on选项,并且在同一个server块中写一条监听IPv4地址的指令:

  • 修改配置文件应该是在你修改内核运行参数以后进行。

  • listen [::]:80 ipv6only=on; # 只监听IPv6链路

  • listen 80; # 这条指令将监听IPv4链路在FreeBSD中默认是将IPv4和IPv6分离监听的,这样listen [::]:80仅监听IPv6的链路,如果你想同时进行IPv4地址的监听你可能需要另外写一条指令。

  • 通过使用default ipv6only=on选项可以在listen指令中指定仅监听IPv6地址,这样在这个server块中就可以指定IPv6监听地址,其他server块中同样可以指定IPv4地址:

  • listen [2a02:750:5::123]:80;

  • listen [::]:80 default_server ipv6only=on;如果只有ip地址指定,则默认端口为80。

如果指令有default_server参数,那么这个server块将是通过“地址:端口”来进行访问的默认服务器,这对于你想为那些不匹配server_name指令中的主机名指定默认server块的虚拟主机(基于域名)非常有用,如果没有指令带有default_server参数,那么默认服务器将使用第一个server块。在0.8.21版本以前这个参数名称为default。

listen允许一些不同的参数,即系统调用listen(2)和bind(2)中指定的参数,这些参数必须用在default参数之后:

  • backlog=num – 指定调用listen(2)时backlog的值,默认为-1。 

  • rcvbuf=size – 为正在监听的端口指定SO_RCVBUF。 

  • sndbuf=size – 为正在监听的端口指定SO_SNDBUF。 

  • accept_filter=filter – 指定accept-filter。 

仅用于FreeBSD,可以有两个过滤器,dataready与httcodeady,仅在最终版本的FreeBSD(FreeBSD: 6.0, 5.4-STABLE与4.11-STABLE)上,为他们发送-HUP信号可能会改变accept-filter。 

deferred – 在linux系统上延迟accept(2)调用并使用一个辅助的参数: TCP_DEFER_ACCEPT。 

bind – 将bind(2)分开调用。 

主要指这里的“地址:端口”,实际上如果定义了不同的指令监听同一个端口,但是每个不同的地址和某条指令均监听为这个端口的所有地址(*:port),那么nginx只将bind(2)调用于*:port。这种情况下通过系统调用getsockname()确定哪个地址上有连接到达,但是如果使用了parameters backlog, rcvbuf, sndbuf, accept_filter或deferred这些参数,那么将总是将这个“地址:端口”分开调用。 

ssl – 参数(0.7.14)不将listen(2)和bind(2)系统调用关联。 

被指定这个参数的listen将被允许工作在SSL模式,这将允许服务器同时工作在HTTP和HTTPS两种协议下,例如: 

  • listen  80;

  • listen  443 default_server ssl;一个使用这些参数的完整例子:

  • listen  127.0.0.1 default_server accept_filter=dataready backlog=1024;0.8.21版本以后nginx可以监听unix套接口:

  • listen unix:/tmp/nginx1.sock;

location

语法:location [=|~|~*|^~|@] /uri/ { … } 

默认值:no 

使用字段:server 

这个参数根据URI的不同需求来进行配置,可以使用字符串与正则表达式匹配,如果要使用正则表达式,你必须指定下列前缀:

~* 不区分大小写。 ~ 区分大小写。 

要确定该指令匹配特定的查询,程序将首先对字符串进行匹配,字符串匹配将作为查询的开始,最确切的匹配将被使用。然后,正则表达式的匹配查询开始,匹配查询的第一个正则表达式找到后会停止搜索,如果没有找到正则表达式,将使用字符串的搜索结果。

在一些操作系统,如Mac OS X和Cygwin,字符串将通过不区分大小写的方式完成匹配(0.7.7),但是,比较仅限于单字节的语言环境。

正则表达式可以包含捕获(0.7.40),并用于其它指令中。

可以使用“^~”标记禁止在字符串匹配后检查正则表达式,如果最确切的匹配location有这个标记,那么正则表达式不会被检查。

使用“=”标记可以在URI和location之间定义精确的匹配,在精确匹配完成后并不进行额外的搜索,例如有请求“/”发生,则可以使用“location = /”来加速这个处理。

即使没有“=”和“^~”标记,精确的匹配location在找到后同样会停止查询。

下面是各种查询方式的总结:

  • 前缀“=”表示精确匹配查询,如果找到,立即停止查询。 

  • 指令仍然使用标准字符串,如果匹配使用“^~”前缀,停止查询。 

  • 正则表达式按照他们在配置文件中定义的顺序。 

  • 如果第三条产生一个匹配,这个匹配将被使用,否则将使用第二条的匹配。 

例:

location  = / {
  # 只匹配 / 的查询.
  [ configuration A ]
}
location  / {
  # 匹配任何以 / 开始的查询,但是正则表达式与一些较长的字符串将被首先匹配。
  [ configuration B ]
}
location ^~ /images/ {
  # 匹配任何以 /images/ 开始的查询并且停止搜索,不检查正则表达式。
  [ configuration C ]
}
location ~* \.(gif|jpg|jpeg)$ {
  # 匹配任何以gif, jpg, or jpeg结尾的文件,但是所有 /images/ 目录的请求将在Configuration C中处理。
  [ configuration D ]
}

各请求的处理如下例:

/ → configuration A 

/documents/document.html → configuration B 

/images/1.gif → configuration C 

/documents/1.jpg → configuration D 

注意你可以以任何顺序定义这4个配置并且匹配结果是相同的,但当使用嵌套的location结构时可能会将配置文件变的复杂并且产生一些比较意外的结果。

标记“@”指定一个命名的location,这种location并不会在正常请求中执行,它们仅使用在内部重定向请求中。(查看error_page和try_files)

log_not_found

语法:log_not_found [on|off] 

默认值:log_not_found on 

使用字段:http, server, location 

指令指定是否将一些文件没有找到的错误信息写入error_log指定的文件中。

log_subrequest

语法:log_subrequest [on|off]

默认值:log_subrequest off 

使用字段:http, server, location 

指令指定是否将一些经过rewrite rules和/或SSI requests的子请求日志写入access_log指定的文件中。

msie_padding

语法:msie_padding [on|off] 

默认值:msie_padding on 

使用字段:http, server, location 

指令指定开启或关闭MSIE浏览器和chrome浏览器(0.8.25+)的msie_padding特征,当这个功能开启,nginx将为响应实体分配最小512字节,以便响应大于或等于400的状态代码。

指令预防在MSIE和chrome浏览器中激活“友好的”HTTP错误页面,以便不在服务器端隐藏更多的错误信息。

msie_refresh

语法: msie_refresh [on|off] 

默认值:msie_refresh off 

使用字段:http, server, location 

指令允许或拒绝为MSIE发布一个refresh而不是做一次redirect

open_file_cache

语法:open_file_cache max = N [inactive = time] | off 

默认值: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 

这个指令指定是否在搜索一个文件是记录cache错误。

open_file_cache_min_uses

语法:open_file_cache_min_uses number 

默认值:open_file_cache_min_uses 1 

使用字段:http, server, location 

这个指令指定了在open_file_cache指令无效的参数中一定的时间范围内可以使用的最小文件数,如果使用更大的值,文件描述符在cache中总是打开状态。

open_file_cache_valid

语法:open_file_cache_valid time 

默认值:open_file_cache_valid 60 

使用字段:http, server, location 

这个指令指定了何时需要检查open_file_cache中缓存项目的有效信息。

optimize_server_names

语法:optimize_server_names [ on|off ] 

默认值:optimize_server_names on 

使用字段:http, server 

这个指令指定是否在基于域名的虚拟主机中开启最优化的主机名检查。

尤其是检查影响到使用主机名的重定向,如果开启最优化,那么所有基于域名的虚拟主机监听的一个“地址:端口对”具有相同的配置,这样在请求执行的时候并不进行再次检查,重定向会使用第一个server name。

如果重定向必须使用主机名并且在客户端检查通过,那么这个参数必须设置为off。

注意:这个参数不建议在nginx 0.7.x版本中使用,请使用server_name_in_redirect。

port_in_redirect

语法:port_in_redirect [ on|off ] 

默认值:port_in_redirect on 

使用字段:http, server, location 

这个指令指定是否在让nginx在重定向操作中对端口进行操作。

如果这个指令设置为off,在重定向的请求中nginx不会在url中添加端口。

post_action

语法:post_action [ uri|off ] 

默认值:post_action off 

使用字段:http, server, location, location中的if字段 

为当前完成请求的子请求定义一个URI。

location /protected_files { 
 internal;
 
 proxy_pass http://127.0.0.2;
 post_action /protected_done;
}
# 发送post_action 请求到FastCGI后端进行登录验证。
location /protected_done {
 internal;
 fastcgi_pass 127.0.0.1:9000;
}

recursive_error_pages

语法:recursive_error_pages [on|off] 

默认值:recursive_error_pages off 

使用字段:http, server, location 

recursive_error_pages指定启用除第一条error_page指令以外其他的error_page。

request_pool_size

语法:request_pool_size the_size 

默认值:request_pool_size the_size 256 

使用字段:http (或许可以用到其他地方?) 

为每个请求分配的内存池,内存池用于小配额内存块,如果一个块大于内存池或者大于分页大小,那么它将被分配到内存池之外,如果位于内存池中较小的分配量没有足够的内存,那么将分配一个相同内存池大小的新块,这个指令仅有相当有限的效果(来源http://markmail.org/message/b2kmrluscevimpba)

reset_timedout_connection

语法:reset_timedout_connection [on|off] 

默认值:reset_timedout_connection off 

使用字段:http, server, location 

是否启用重置timeout的连接,在socket关闭并且重置连接时,socket的SO_LINGER选项设置为0timeout,这将强迫RST包发送到客户端后关闭连接,从而释放与之关联的内存,这是socket处于FIN_WAIT1状态。

注意如果socket使用keepalive连接,在经过定义的timeout时间后,将使用正常的方式关闭连接。

resolver

语法:resolver address 

默认值:no 

使用字段:http, server, location 

指定DNS服务器地址,如:resolver 127.0.0.1;

resolver_timeout

语法:resolver_timeout time 

默认值:30s 

使用字段:http, server, location 

解析超时时间。如:resolver_timeout 5s;

语法:root path 

默认值:root html 

使用字段:http, server, location ,location中的if字段

请求到达后的文件根目录。

下例中:

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

如果请求”/i/top.gif”文件,nginx将转到”/spool/w3/i/top.gif”文件。你可以在参数中使用变量。

注意:在请求中root会添加这个location到它的值后面,即”/i/top.gif”并不会请求”/spool/w3/top.gif”文件,如果要实现上述类似于apache alias的功能,可以使用alias指令。

satisfy

语法: satisfy [ all | any ]

默认值: satisfy all

使用字段:http, server, location

可用版本: ≥ 0.6.25

如果在一个字段中同时使用了Access模块和Auth Basic模块的指令,可以使用这个指令确定一种验证方式:

  • all - 必须同时匹配Access和Auth Basic中指令指定的权限。 

  • any - 具有Access 或 Auth Basic指令任一权限即可通过匹配 

location / {
  satisfy any;
  allow 192.168.1.0/32;
  deny all;
  auth_basic "closed site";
  auth_basic_user_file conf/htpasswd;
}

satisfy_any

语法:satisfy_any [ on|off ] 

默认值:satisfy_any off 

使用字段:location 

0.6.25版本以后请使用satisfy

send_timeout

语法:send_timeout the time 

默认值:send_timeout 60 

使用字段:http, server, location 

指令指定了发送给客户端应答后的超时时间,Timeout是指没有进入完整established状态,只完成了两次握手,如果超过这个时间客户端没有任何响应,nginx将关闭连接。

sendfile

语法:sendfile [ on|off ] 

默认值:sendfile off 

使用字段:http, server, location 

是否启用sendfile()函数。

sendfile()函数在一个文件描述符与另一个之间拷贝数据,由于这个拷贝过程是在内核状态下完成,sendfile()函数比read(2)和write(2)函数更加高效,后者需要从用户空间中传送文件。

更多sendfile信息:https://www.kernel.org/doc/man-pages/online/pages/man2/sendfile.2.html

使用sendfile优化性能:http://www.techrepublic.com/article/use-sendfile-to-optimize-data-transfer/1044112

server

语法:server {…} 

默认值:no 

使用字段:http 

server字段包含虚拟主机的配置。

没有明确的机制来分开基于域名(请求中的主机头)和基于IP的虚拟主机。

可以通过listen指令来指定必须连接到这个server块的所有地址和端口,并且在server_name指令中可以指定所有的域名。

server_name

语法:server_name name [… ] 

默认值:server_name hostname 

使用字段:server 

这个指令有两个作用:

一、将HTTP请求的主机头与在nginx配置文件中的server{…}字段中指定的参数进行匹配,并且找出第一个匹配结果。这就是如何定义虚拟主机的方法,域名遵循下述优先级规则:

完整匹配的名称。 

名称开始于一个文件通配符:*.example.com。 

名称结束于一个文件通配符:www.example.*。 

使用正则表达式的名称。 

如果没有匹配的结果,nginx配置文件将安装以下优先级使用[#server server { … }]字段:

listen指令被标记为default的server字段。 

第一个出现listen(或者默认的listen 80)的server字段。 

二、如果server_name_in_redirect被设置,这个指令将用于设置HTTP重定向的服务器名。

例:

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

第一个名称为服务器的基本名称,默认名称为机器的hostname。

当然,可以使用文件通配符:

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

上述例子中的前两个名称可以合并为一个:

server {
  server_name  .example.com;
}

同样可以使用正则表达式。名称前面加“~”:

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

0.7.12版本以后已经可以支持空服务器名,以处理那些没有主机头的请求,但是请注意,大多数的浏览器会为请求增加一个“Host”头,如果其连接包含IP,请通过listen指令给他指定一个默认监听的server块。

server {
  server_name "";
}

0.8.25版本以后可以在server_name中使用命名的捕获:

server {
  server_name   ~^(www\.)?(?.+)$;
  root  /sites/$domain;
}

一些老的PCRE版本在使用此语法的时候可能会引起部分问题,可以尝试以下语法修复:

server {
  server_name   ~^(www\.)?(?P.+)$;
  root  /sites/$domain;
}

0.9.4版本(含)以后,$hostname变量可以作为server_name的参数:

server {
  server_name $hostname;
}

server_name_in_redirect

语法:server_name_in_redirect on|off 

默认值:server_name_in_redirect on 

使用字段:http, server, location 

如果这个指令打开,nginx将使用server_name指定的基本服务器名作为重定向地址,如果关闭,nginx将使用请求中的主机头。

注意:如果一个header中的Location字段来自一个上游代理服务器(例如通过proxy_pass),可能不并不仅仅需要这个指令,事实上,它会被忽略,如果你看到返回的上游服务器的服务器名没有经过重写,你需要使用proxy_redirect来重写上游服务器提供的服务器名称,例如:proxy_redirecthttp://some.upstream.url/ /,它将http://some.upstream.url/重写为”/“,这是一个相对路径

server_names_hash_max_size

语法:server_names_hash_max_size number 

默认值:server_names_hash_max_size 512 

使用字段:http 服务器名称哈希表的最大值,更多信息请参考nginx部分优化。

server_names_hash_bucket_size

语法:server_names_hash_bucket_size number 

默认值:server_names_hash_bucket_size 32/64/128 

使用字段:http服务器名称哈希表每个页框的大小,这个指令的默认值依赖于cpu缓存。更多信息请参考nginx部分优化。

server_tokens

语法:server_tokens on|off 

默认值:server_tokens on 

使用字段:http, server, location 

是否在错误页面和服务器头中输出nginx版本信息。

tcp_nodelay

语法:tcp_nodelay [on|off] 

默认值:tcp_nodelay on 

使用字段:http, server, location 

这个指令指定是否使用socket的TCP_NODELAY选项,这个选项只对keep-alive连接有效。

tcp_nopush

语法:tcp_nopush [on|off] 

默认值:tcp_nopush off 

使用字段:http, server, location 

这个指令指定是否使用socket的TCP_NOPUSH(FreeBSD)或TCP_CORK(linux)选项,这个选项只在使用sendfile时有效。

设置这个选项的将导致nginx试图将它的HTTP应答头封装到一个包中。

try_files

语法:try_files path1 [path2] uri 

默认值:none 

使用字段:server, location 

可用版本:0.7.27 

按照指定的顺序检查存在的文件,并且返回第一个找到的结果,尾部跟随一个目录名,如果所有的文件都没有找到,那么将启用最后一个参数命名的内部重定向,最后一个参数所指定的命名location必须被设置,否则将产生一个内部错误。不像rewrite,如果$args变量并不会自动保留,如果你需要保留请求参数,请参照如下配置:

try_files $uri $uri/ /index.php?q=$uri&$args;例(在代理Mongrel时使用):

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

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

注意,0.7.51版本后你可以指定一个HTTP状态代码在try_file的最后一个参数中,例如:

location / {
  try_files $uri $uri/ /error.php?c=404 =404;
}

当参数中的请求(除最后一个外)都没有正常响应,那么将返回404。

在Drupal / FastCGI中使用

# for drupal 6:
try_files $uri $uri/ @drupal;
 
# for drupal 7:
try_files $uri $uri/ /index.php?q=$request_uri;
 
# only needed for Drupal 6 (或者你需要一个命名的location)
location @drupal {
  rewrite ^ /index.php?q=$uri last; # for drupal 6
}
location ~ \.php$ {
  fastcgi_pass 127.0.0.1:8888;
  fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name; # if not already defined in the fastcgi_params file
  # any other specific fastcgi_params
}

下面这个例子中,指令try_files:

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

相当于这个指令:

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

或者这个:

if (-e $request_filename) {
   rewrite ^ /index.php?q=$uri last;
}

try_files基本上是一个对检查是否存在mod_rewrite样式的文件(类似于/directory)的替换,它比if的效率更高,参考IfIsEvil。

在Wordcodess和Joomla中使用:

# wordcodess (不使用WP Super Cache) - 示例 1
try_files $uri $uri/ /index.php?q=$uri&$args;
 
# wordcodess (不使用WP Super Cache) - 示例 2 (实际上并不需要"q"参数)
try_files $uri $uri/ /index.php;
 
# joomla
try_files $uri $uri/ /index.php?q=$uri&$args;
 
location ~ \.php$ {
  fastcgi_pass 127.0.0.1:8888;
  fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name; # 如果在fastcgi_params文件中没有定义
  # 其他一些指定的fastcgi_params.
}

WP Super Cache需要成堆的静态文件检查,这里不对其进行讨论。

types

语法:types {…} 

使用字段:http, server, location 

这个字段指定一些扩展的文件对应方式与应答的MIME类型,一个MIME类型可以有一些与其类似的扩展。默认使用以下文件对应方式:

types {
  text/html    html;
  image/gif    gif;
  image/jpeg   jpg;
}

完整的对应视图文件为conf/mime.types,并且将被包含。

如果你想让某些特定的location的处理方式使用MIME类型:application/octet-stream,可以使用以下配置:

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

underscores_in_headers

语法:underscores_in_headers on|off 

默认值:off

使用字段:http, server 

是否允许在header的字段中带下划线。

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 512

使用字段:http 

变量:无

哈希表的最大值,查看更多信息请参考nginx部分优化选项中的哈希表。

变量 core module 支持一些内置的变量,与apache使用的变量相一致。

首先,一些变量代表了客户端请求头部的一些字段,如:$http_user_agent, $http_cookie等等。注意,由于这些变量会在请求中定义,所以可能无法保证他们是存在的或者说可以定义到一些别的地方(例如遵循一定的规范)。

除此之外,下列是一些其他变量:

$arg_PARAMETER:这个变量包含在查询字符串时GET请求PARAMETER的值。

$args:这个变量等于请求行中的参数。

$binary_remote_addr:二进制码形式的客户端地址。

$body_bytes_sent:应答实体大小,即使连接失败或中断,它也非常精确。

$content_length:请求头中的Content-length字段。

$content_type:请求头中的Content-Type字段。

$cookie_COOKIE:cookie COOKIE的值。

$document_root:当前请求在root指令中指定的值。

$document_uri:与$uri相同。

$host

请求中的Host字段,如果请求中的Host字段不可用,则为服务器处理请求的服务器名称。

在下列情况下,$host变量的值可能和$http_host的值不相同:

当请求头中的Host字段未指定或者为空值,$host等于server_name指令指定的值。 

当Host字段包含端口号时,$host并不包含端口号,$host的值在0.8.17后总是小写。

$hostname:gethostname返回的机器名称。

$is_args:如果$args设置,值为”?”,否则为”“。

$limit_rate:这个变量可以限制连接速率。

$nginx_version:当前运行的nginx版本号。

$query_string:与$args相同。

$remote_addr:客户端的IP地址。

$remote_port:客户端的端口。

$remote_user:已经经过Auth Basic Module验证的用户名。

$request_filename:当前连接请求的文件路径,由root或alias指令与URI请求生成。

$request_body:这个变量(0.7.58+)包含请求的主要信息。在使用proxy_pass或fastcgi_pass指令的location中比较有意义。

$request_body_file:客户端请求主体信息的临时文件名。

$request_completion:如果请求成功,值为”OK”,如果请求未完成或者请求不是一个范围请求的最后一部分,则为空。

$request_method:这个变量是客户端请求的动作,通常为GET或POST。

包括0.8.20及之前的版本中,这个变量总为main request中的动作,如果当前请求是一个子请求,并不使用这个当前请求的动作。

$request_uri:这个变量等于包含一些客户端请求参数的原始URI,它无法修改,请查看$uri更改或重写URI,不包含主机名,例如:”/foo/bar.php?arg=baz”。

$scheme

HTTP方法(如http,https)。按需使用,例:

rewrite  ^  $scheme://example.com$uri  redirect;$server_addr

服务器地址,在完成一次系统调用后可以确定这个值,如果要绕开系统调用,则必须在listen中指定地址并且使用bind参数。

$server_name:服务器名称。

$server_port:请求到达服务器的端口号。

$server_protocol:请求使用的协议,通常是HTTP/1.0或HTTP/1.1。

$uri:请求中的当前URI(不带请求参数,参数位于$args),可以不同于浏览器传递的$request_uri的值,它可以通过内部重定向,或者使用index指令进行修改,$uri不包含主机名,如”/foo/bar.html”。

未经允许请勿转载:程序喵 » Nginx模块参考手册:HTTP核心模块

点  赞 (1) 打  赏
分享到: