nginx中文文档-ngx_stream_split_clients_module

此页面版本:2016-08-23,57bc4b4b-98b
ngx_stream_split_clients_module模块(1.11.3+)创建用于A/B测试(也叫作分离测试)的变量。

示例配置

stream {
    ...
    split_clients "${remote_addr}AAA" $upstream {
                  0.5%                feature_test1;
                  2.0%                feature_test2;
                  *                   production;
    }

    server {
        ...
        proxy_pass $upstream;
    }
}

split_clients

语法:split_clients string $variable { … }
默认:—
上下文:stream

为A/B测试创建变量,例如:

split_clients "${remote_addr}AAA" $variant {
               0.5%               .one;
               2.0%               .two;
               *                  "";
}

原始字符串的值通过MurmurHash2进行哈希。在给出的示例中,哈希值从0到21474835(0.5%)对应的$variant变量值为“.one”,哈希值从21474836到107374180(2%)对应的值为“.two”,哈希值从107374181到4294967295对应的值为“”(空字符串)。

nginx中文文档-ngx_stream_geoip_module

此页面版本:2016-08-23,57bc4b4b-c73
ngx_stream_geoip_module模块(1.11.3+)创建变量,变量值依赖于客户端的IP地址,使用预编译的MaxMind数据库。

当使用的数据库支持IPv6时,IPv4的地址会被映射为IPv6的地址。
该模块默认不会构建,需要使用–with-stream_geoip_module参数进行编译。
该模块需要MaxMind GeoIP库。

示例配置

stream {
    geoip_country         GeoIP.dat;
    geoip_city            GeoLiteCity.dat;

    map $geoip_city_continent_code $nearest_server {
        default        example.com;
        EU          eu.example.com;
        NA          na.example.com;
        AS          as.example.com;
    }
   ...
}

geoip_country

语法:geoip_country file
默认:—
上下文:stream

指定一个数据库用于决定依赖于客户端IP的国家。下面的变量在使用数据库时可用:
$geoip_country_code
两个字母的国家代码,例如“RU”、“US”

$geoip_country_code3
三个字母的国家代码,例如“RUS”、“USA”

$geoip_country_name
国家名称,例如“Russian Federation”、“United States”

geoip_city

语法:geoip_city file
默认:—
上下文:stream

指定一个数据库用于决定依赖于客户端IP的国家区域以及城市。下面的变量在使用数据库时可用:

$geoip_area_code
电话区号(仅美国)
这个变量可能包含过时的信息,因为相应的数据库字段可能会过时。

$geoip_city_continent_code
两个字母的大陆编码,例如“EU”、“NA”

$geoip_city_country_code
两个字母的国家编码,例如“RU”、“US”

$geoip_city_country_code3
三个字母的国家编码,例如“RUS”、“USA”

$geoip_city_country_name
国家名称,例如“Russian Federation”、“United States”

$geoip_dma_code
美国DMA区域编码(也成为地铁编码),依据Google AdWords API

$geoip_latitude
纬度

$geoip_longitude
经度

$geoip_region
两个标识符的国家行政区代码(行政区、地域、州、省、联邦等),例如“48”、“DC”

$geoip_region_name
国家行政区名称(行政区、地域、州、省、联邦等),例如“Moscow City”、“District of Columbia”

$geoip_city
城市名称,例如“Moscow”、“Washington”

$geoip_postal_code
邮政编码

geoip_org

语法:geoip_org file
默认:—
上下文:stream

指定一个数据库,用于决定依赖于客户端IP地址的组织。下列变量在使用数据库时可用:

$geoip_org
组织名称,例如“The University of Melbourne”

nginx中文文档-ngx_stream_geo_module

此页面版本:2016-08-10,57ab4631-be8
ngx_stream_geo_module模块(1.11.3+)根据客户端IP地址创建变量。

示例配置:

geo $geo {
    default        0;

    127.0.0.1      2;
    192.168.1.0/24 1;
    10.1.0.0/16    1;

    ::1            2;
    2001:0db8::/32 1;
}

geo

语法:geo [$address] $variable { … }
默认:—
上下文:stream

描述指定变量的值与客户端IP地址之间的依赖关系。默认情况下,地址从$remote_addr变量中获取,但是它可以从另外的变量中获取,例如:

geo $arg_remote_addr $geo {
    ...;
}

由于变量在使用时才会解析,可以在geo中声明一个很大的变量映射表,不会引起任何额外的开销。
如果变量的值不是一个合法的IP地址,则使用“255.255.255.255”。
地址可以指定为CIDR地址块格式,也可以为范围。
下面特殊的参数同样受支持:
delete
删除指定的网络。

default
为那些没有匹配任何指定IP地址的客户端地址设置一个默认值。当地址是以CIDR方式指定,“0.0.0.0/0”和“::/0”用于替换默认值。当默认值没有指定,则默认值为空字符串。

include
包含一个含有地址和值的文件。可以有多个包含。

ranges
声明地址定义为一个范围。这个参数应该在最先出现。为了加快载入的速度,地址应该以升序排列。

例子:

geo $country {
    default        ZZ;
    include        conf/geo.conf;
    delete         127.0.0.0/16;

    127.0.0.0/24   US;
    127.0.0.1/32   RU;
    10.1.0.0/16    RU;
    192.168.1.0/24 UK;
}

