概要
控制Nginx HTTP 进程的核心属性.
指令
alias
语法: alias file-path|directory-path;
默认值: no
作用域: location
该指令设置指定location使用的路径.注意它跟 root 相似,但是不改变文件的根路径,仅仅是使用文件系统路径
比如:
- location /i/ {
- alias /spool/w3/images/;}
请求 "/i/top.gif" 将返回文件 "/spool/w3/images/top.gif".
在替换路径中可以使用变量.
alias 无法在正则的 location中使用. 如果你需要这么做,你必须结合使用指令rewrite 和 root.
client_body_in_file_only
语法: client_body_in_file_only on|off
默认值: off
作用域: http, server, location
The directive enables to store a client request body in a file.
Please note that the file at the request completion will not be removed if the directive is enabled.
指令允许在文件中存储客户端请求主体。 请注意,如果指令已启用,请求完成时的文件将不会被删除。 该指令可用于调试,以及在嵌入式Perl模块为$r->request_body_file方法所用。
client_body_buffer_size
语法: client_body_buffer_size the_size
默认值: 8k/16k
作用域: http, server, location
指令指定客户端请求体缓冲区大小。
如果请求主体大于缓冲区,那么整个请求主体或某个部分将写入临时文件中。
默认的大小等于两页的大小,取决于平台是8k或16k。
client_body_temp_path
语法: client_body_temp_path dir-path [ level1 [ level2 [ level3 ]
默认值: client_body_temp
作用域: http, server, location
指令将目录中的临时文件存储在请求正文中。在dir-path
一个层次的子目录可多达三层。
例如:
- 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返回错误“请求超时”(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
指令分配超时,读取客户请求的标题。只有头部在一个readstep里读取失败才会有超时设置。如果这个时候客户没有发送任何信息,nginx返回错误“请求超时”(408)。
client_max_body_size
语法: client_max_body_size size
默认值: client_max_body_size 1m
作用域: http, server, location
指令以请求标头中的行内容长度指示客户端请求的最大接受体大小。
如果给定的大小较大,则客户端获取错误“请求实体太大”(413)。
必须记住,浏览器不知道如何正确地显示这个错误。
default_type
语法: default_type MIME-type
默认值: default_type text/plain
作用域: http, server, location
Assigns the default MIME-type to be used for files where the standard MIME map doesn't specify anything. 在标准MIME地图没有指定任何东西的文件,指定默认的标准MIME类型。
参照这里: types
例子:
- location = /proxy.pac {
- default_type application/x-ns-proxy-autoconfig;}location = /wpad.dat {
- rewrite . /proxy.pac;
- default_type application/x-ns-proxy-autoconfig;}
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
默认值: no
作用域: http, server, location, if in location
指令指定URI,将显示所指出的错误。
例如:
- error_page 404 /404.html;error_page 502 503 504 /50x.html;error_page 403 http://example.com/forbidden.html;
此外,可以将应答代码更改为另一个, 例如:
- error_page 404 =200 /.empty.gif;
如果一个错误的答案是被代理服务器或FastCGI服务器处理的,将会返回不同的答案代码,例如,200, 302, 401或404,那么就可能隐藏返回的代码:
- error_page 404 = /404.php;
如果你想返回的错误代码如下,则OMIT=从error_page来的指令:
- error_page 404 /404.php;
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"更早。
index
语法: index file [file...]
默认值: index index.html
作用域: http, server, location
指令确定将用作索引的单个或多个文件。在文件名中使用变量是可能的。文件的存在按枚举的顺序进行检查。一个具有绝对路径的文件可以放在结尾。使用变量的示例:
- index index.$geo.html index.0.html /index.html;
如果要从目录列表中自动生成索引,请使用autoindex on。
internal
语法: internal
默认值: no
作用域: location
internal
表明匹配的位置只能用于所谓的“内部”请求。
对于外部请求,它将返回“未找到”的错误(404)。
Internal 请求如下:
-
被
error_page
重定向后的请求 -
"ngx_http_ssi_module"模块的
include virtual
指令创建的子请求 -
"ngx_http_rewrite_module" 模块的 rewrite 结构修改的请求
防止客户端直接获取错误页面的示例:
- error_page 404 /404.html;location /404.html {
- internal;}
nginx的0.7.x介绍内部位置的一种新的语法: @location
例子:
- location / {
- root /var/www/html;
- error_page 404 @40x;} location @40x {
- root /var/www/errors/40x.html;}
keepalive_timeout
语法: keepalive_timeout time [ time ]
默认值: keepalive_timeout 75
作用域: http, server, location
指令分配超时,以便与客户保持联系。
第二个参数在响应头中指定行 Keep-Alive: timeout=time 中的值。
这些参数可能彼此不同。 Keep-Alive: timeout=time 行只能读懂 Mozilla 和 Konqueror. MSIE 60秒后关闭自身的活动链接。
large_client_header_buffers
语法: large_client_header_buffers number size
默认值: large_client_header_buffers 4 4k/8k
作用域: http, server
指令规定,将要读的从客户端来的大头部的最大数量和最大缓冲尺寸。
请求行不能超过一个缓冲区的大小,如果客户端的头部过长nginx将会返回错误“请求URI太大”(414)。 请求的最长标头行也必须不大于一个缓冲区的大小,否则客户端会收到错误“错误请求”(400)。 缓冲区仅根据需要分开。 默认情况下,一个缓冲区的大小等于页的大小,取决于平台这是4K或8K,如果在工作要求的连接端将状态保持,那么这些缓冲区被释放。
limit_except
语法: limit_except methods {...}
默认值: no
作用域: 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, if in location
指令声明分配给客户端的速度。速度以每秒字节表示。限制只适用于一个连接,也就是说,如果客户端打开2个连接,那么总速度将是限制集的2倍。
如果有必要在某种程度上限制服务器部分客户端的速度,则此指令不适用。相反,你应该到$limit_rate variable
变量分配值指定的限制,如下所示:
- server {
- if ($slow) {
- set $limit_rate 4k;
- }}
listen
语法: listen address:port [ default [ backlog=num | rcvbuf=size | sndbuf=size | accept_filter=filter | deferred | bind | ssl ]
默认值: listen 80
作用域: server
侦听指令指定由封闭 server {...} 块所接受的地址和端口。可以只指定地址、端口或服务器名称作为地址。
- listen 127.0.0.1:8000;listen 127.0.0.1;listen 8000;listen *:8000;listen localhost:8000;
如果只有地址被给出, 则指定的端口是80。
如果指令具有默认参数,那么封闭的 server {...} 块将是地址的默认服务器:端口对。这对于基于名字的虚拟主机非常有用:你想指定默认的服务器块,用于不匹配任何[#server_name server_name]指令的服务器名。如果没有默认参数的指令,则默认服务器将是第一个出现“地址:端口”的服务器块。
侦听指令接受特定于系统调用listen(2)
和bind(2)
的几个参数。这些参数必须遵循默认的
参数。
backlog=num -- 用来声明listen(2)里积压的参数。默认的积压数是-1。
rcvbuf=size -- 为socket监听声明SO_RCVBUF
参数。
sndbuf=size -- 为socket监听声明SO_SNDBUF
参数。
accept_filter=filter -- 声明accept-filter的名字。
-
它只能用于FreeBSD,它可以用两个过滤器:
dataready
和httpready
。在只接受信号HUP滤镜上,可能只能在FreeBSD: 6.0, 5.4-STABLE 和 4.11-STABLE版本里修改。
延迟——表示在Linux上使用延迟接受(2):
-
在TCP_DEFER_ACCEPT的帮助下
绑定 -- 表示有必要分别作出bind(2)
。
-
对于“地址:端口”对:事实是,如果描述了几个指令,则监听相同的端口, 但是,通过不同的地址和其中一个指令,侦听器监听这个端口的所有地址(*:port),这时Nginx会只为*:port制造 bind(2)。在这种情况下,必须考虑确定地址:该连接到达,完成系统调用getsockname()。但是如果是用过的参数积压,rcvbuf, sndbuf, accept_filter 或 deferred,这时总是为这个“地址:端口bind(2)”分开完成。
ssl -- 参数(0.7.14) 与listen(2)和bind(2)系统响应无关
-
而相反,如果指定在这个端口接受的连接可以在SSL模式下工作。这允许为HTTP和HTTPS工作的服务器指定紧凑的配置。例如:
- listen 80;listen 443 default ssl;
参数使用示例:
- listen 127.0.0.1 default accept_filter=dataready backlog=1024;
location
语法: location [=|~|~*|^~] /uri/ { ... }
默认值: no
作用域: server
这个指令允许根据URI进行不同的配置。它可以使用文字字符串和正则表达式进行配置。要使用正则表达式,必须使用前缀:
-
~* 用于对大小写不敏感的匹配
-
~ 用于对大小写敏感的匹配
要确定哪个位置指令与特定查询匹配,首先检查文本字符串。字符串匹配请求的开始部分,区分大小写,最准确的匹配将会被使用(见下文明白nginx怎么确定最准确的匹配)。然后,按照配置文件中定义的顺序检查正则表达式。匹配查询的第一个正则表达式将停止搜索。如果找不到正则表达式匹配,则使用文字字符串搜索的结果。
有两种方法可以修改这种行为。第一种方法是使用前缀“=”,它只精确查询匹配。如果查询匹配,则搜索停止,并立即处理请求。例如,如果请求“/”经常发生,则使用 "location = /"将加快处理此请求。
第二个是使用前缀^~。这个前缀用于字符串,告诉nginx不测试正则表达式如果提供的路径匹配。例如,如果查询以“/images/”开头,“location ^~ /images/”将停止搜索,所有正则表达式指令都不会被检查。
总之,检查指令的顺序如下:
-
具有与查询完全匹配的=前缀的指令。如果找到,搜索停止。
-
使用常规字符串的所有剩余指令。如果这个匹配使用的是“^~”前缀,搜索停止。
-
正则表达式,按照它们在配置文件中定义的顺序。
-
如果第 3 步找到了一个匹配, 这个结果将被使用。否则, 将使用第2步的匹配。
要知道nginx对解码URI比较重要。例如, 如果你希望匹配 "/images/%20/test", 这时你必须使用 "/images/ /test" 去决定路径。
例如:
- location = / {
- # matches the query / only.
- [ configuration A ] }location / {
- # matches any query, since all queries begin with /, but regular
- # expressions and any longer conventional blocks will be
- # matched first.
- [ configuration B ] }location ^~ /images/ {
- # matches any query beginning with /images/ and halts searching,
- # so regular expressions will not be checked.
- [ configuration C ] }location ~* \.(gif|jpg|jpeg)$ {
- # matches any request ending in gif, jpg, or jpeg. However, all
- # requests to the /images/ directory will be handled by
- # Configuration C.
- [ configuration D ] }
这个例子的结果是:
-
/ -> configuration A
-
/documents/document.html -> configuration B
-
/images/1.gif -> configuration C
-
/documents/1.jpg -> configuration D
注意,您可以按照任何顺序定义这4个配置,结果将保持不变。虽然配置文件解析器允许嵌套位置,但它们的使用被阻止,并可能产生意外的结果。
nginx 如何决定哪个路径匹配
大多数用户不需要知道Nginx内部如何决定使用哪个路径-知道它如何快速有效的确定“最准确的”匹配路径。然而,对于那些好奇的人,继续读下去。
所有路径字符串按字母顺序排序。Nginx然后向下搜索列表,直到URI中有“更高”的价值的值。这是被strcmp()家族的函数决定的-strcmp()如果返回1,搜索停止。搜索停止后,匹配的最后一个字符串被使用。
例如, 我们有如下地址:
- /
- /a
- /apple
- /banana
这时,如果系统接收到路径 "/az", nginx 会开始搜索列表。首先,"/" 会匹配, 但是 "/ 少于 "/az" 所以搜索继续。"/a" 也匹配,但是 "/a" 仍然少于 "/az",所以搜索仍然继续。 "/apple" 不匹配。下一个字符串, "/banana", 多于 "/az" 所以搜索停止, "/a", 将会被使用。
log_not_found
语法: log_not_found [on|off]
默认值: log_not_found on
作用域: http, server, location
该指令启用或禁止关于文件没有在硬盘上找到时, error_log里面的信息 。
msie_padding
语法: msie_padding [on|off]
默认值: msie_padding on
作用域: http, server, location
这个指令为MSIE浏览器启用或禁用的msie_padding特征。当启用时,nginx会消耗多达512个字节的大小的响应头,这些响应头的状态码都多于400。这可以防止激活相关浏览器的“友好HTTP错误页面”功能,以避免隐藏可能更为详细的错误详细。
msie_refresh
语法: msie_refresh [on|off]
默认值: msie_refresh off
作用域: http, server, location
该指令允许或禁止分配刷新而不是为MSIE做重定向。
optimize_server_names
语法: optimize_server_names [ on|off ]
默认值: optimize_server_names on
作用域: http, server
指令激活或停用基于名称的虚拟服务器的主机名检查优化。
特别情况下,检查将影响用于重定向主机名。如果启用优化,所有基于名称的服务器监听一个“地址:端口对”是否具有相同的配置,然后在 请求执行以及重定向使用第一个服务器名的时候不检查名字。
如果重定向必须使用客户端传递的主机名,则必须关闭优化。
提示: 这个指令在 nginx 0.7.x中已经过时, 请使用 server_name_in_redirect 替代。
port_in_redirect
语法: port_in_redirect [ on|off ]
默认值: port_in_redirect on
作用域: http, server, location
指令允许或阻止被nginx挂起的重定向中的端口标识。
如果 port_in_redirect 被开启, 这时 Nginx 在请求被重定向后不会将端口加到地址后面。
recursive_error_pages
语法: recursive_error_pages [on|off]
默认值: recursive_error_pages off
作用域: http, server, location
recursive_error_pages启用或禁用接下来的一系列error_page指令。
root
语法: root path
默认值: root html
作用域: http, server, location, if in location
root
指定请求的文档根目录。例如,以下配置:
- location /i/ {
- root /spool/w3;}
请求 "/i/top.gif" 会返回这个文件: "/spool/w3/i/top.gif"。你可以在参数中使用变量。
提示: 记住, root仍然会在请求上追加目录,这样请求 "/i/top.gif" 就会在 "/spool/w3/top.gif"中寻找,而这种情况可能会发生在类Apache服务器别名配置上,在这些配置中,位置匹配本身被删除。使用别名指令来实现类似Apache的功能。
satisfy_any
语法: satisfy_any [ on|off ]
默认值: satisfy_any off
作用域: location
指令执行至少一个成功的检查来响应访问(通过执行 NginxHttpAccessModule 或者 NginxHttpAuthBasicModule):
- location / {
- satisfy_any on;
- allow 192.168.1.0/32;
- deny all;
- auth_basic "closed site";
- auth_basic_user_file conf/htpasswd;}
send_timeout
语法: send_timeout the time
默认值: send_timeout 60
作用域: http, server, location
指令为客户端分配超时。超时不是在整个响应传送途中被建立,而只在2个读操作之间建立,如果过了这个时间段客户端还是毛操作没有,那么nginx将关闭连接。
sendfile
语法: sendfile [ on|off ]
默认值: sendfile off
作用域: http, server, location
指令激活或停用sendfile()
。
server
语法: server {...}
默认值: no
作用域: http
指令为虚拟服务器分配配置。
这里没有区分IP 和 基于名称的服务器 (请求的主机头) 。
listen
指令被用来描述所有可能发生的地址和端口,server_name
显示所有服务器的名称。
server_name
语法: server_name name [... ]
默认值: server_name hostname
作用域: server
这个指令执行两个操作:
-
比较接收的HTTP请求 Host 头 和 Nginx 配置文件中的 server { ... } 块,并选择第一个匹配项。虚拟服务器就是这样定义的。服务器名按如下顺序处理:
-
完全的, 静态名字
-
以通配符开头的名字 — *.example.com
-
以通配符结束的名字 — www.example.*
-
带有正则表达式的名字
-
如果没有找到匹配项, 配置文件里的[#server server { ... }] 块将会按如下顺序使用:
-
被一个匹配的
listen
指令标记为默认的服务器块 -
匹配监听指令的第一服务器块(或隐式监听80;)
-
设置服务器名,服务器名将会在HTTP转向里被使用(如果 server_name_in_redirect 被设置了的话)。
例子:
- server {
- server_name example.com www.example.com;}
第一个名字变成服务器的基本名。默认情况下,机器名 (hostname)会成为基本名。
上面的两个名字可以组合成一个:
- server {
- server_name .example.com;}
使用 "*" 去替换第一部分或最后一部分名称是可能的:
- server {
- server_name example.com *.example.com www.example.*;}
在服务器名字里使用正则表达式也是可能的,名称前面加上符号 "~" ,像这样:
- server {
- server_name www.example.com ~^www\d+\.example\.com$;}
如果客户端请求里没有 Host 头,或者这个头没有匹配任何server_name,服务器基本名将被用在HTTP重定向上。你也可以只使用 "*" 强制Nginx在HTTP重定向里使用 Host 头 。注意 "*" 不能被用作第一个名字, 但是你可以使用一个虚拟的名字(例如 "_" )替代:
- server {
- server_name example.com *;}server {
- server_name _ *;}
注意这在 0.6.x 和更高版本里已经被替换成这样:
- server {
- server_name _;}
从nginx 0.7.12版本开始, 支持空的服务器名, 用于捕捉没有“Host”头的请求:
- server {
- server_name "";}
server_name_in_redirect
语法: server_name_in_redirect on|off
默认值: server_name_in_redirect on
作用域: http, server, location
如果 server_name_in_redirect
是开的状态, Nginx 会为重定向使用 server_name 的第一个指令值。如果 server_name_in_redirect 是关的状态,nginx会使用已经响应的 Host 头.
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
指令在服务器名称的哈希表中分配篮子的大小。默认情况下,此值取决于处理器缓存行的大小。具体详见 哈希表调整描述: 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 的使用。只在活跃的连接中存在。
关于 TCP_NODELAY socket 选项的详细信息, 请点击这里。
tcp_nopush
语法: tcp_nopush [on|off]
默认值: tcp_nopush off
作用域: http, server, location
这个指令允许或禁止FreeBSD 或 Linux的TCP_CORK 上socket 选项 TCP_NOPUSH 的使用。这个选项只在使用 sendfile 的时候可用.
-
设置此选项将会导致Linux 和 FreeBSD 4.x 上的nginx 试图在一个信息包里发送它的HTTP 响应头。
try_files
语法: try_files file1 [file2 ... filen] fallback
默认值: none
作用域: location
这个指令告诉nginx来测试每个文件的存在, 并把第一个找到的文件作为URI. 如果没有找到任何文件, 调用回退地址 ("回退" 可用有任意的名字)。 回退 是必需的参数。这可用是一个已经命名的地址,或任何可靠的URI。
例如:
- location / {
- try_files index.html index.htm @fallback;} location @fallback {
- root /var/www/error;
- index index.html;}
types
语法: types {...}
作用域: http, server, location
指令指定扩展和MIME类型的对应关系。一个MIME类型可以对应几个扩展。默认情况下,它使用这些对应关系:
- types {
- text/html html;
- image/gif gif;
- image/jpeg jpg;}
conf/mime.types文件中包含了完整的映射表。
So that for that determined location's for all answers would reveal MIME- type application/octet-stream, it is possible to use the following 因此,确定位置的所有应答将揭示MIME类型 application/octet-stream,可以这样使用:
- location /download/ {
- types { }
- default_type application/octet-stream;}
本节翻译:沸活量,转载请保留。
变量
核心模块支持內建变量, 其名称与Apache中变量的名称对应。
首先, 这里有变量代表客户端请求的标题行。例如, $http_user_agent, $http_cookie, 等等。
此外,还有其他变量:
$arg_PARAMETER
这个变量包含查询字符串中的get请求变量参数的值。
$args
这个变量等于请求行中的参数。
$binary_remote_addr
二进制形式的客户端地址。
$body_bytes_sent
(无资料)
$content_length
此变量在请求标头中等于行文本长度。
$content_type
此变量在请求标头中等于行内容类型。
$cookie_COOKIE
名字为COOKIE的cookie的值;
$document_root
这个变量等于当前请求的重定向 root 的值。
$document_uri
等同于 $uri。
$host
如果主机头不可用,这个变量在请求头或请求处理请求的服务器名称中等于行主机。
$http_HEADER
HTTP header 里边 特定HEADER的值,变量会转成小写,比如 $http_user_agent, $http_referer... header信息 "YOUR-STRANGE-HEADER: values" 能通过 $http_your_strange_header获得。
$is_args
如果设置了 $args值为"?" 否则为""。
$limit_rate
这个变量允许限制连接速率。
$query_string
等同于 $args。
$remote_addr
客户端的地址。
$remote_port
客户端的端口。
$remote_user
这个变量等于用户的名字, 经 Auth Basic Module生效;
$request_filename
这个变量等于当前请求的文件路径,由命令根或别名和URI请求组成。
$request_body_file
客户端请求主体临时文件名。
$request_completion
(无资料)
$request_method
这个变量等于请求的方法,通常是GET或POST。
$request_uri
这个变量等同于:与参数相连的完整初始URI。
$scheme
HTTP方案(即HTTP、HTTPS)。仅根据需求进行评估,例如:
- rewrite ^(.+)$ $scheme://example.com$1 redirect;
$server_addr
等于服务器地址。通常,获取这个变量的值是通过一个系统调用完成的。为了避免系统调用,必须在指令listen中显示地址,并使用参数绑定。
$server_name
服务器名称。
$server_port
这个变量等于请求到达的服务器端口。
$server_protocol
这个变量等于请求的协议,通常是 HTTP/1.0 or HTTP/1.1。
$uri
这个变量在请求等于当前的URI,它不同于初始URI,例如内部重定向,或是使用index内部重定向文件。
本章节翻译者:沸活量,转载请保留。
转载本站内容时,请务必注明来自W3xue,违者必究。