conf/geo.conf文件包含以下内容:

10.2.0.0/16    RU;
192.168.2.0/24 RU;

最匹配的值将被使用。例如,地址127.0.0.1会使用“RU”,而不是“US”。

带范围的例子:

geo $country {
    ranges;
    default                   ZZ;
    127.0.0.0-127.0.0.0       US;
    127.0.0.1-127.0.0.1       RU;
    127.0.0.1-127.0.0.255     US;
    10.1.0.0-10.1.255.255     RU;
    192.168.1.0-192.168.1.255 UK;
}

nginx中文文档-ngx_stream_map_module

此页面版本:2016-07-05,577bcc35-cc0
ngx_stream_map_module 模块(1.11.2+)创建变量,其值取决于其他变量的值。

示例配置

map $remote_addr $limit {
    127.0.0.1    "";
    default      $binary_remote_addr;
}

limit_conn_zone $limit zone=addr:10m;
limit_conn addr 1;

map

语法:map string $variable { … }
默认:—
上下文:stream

创建新变量,其值依赖于指定在第一个参数中的一个或多个源变量。
由于变量只有在使用的时候会被计算,可以声明一个很大的变量映射表,而不会带来连接的额外开销。
在map块中的参数指定了一个源与结果值之间的映射关系。
源值定义为字符串或正则表达式。
字符串匹配忽略大小写。
正则表达式可以以“~”标识起始,表示大小写敏感的匹配,也可以以“~*”标识起始,表示大小写不敏感的匹配。一个正则表达式可以包含名称和位置捕获,稍后可以用于其他指令。
如果源值匹配任一个下面描述的特殊参数名,需要用“\”标识作为前缀。
结果值可以包含文本、变量以及它们的混合。
指令可以支持三种特殊参数:
default value
如果源值不匹配任何指定的变量,设置结果值。当没有指定default时,默认结果值是一个空字符串。

hostnames
表明源值可以是带前缀或后缀的主机名:

*.example.com 1;
example.*     1;

下面两个记录:

example.com   1;
*.example.com 1;

可以合并为:

.example.com  1;

该参数需要在列表值之前指定。

include file
包含一个含值的文件,可以有多个包含。

如果源值匹配超过一个定义的变量,例如同时匹配一个标记和正则表达式,先匹配的变量会被选中,按照下面的优先级:

  1. 没有标记的字符串值
  2. 最长的前缀标记字符串,例如“*.example.com”
  3. 最长的后缀标记字符串,例如“mail.*”
  4. 第一个匹配的正则表达式(按出现在配置文件中的顺序)
  5. 默认值

map_hash_bucket_size

语法:map_hash_bucket_size size
默认:map_hash_bucket_size 32|64|128
上下文:stream

为映射变量哈希表设置一个桶的大小。默认大小取决于处理器的缓存行大小。

map_hash_max_size

语法:map_hash_max_size size
默认:map_hash_max_size 2048
上下文:stream

设置变量映射哈希表的最大大小。

nginx中文文档-ngx_stream_return_module

此页面版本:2016-07-05,577bcc35-851
ngx_stream_return_module模块(1.11.2+)允许向客户端发送一个指定的值然后关闭连接。

示例配置

server {
    listen 12345;
    return $time_iso8601;
}

return

语法:return value
默认:—
上下文:server

指定一个值发送到客户端,这个值可以包含文本、变量以及它们的混合。

nginx中文文档-ngx_core_module

本文档包含以下指令:accept_mutex、accept_mutex_delay、daemon、debug_connection、debug_points、error_log、env、events、include、load_module、lock_file、master_process、multi_accept、pcre_jit、pid、ssl_engine、thread_pool、timer_resolution、use、user、worker_aio_requests、worker_connections、worker_cpu_affinity、worker_priority、worker_processes、worker_rlimit_core、worker_rlimit_nofile、working_directory

示例配置

user www www;
worker_processes 2;

error_log /var/log/nginx-error.log info;

events {
    use kqueue;
    worker_connections 2048;
}

...

accept_mutex

语法:accept_mutex on | off
默认:accept_mutex on
上下文:events

如果accept_mutex启用,工作进程会轮流接受新连接。否则,所有工作进程会接到新连接的通知,如果新连接的数量少,一些工作进程会浪费系统资源。

accept_mutex_delay

语法:accept_mutex_delay time
默认:accept_mutex_delay 500ms
上下文:events

如果accept_mutex启用,指定一个最大的时间,在这个期间如果另一个工作进程正在接受新连接,工作进程会尝试重新开始接受新连接。

daemon

语法:daemon on | off
默认:daemon on
上下文:main

决定nginx是否是守护进程。主要用于开发期间。

debug_connection

语法:debug_connection address | CIDR | unix:
默认:—
上下文:events

为选择的客户端连接启用调试日志。其他连接将使用error_log指令设置的日志等级。被调试的连接指定为IPv4或IPv6(1.3.0+,1.2.1+)地址或网络。连接也可以用主机名指定。对于使用UNIX-domain sockets(1.3.0+,1.2.1+)的连接,调试日志通过“unix:”参数启用。

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    ...
}

为了使该指令工作,nginx需要使用–with-debug参数构建。

debug_points

语法:debug_points abort | stop
默认:—
上下文:main

该指令用于调试。
当检测到内部错误,例如,在重启工作进程时泄露的socket,开启debug_points引起核心文件创建(abort)或停止进程(stop)以便后续使用系统调试器进一步分析。

error_log

语法:error_log file [level]
默认:error_log logs/error.log error
上下文:main, http, mail, stream, server, location

配置日志。多个日志可以在同一个等级中指定(1.5.2+)。
第一个参数定义一个文件保存日志。特殊值stderr选择标准错误文件。记录到syslog可以由指定的“syslog:”前缀配置。记录到cyclic memory buffer可以有指定的“memory:”前缀和缓冲区大小配置,一般用于调试(1.7.11+)。
第二个参数决定了日志的等级,可以是下面任何一个值:debug, info, notice, warn, error, crit, alert 或 emerg。上面列出的日志等级是按严重度逐级递增的。如果参数忽略,则使用error。
为了debug记录工作,nginx需要以–with-debug参数构建。
从1.7.11版本起,指令可以在stream等级上指定。
从1.9.0版本起,指令可以在mail等级上指定。

env

语法:env variable[=value]
默认:env TZ
上下文:main

默认情况下,nginx移除所有继承自父进程的环境变量,处理TZ变量。这个指令允许保留一些继承的变量,改变它们的值或创建新的环境变量。这些变量是:

  • 当live upgrade是从可执行文件继承的
  • ngx_http_perl_module模块使用的
  • 工作进程使用的。应该清楚的是,通过这种方式控制系统库不总是可行的,因为一般的库只有在初始化时会检查变量,是在它们可以使用这个指令设置之前。一个例外就是上面提到的live upgrade的可执行文件。

TZ变量总是会继承,对ngx_http_perl_module模块有效,除非显式的配置它。
用法示例:

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

nginx环境变量是nginx内部使用的,不能直接由用户设置。

events

用法:events { … }
默认:—
上下文:main

指定配置文件上下文,用于指定关于连接处理的指令。

include

用法:include file | mask
默认:—
上下文:any

包含另一个文件或匹配指定的mask到配置中。被包含的文件应该保证依据语法结构的正确语句和块。
用法示例:

include mime.types;
include vhosts/*.conf;

load_module

语法:load_module file
默认:—
上下文:main
版本:1.9.11+

加载动态模块。
例子:
load_module modules/ngx_mail_module.so;

lock_file

语法:lock_file file
默认:lock_file logs/nginx.lock
上下文:main

nginx使用锁机制时间accept_mutex和序列化访问共享内存。大多数操作系统上,锁使用原子操作实现,这个指令会被忽略。在其他系统上“lock file”机制被使用。这个指令为锁文件指定一个前缀。

master_process

语法:master_process on | off
默认:master_process on
上下文:main

决定工作进程是否启动。这个指令为开发者准备。

multi_accept

语法:multi_accept on | off
默认:multi_accept off
上下文:events

如果multi_accept禁用,工作进程将一次接受一个新连接。否则一个工作进程会同时接受所有的新连接。
如果使用kqueue连接处理方式,该指令会被忽略,因为它报告等待被接受的新连接的数量。

pcre_jit

语法:pcre_jit on | off
默认:pcre_jit off
上下文:main
版本:1.1.12+

启用或禁用为正则表达式使用“just-in-time compilation”(PCRE JIT)。
PCRE JIT可以显著提升处理正则表达式的速度。
JIT在PCRE库中可以使用时从8.20版本开始同–enable-jit配置参数构建。当PCRE与nginx一同构建(–with-pcre=),JIT支持可以通过–with-pcre-jit配置参数启用。

pid

语法:pid file
默认:pid nginx.pid
上下文:main

定义用于保存主进程的进程ID的文件。

ssl_engine

语法:ssl_engine device
默认:—
上下文:main

定义硬件SSL加速器的名字。

thread_pool

语法:thread_pool name threads=number [max_queue=number]
默认:thread_pool default threads=32 max_queue=65536
上下文:main
版本:1.7.11+

定义线程池名称用于多线程读取和发送文件,不阻塞工作进程。
threads参数定义了线程池中线程的数量。
在线程池中所有线程都繁忙的情况下,新任务会在队列中等待。max_queue参数限制了允许在队列中等待的任务的数量。默认是65536个。当队列溢出,任务会以错误完成。

timer_resolution

语法:timer_resolution interval
默认:—
上下文:main

降低工作进程中的时钟精度,以降低gettimeofday()系统调用发生的次数。默认情况下,gettimeofday()会在每一次内核时间接受后调用。设置后会在指定的间隔调用gettimeofday()。
例子:
timer_resolution 100ms;
间隔的内部实现取决于使用的方法:

  • 如果使用kqueue,则EVFILT_TIMER过滤器
  • 如果使用eventport,则timer_create()
  • 其他情况是setitimer()

use

语法:use method
默认:—
上下文:events

指定使用的连接处理方式。通常不需要显式的指定它,因为nginx默认会使用最高效的方法。

user

语法:user user [group]
默认:user nobody nobody
上下文:main

定义工作进程使用的用户和组的凭证。如果group忽略,会用同user的名字。

worker_aio_requests

语法:worker_aio_requests number
默认:worker_aio_requests 32
上下文:events
版本:1.1.4+1.0.7+

当使用aio和epoll连接处理方式时,设置一个工作进程未完成的异步I/O操作最大数。

worker_connections

语法:worker_connections number
默认:worker_connections 512
上下文:events

设置一个工作进程可以打开的最大并发连接数。
需要记住这个数包含所有连接(例如,与被代理服务器之间的连接),不只是与客户端的连接。还需要考虑的是实际并发连接数不能超过当前打开文件最大数限制,这个可以通过worker_rlimit_nofile改变。

worker_cpu_affinity

语法:worker_cpu_affinity cpumask …;
worker_cpu_affinity auto [cpumask]
默认:—
上下文:main

绑定工作进程与CPU。每个CPU设置体现在允许的CPU的位掩码。应该单独为每个工作进程定义。默认工作进程不会绑定任何指定的CPU。
例如,

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

绑定每一个工作进程到单独的CPU,但

worker_processes    2;
worker_cpu_affinity 0101 1010;

绑定第一个工作进程到CPU0/CPU2,第二个工作进程个到CPU1/CPU3。第二个例子适用于超线程技术。
特殊值auto(1.9.10+)允许自动绑定工作进程到可用的CPU:

worker_processes auto;
worker_cpu_affinity auto;

可选的掩码参数可以用于限制CPU对自动绑定的可用:
worker_cpu_affinity auto 01010101;
该指令只在FreeBSD和Linux系统上可用。

worker_priority

语法:worker_priority number
默认:worker_priority 0
上下文:main

为工作进程定义优先级,负数表示更高的优先级。允许的值从-20到20。
例子:
worker_priority -10;

worker_processes

语法:worker_processes number | auto
默认:worker_processes 1
上下文:main

定义工作进程数。
最佳值取决于很多因素包括(但不限于)CPU核心数、硬盘驱动器保存数据数以及加载的模式。当不确定时,设置为可用CPU核心数比较好(auto值会尝试自动识别)。
auto参数从1.3.8和1.2.5版本开始支持。

worker_rlimit_core

语法:worker_rlimit_core size
默认:—
上下文:main

为工作进程改变核心文件(RLIMIT_CORE)的最大大小的限制。用于增加限制而不重启主进程。

worker_rlimit_nofile

语法:worker_rlimit_nofile number
默认:—
上下文:main

为工作进程改变打开文件(RLIMIT_NOFILE)的最大数限制。用于增加限制而不需要重启主进程。

working_directory

语法:working_directory directory
默认:—
上下文:main

为工作进程定义当前的工作目录。主要用在写核心文件,这种情况下工作进程需要有指定目录的写权限。

nginx中文文档-ngx_stream_upstream_module

ngx_stream_upstream_module模块(1.9.0+)用于定义可以被proxy_pass指令引用的服务器组。

示例配置

upstream backend {
    hash $remote_addr consistent;

    server backend1.example.com:12345  weight=5;
    server backend2.example.com:12345;
    server unix:/tmp/backend3;

    server backup1.example.com:12345   backup;
    server backup2.example.com:12345   backup;
}

server {
    listen 12346;
    proxy_pass backend;
}

动态配置服务器组,可以在商业版本中使用:

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;
    server backend3.example.com:12345 resolve;
    server backend4.example.com       service=http resolve;

    server backup1.example.com:12345  backup;
    server backup2.example.com:12345  backup;
}

server {
    listen 12346;
    proxy_pass dynamic;
    health_check;
}

upstream

语法:upstream name { … }
默认:—
上下文:stream

定义一个服务器组。服务器可以监听不同的端口。另外,服务器可以混合的监听TCP和UNIX-domain socket。
例子:

upstream backend {
    server backend1.example.com:12345 weight=5;
    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:12345 resolve;

    server backup1.example.com:12345  backup;
}

默认情况下,连接会使用带权重的轮询负载均衡方法在服务器之间进行分配。在上面的例子中,每7个连接将会按如下分配:5个连接分到backend1.example.com:12345,第二、第三个服务器各分配一个连接。如果在与服务器通信过程中发生了一个错误,连接将会传递给下一个服务器上,直到所有的服务器都尝试了。如果与所有服务器的通信都失败了,连接将被关闭。

server

语法:server address [parameters]
默认:—
上下文:upstream

定义地址和服务器的其他参数。地址可以定义为域名或IP地址和必须的端口号,或UNIX-domain socket路径指定在“unix:”前缀之后。域名解析成多个IP地址会一次定义多个服务器。
下面的参数可以被定义:
weight=number
设置服务器权重,默认是1。

max_fails=number
设置发生在由fail_timeout参数设置的期间与服务器通信不成功的尝试次数,这个次数会在由fail_timeout参数设置的期间认为是不可用的。默认情况下,不成功的尝试次数设置为1。零值禁用尝试计数。这里,一次不成功的尝试是在与服务器建立连接时发生错误或超时。

fail_timeout=time
设置

  • 一个时间,在这期间指定与服务器通信不成功的尝试次数会认为服务器不可用
  • 一个时间段,在此期间服务器会被认为不可用

默认情况下,该参数为10秒。

backup
标记服务器为备份服务器。当主服务器都不可用时,连接会被传递给备份服务器。

down
标记服务器为永久不可用。

下面的参数在商业版本可用(商业版本不进行翻译):

max_conns=number
limits the maximum number of simultaneous connections to the proxied server. Default value is zero, meaning there is no limit.

resolve
monitors changes of the IP addresses that correspond to a domain name of the server, and automatically modifies the upstream configuration without the need of restarting nginx. The server group must reside in the shared memory.
In order for this parameter to work, the resolver directive must be specified in the stream block. Example:

stream {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com:12345 resolve;
    }
}

service=name
enables resolving of DNS SRV records and sets the service name (1.9.13). In order for this parameter to work, it is necessary to specify the resolve parameter for the server and specify a hostname without a port number.
If the service name does not contain a dot (“.”), then the RFC-compliant name is constructed and the TCP protocol is added to the service prefix. For example, to look up the _http._tcp.backend.example.com SRV record, it is necessary to specify the directive:
server backend.example.com service=http resolve;
If the service name contains one or more dots, then the name is constructed by joining the service prefix and the server name. For example, to look up the _http._tcp.backend.example.com and server1.backend.example.com SRV records, it is necessary to specify the directives:
server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;
Highest-priority SRV records (records with the same lowest-number priority value) are resolved as primary servers, the rest of SRV records are resolved as backup servers. If the backup parameter is specified for the server, high-priority SRV records are resolved as backup servers, the rest of SRV records are ignored.

slow_start=time
sets the time during which the server will recover its weight from zero to a nominal value, or when the server becomes available after a period of time it was considered unavailable. Default value is zero, i.e. slow start is disabled.
If there is only a single server in a group, max_fails, fail_timeout and slow_start parameters are ignored, and such a server will never be considered unavailable.

zone

语法:zone name [size]
默认:—
上下文:upstream

定义用于保存组配置及运行时共享于工作进程的状态的共享内存区域名称和大小。多个组可以共享相同的区域。这种情况下,指定一次区域大小是足够的。
作为商业版本的一部分,这个组允许改变组成员或修改服务器设置而不用重启nginx。配置可以通过特殊的location由upstream_conf处理。

state

语法:state file
默认:—
上下文:upstream
版本:1.9.7+

指定一个文件用于保存动态配置的组的状态。状态目前限制于带参数的服务器列表。文件在解析配置时以及每次upstream 配置改变进行更新时会读取。直接改变文件的内容应该避免。指令不能同server指令一同使用。
在配置重载 或二进制文件升级过程中的改变可能会被丢失。
该指令在商业版本中可用。

hash

语法:hash key [consistent]
默认:—
上下文:upstream

为服务器组指定负载均衡方法:客户端-服务器映射基于哈希键值。目前,只支持的值是指定为$remote_addr的客户端远程地址。注意从组中添加或移除服务器会导致重映射关键字到不同的服务器。该方法与Perl库中的Cache::Memcached一致。
如果指定consistent参数,ketama一致性哈希方法会被使用。该方法确保在服务器从组中添加或删除时只有很少重映射到不同的服务器。这有助于缓存服务器的更高的缓存命中率。该方法与Perl库带ketama_points参数设置为160时的Cache::Memcached::Fast一致。

least_conn

语法:least_conn
默认:—
上下文:upstream

指定一个服务器组的负载均衡方法:连接会传递给最少活跃连接的服务器中,会考虑服务器权重。如果有多个这样的服务器,它们会通过使用带权重的轮询负载均衡方法轮流尝试。

least_time

语法:least_time connect | first_byte | last_byte
默认:—
上下文:upstream

指定一个组使用的负载均衡方法:连接将传递给平均时间最少和活跃连接最少的服务器上,会考虑服务器权重。如果由多个服务器满足,它们会通过带权重的负载均衡方法轮流尝试。
如果指定了connect参数,会使用连接到上游服务器的时间。如果first_byte参数指定,使用收到数据的第一个字节的时间。如果指定了last_byte,使用受到数据的最后一个字节的时间。
该指令在商业版本上可用。

health_check

语法:health_check [parameters]
默认:—
上下文:server

启用组中服务器的健康检查。
支持下面的参数:
interval=time
设置两次连续的健康检查时间间隔,默认是5秒。

fails=number
设置一个服务器连续的健康检查失败次数,在这之后服务器会被认为是不健康的,默认是1。

passes=number
设置一个服务器连续的健康检查通过次数,在这之后服务器会被认为是健康的,默认是1。

match=name
指定match块配置测试,该测试用于健康检查通过。默认,能够建立TCP连接就是通过。

port=number
定义用于连接服务器进行健康检查的端口(1.9.7+)。默认等于服务器的端口。

udp
指定使用UDP协议进行健康检查而不是默认的TCP协议(1.9.13+)。需要带send和expect参数的match块。
例如,

server {
    proxy_pass backend;
    health_check;
}

将每5秒钟检测backend组中的每个服务器能否建立TCP连接。当到服务器的连接不能建立时,健康检查失败,服务器会被认为是不健康的。客户端连接将不会传递给不健康的服务器。
健康检查也可以配置为检测服务器获取的数据。测试配置单独使用match指令和match参数中的引用。
服务器组必须在同一个共享内存中。
如果多个健康检查为同一个组定义,任何健康检查失败都会使相应的服务器视为不健康的。
该指令是商业版本中的一部分。

health_check_timeout

语法:health_check_timeout timeout
默认:health_check_timeout 5s
上下文:stream, server

覆盖健康检查的proxy_timeout值。
该指令是商业版的一部分。

match

语法:match name { … }
默认:—
上下文:stream

定义命名的测试,用于验证服务器响应的健康检查。
下面的参数可以配置:
send string;
向服务器发送字符串。

expect string | ~ regex;
一个从服务器获取的数据中需要匹配的字面字符串(1.9.12+)或正则表达式。正则表达式指定以“~*”开头(大小写不敏感匹配)或“~”开头(大小写敏感匹配)。send和expect参数都可以包含十六进制的字面量,前缀“\x”跟着两个16进制数字,例如“\x80”(1.9.12+)。
如果:

  • TCP连接成功建立
  • 如果指定了send参数的字符串,并发送了
  • 如果指定了字符串或正则表达式,从服务器收到的数据匹配字符串或expect参数的正则表达式
  • 时间没有超过health_check_timeout指令指定的值

健康检查通过。
示例:

upstream backend {
    zone     upstream_backend 10m;
    server   127.0.0.1:12345;
}

match http {
    send     "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
    expect ~ "200 OK";
}

server {
    listen       12346;
    proxy_pass   backend;
    health_check match=http;
}

只有从服务器获取的第一个proxy_buffer_size字节的数据会被检查。
该指令为商业版本的一部分。

nginx中文文档-ngx_stream_ssl_module

ngx_stream_ssl_module模块(1.9.0+)为代理流服务器提供必要的SSL/TLS协议支持。该模块默认不会构建,需要通过–with-stream_ssl_module配置参数启用。

示例配置
为降低处理器负载,建议

  • 设置工作进程数等于处理器个数
  • 启用共享会话缓存
  • 禁用built-in会话缓存
  • 增加会话的有效期(默认是5分钟)
worker_processes auto;

stream {

    ...

    server {
        listen              12345 ssl;

        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

ssl_certificate

语法:ssl_certificate file
默认:—
上下文:stream, server

为给定的服务器指定一个PEM格式的证书文件。如果中级证书需要指定在初级证书中,它们需要在相同的文件中按如下顺序指定:初级证书在前,然后是中级证书。PEM格式的密钥也应该放到相同文件中。
从1.11.0版本开始,该指令可以指定多次加载不同类型的证书,例如RSA和ECDSA:

server {
    listen              12345 ssl;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

    ...
}

只有OpenSSL1.0.2及更高版本支持分离的不同证书链。旧版本只有一个证书链可以使用。

ssl_certificate_key

语法:ssl_certificate_key file
默认:—
上下文:stream, server

为给定的服务器指定一个PEM格式的密钥文件。
engine:name:id值可以代替文件指定,会从OpenSSL引擎name中加载指定id的密钥。

ssl_ciphers

语法:ssl_ciphers ciphers
默认:ssl_ciphers HIGH:!aNULL:!MD5
上下文:stream, server

指定启用的加密算法。加密算法指定为OpenSSL库可以识别的格式,例如:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
完整的列表可以通过“openssl ciphers”命令查看。

ssl_dhparam

语法:ssl_dhparam file
默认:—
上下文:stream, server

为DHE算法指定一个包含DH参数的文件。

ssl_ecdh_curve

语法:ssl_ecdh_curve curve
默认:ssl_ecdh_curve auto
上下文:stream, server

为ECDHE算法是定一个curve。
当使用OpenSSL1.0.2或更高版本时,可以指定多个curves(1.11.0+),例如:
ssl_ecdh_curve prime256v1:secp384r1;
在使用OpenSSL1.0.2及更高版本时,特殊值auto(1.11.0+)指示nginx使用一个OpenSSL库中建立的列表,老版本使用prime256v1。
在1.11.0版本之前,prime256v1 curve会被默认使用。

ssl_handshake_timeout

语法:ssl_handshake_timeout time
默认:ssl_handshake_timeout 60s
上下文:stream, server

指定SSL握手完成的超时时间。

ssl_password_file

语法:ssl_password_file file
默认:—
上下文:stream, server

指定一个文件保存密钥的密码,每个密码指定在单独的一行中。密码在加载密钥时会轮流尝试。
示例:

stream {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        listen 127.0.0.1:12345;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        listen 127.0.0.1:12346;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}

ssl_prefer_server_ciphers

语法:ssl_prefer_server_ciphers on | off
默认:ssl_prefer_server_ciphers off
上下文:stream, server

指定当使用SSLv3和TLS协议使用时服务器加密算法应该优先于客户端加密算法。

ssl_protocols

语法:ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]
默认:ssl_protocols TLSv1 TLSv1.1 TLSv1.2
上下文:stream, server

启用指定的协议。TLSv1.1和TLSv1.2参数只有OpenSSL库在1.0.1及更高版本使用时才有效。

ssl_session_cache

语法:ssl_session_cache off | none | [builtin[:size]] [shared:name:size]
默认:ssl_session_cache none
上下文:stream, server

设置保存会话参数的缓存类型和大小。缓存可以下面任意类型:
off
使用会话缓存是强烈禁止的:nginx明确告诉客户端会话不能被重用。

none
使用会话缓存是不允许的:nginx告诉客户端会话可以重用,但实际上会话参数不会保存在缓存中。

builtin
构建在OpenSSL中的缓存,只被一个工作进程使用。缓存大小指定在会话中。如果没给出大小,它等于20480个会话,使用built-in缓存可以引起内存碎片。

shared
在工作进程之间共享的缓存。缓存大小指定为字节。1M可以保存大约4000个会话。每个共享缓存有一个唯一的名字。相同名字的缓存可以在多个服务器之间使用。
缓存和类型可以同时使用,例如:
ssl_session_cache builtin:1000 shared:SSL:10m;
但是只使用共享缓存不带built-in缓存会更有效率。

ssl_session_ticket_key

语法:ssl_session_ticket_key file
默认:—
上下文:stream, server

设置一个带密钥的文件用于加密和解密TLS会话凭据。如果相同的密钥在多个服务器之间共享,该指令是必要的。默认情况下,会使用随机生成的密钥。
如果指定的多个密钥,只有第一个密钥会用于加密TLS会话凭据。这允许配置密钥循环,例如:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

文件必须包含48字节的随机数据,可以通过下面命令创建:
openssl rand 48 > ticket.key

ssl_session_tickets

语法:ssl_session_tickets on | off
默认:ssl_session_tickets on
上下文:stream, server

启用或禁用通过TLS会话凭证的会话恢复。

ssl_session_timeout

语法:ssl_session_timeout time
默认:ssl_session_timeout 5m
上下文:stream, server

指定一个时间,在这个期间客户端可以重用保存在缓存中的会话参数。

nginx中文文档-ngx_stream_proxy_module

ngx_stream_proxy_module模块(1.9.0+)允许代理TCP、UDP(1.9.13+)以及UNIX-domain socket的数据流。

示例配置

server {
    listen 127.0.0.1:12345;
    proxy_pass 127.0.0.1:8080;
}

server {
    listen 12345;
    proxy_connect_timeout 1s;
    proxy_timeout 1m;
    proxy_pass example.com:12345;
}

server {
    listen 53 udp;
    proxy_responses 1;
    proxy_timeout 20s;
    proxy_pass dns.example.com:53;
}

server {
    listen [::1]:12345;
    proxy_pass unix:/tmp/stream.socket;
}

proxy_bind

语法:proxy_bind address [transparent] | off
默认:—
上下文:stream, server
版本:1.9.2+

从指定的本地IP地址向被代理服务器发起外部连接。特殊值off取消从上层配置中继承的proxy_bind指令产生的影响,允许系统自动分配本地IP地址。
transparent参数(1.11.0+)允许从一个非本地IP地址发起到被代理服务器的外部连接,例如从一个客户端的真实IP地址:
proxy_bind $remote_addr transparent;
为了使这个参数生效,需要以超级用户权限运行nginx工作进程,并配置核心路由表以截获从被代理服务器的网络流量。

proxy_buffer_size

语法:proxy_buffer_size size
默认:proxy_buffer_size 16k
上下文:stream, server
版本:1.9.4+

设置用于读取来自于被代理服务器的数据缓冲区大小。同时设置用于读取来自于客户端的数据缓冲区大小。

proxy_connect_timeout

语法:proxy_connect_timeout time
默认:proxy_connect_timeout 60s
上下文:stream, server

定义一个与被代理服务器建立连接的超时时间。

proxy_download_rate

语法:proxy_download_rate rate
默认:proxy_download_rate 0
上下文:stream, server
版本:1.9.3+

限制从被代理服务器读取数据的速度。速度定义为字节每秒。零值禁用限速。限制是针对每个连接,所以如果nginx同时打开两个连接到被代理服务器,整体的速度将为指定限速的两倍。

proxy_next_upstream

语法:proxy_next_upstream on | off
默认:proxy_next_upstream on
上下文:stream, server

当与被代理服务器的连接不能够建立时,决定客户端连接是否传递到下一个服务器。
传递连接到下一个服务器可以由尝试次数和时间限制。

proxy_next_upstream_timeout

语法:proxy_next_upstream_timeout time
默认:proxy_next_upstream_timeout 0
上下文:stream, server

限制允许传递连接到下一个服务器的时间。零值关闭这个限制。

proxy_next_upstream_tries

语法:proxy_next_upstream_tries number
默认:proxy_next_upstream_tries 0
上下文:stream, server

限制传递连接到下一个服务器的尝试次数。零值关闭这个限制。

proxy_pass

语法:proxy_pass address
默认:—
上下文:server

设置被代理服务器的地址。地址可以定义为一个域名或IP地址和一个端口号:
proxy_pass localhost:12345;
或一个UNIX-domain socket路径:
proxy_pass unix:/tmp/stream.socket;
如果域名解析成多个地址,它们会轮流使用。地址可以指定为一个服务器组。

proxy_protocol

语法:proxy_protocol on | off
默认:proxy_protocol off
上下文:stream, server
版本:1.9.2+

为连接到被代理服务器启用PROXY协议。

proxy_responses

语法:proxy_responses number
默认:—
上下文:stream, server
版本:1.9.13+

如果使用UDP协议,设置期望从被代理服务器响应给客户端请求的数据报数量。默认数据报数量是不限制的:响应数据报将一直发送直到proxy_timeout值过期。

proxy_ssl

语法:proxy_ssl on | off
默认:proxy_ssl off
上下文:stream, server

为连接到被代理服务器启用SSL/TLS协议。

proxy_ssl_certificate

语法:proxy_ssl_certificate file
默认:—
上下文:stream, server

指定PEM格式的证书文件用于验证被代理服务器。

proxy_ssl_certificate_key

语法:proxy_ssl_certificate_key file
默认:—
上下文:stream, server

指定PEM格式的密钥文件,用于验证被代理服务器。

proxy_ssl_ciphers

语法:proxy_ssl_ciphers ciphers
默认:proxy_ssl_ciphers DEFAULT
上下文:stream, server

为连接到被代理服务器指定可用的加密算法。加密算法指定为OpenSSL库可以理解的格式。
完整的列表可以通过“openssl ciphers”命令查看。

proxy_ssl_crl

语法:proxy_ssl_crl file
默认:—
上下文:stream, server

指定一个PEM格式的吊销证书文件,用于验证被代理服务器的证书。

proxy_ssl_name

语法:proxy_ssl_name name
默认:proxy_ssl_name host from proxy_pass
上下文:stream, server

允许覆盖用于验证被代理服务器的服务器名称,并通过SNI在与被代理服务器建立连接时传递。
默认proxy_pass地址的host部分会被使用。

proxy_ssl_password_file

语法:proxy_ssl_password_file file
默认:—
上下文:stream, server

为密钥指定一个密码文件,密码指定在单独的行中。在加载密钥时密码会被轮流尝试。

proxy_ssl_server_name

语法:proxy_ssl_server_name on | off
默认:proxy_ssl_server_name off
上下文:stream, server

启用或禁用在与被代理服务器建立连接时,通过TLS Server Name Indication扩展(SNI,RFC 6066)传递服务器名称。

proxy_ssl_session_reuse

语法:proxy_ssl_session_reuse on | off
默认:proxy_ssl_session_reuse on
上下文:stream, server

决定与被代理服务器工作时是否可以重用SSL会话。如果在日志中出现“SSL3_GET_FINISHED:digest check failed”错误,尝试禁用会话重用。

proxy_ssl_protocols

语法:proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]
默认:proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2
上下文:stream, server

为连接到被代理服务器启用指定的协议。

proxy_ssl_trusted_certificate

语法:proxy_ssl_trusted_certificate file
默认:—
上下文:stream, server

指定一个PEM格式的可信CA证书文件,用于验证被代理服务器的证书。

proxy_ssl_verify

语法:proxy_ssl_verify on | off
默认:proxy_ssl_verify off
上下文:stream, server

启用或禁用验证被代理服务器证书。

proxy_ssl_verify_depth

语法:proxy_ssl_verify_depth number
默认:proxy_ssl_verify_depth 1
上下文:stream, server

设置验证被代理服务器证书链深度。

proxy_timeout

语法:proxy_timeout timeout
默认:proxy_timeout 10m
上下文:stream, server

设置两次成功的与被代理服务器或客户端的连接之间读写操作的超时时间。如果在这个时间没有数据传输,连接将被关闭。

proxy_upload_rate

语法:proxy_upload_rate rate
默认:proxy_upload_rate 0
上下文:stream, server
版本:1.9.3+

限制从客户端读取数据的速度。速率指定为字节每秒。零值禁用速度限制。限制针对每一个连接,所以如果客户端同时开启两个连接,整体速率将为指定限制的两倍。

nginx中文文档-ngx_stream_limit_conn_module

ngx_stream_limit_conn_module模块(1.9.3+)用于限制每一个定义的关键字的连接数,尤其是从单个IP地址收到的连接数。

示例配置

stream {
    limit_conn_zone $binary_remote_addr zone=addr:10m;

    ...

    server {

        ...

        limit_conn           addr 1;
        limit_conn_log_level error;
    }
}

limit_conn

语法:limit_conn zone number
默认:—
上下文:stream, server

为给定的键值设置设置共享内存区域以及最大允许的连接数。当超过这个限制,服务器会关闭连接。例如指令

limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
    ...
    limit_conn addr 1;
}

允许一个IP同时只有一个连接。
当指定多个limit_conn指令时,任何配置的限制都会应用。
当且仅当当前层级中没有limit_conn指令时,指令会继承自上级。

limit_conn_log_level

语法:limit_conn_log_level info | notice | warn | error
默认:limit_conn_log_level error
上下文:stream, server

设置当服务器限制连接数时记录日志的等级。

limit_conn_zone

语法:limit_conn_zone key zone=name:size
默认:—
上下文:stream

设置保存各种关键字状态的共享内存区域参数。状态包含当前连接数。目前,支持关键字的值是客户端地址的二进制格式,指定为$binary_remote_addr。空关键字值的连接不计数。用法示例:
limit_conn_zone $binary_remote_addr zone=addr:10m;
这里,关键字是由$binary_remote_addr设置的客户端IP地址。$binary_remote_addr的大小IPv4地址是4字节,IPv6地址是16字节。保存的状态总是在32位系统上占用32或64字节,在64位系统上是64字节。1M的区域可以保存大约32,000个32字节状态或大约16,000个64字节状态。如果存储区域耗尽,服务器就会关闭连接。