HAProxy–理论–03–配置文件中的关键字参考

1、balance

balance [ ]

balance url_param [check_post []]
  1. 可用于"defaults"、“listen"和"backend”。
  2. 定义负载均衡算法，用于在负载均衡场景中挑选一个server
  3. 仅应用于持久信息不可用的条件下或需要将一个连接重新派发至另一个服务器时。
  4. 支持的算法如下

1.1、 roundrobin（Round-Robin）

  1. 基于权重进行轮询
  2. 在服务器的处理时间保持均匀分布时，这是最平衡、最公平的算法。
  3. 此算法是动态的，其权重可以在运行时进行调整，
  4. 每个后端服务器仅能最多接受4128个连接；
  5. 支持慢启动。

1.2、 static-rr（Static Round-Robin）

  1. 基于权重进行轮询
  2. 与roundrobin类似，但是为静态方法，在运行时调整其服务器权重不会生效
  3. 后端服务器连接数上没有限制
  4. 不支持慢启动，在高负荷的情况下，服务器重新上线时会立即被分配大量连接。

1.3、 leastconn（WLC:Least-connection）

  1. 适用于长连接的会话，新的连接请求被派发至具有最少连接数目的后端服务器
  2. 在有着较长时间会话的场景中推荐使用此算法，如LDAP、SQL等
  3. 不太适用于较短会话的应用层协议，如HTTP
  4. 此算法是动态的，可以在运行时调整其权重；

1.4、 source

  1. 将请求中的源IP地址进行HASH后除以全部正常运行的后端服务器权重来决定接收服务请求的服务器；
  1. hash（ip）/weight
  1. 可以使得同一个客户端IP的请求始终被派发至某特定的服务器；不过，当服务器权重总数发生变化时，则响应该客户端请求的后端服务器会改变，因为这时的 HASH/Wight值已经改变
  2. 常用于负载均衡无cookie功能的基于TCP的协议
  3. 默认为静态，不过也可以使用hash-type修改此特性；

1.5、 URL（url）

  1. 对URI的左半部分("问题"标记之前的部分)或整个URI进行hash运算，并由服务器的总权重相除后派发至某匹配的服务器；
  2. 可以使得对同一个URI的请求总是被派发至某特定的服务器，除非服务器的权重总数发生了变化
  3. 此算法常用于代理缓存或反病毒代理以提高缓存的命中率
  4. 用于Web Cache集群中，通过URL负载均衡算法，可以避免请求因为指向不同的cache服务器而导致缺页，而缺页会导致刷新 cache最终降低系统响应速率。
  5. 默认为静态算法，不过也可以使用hash-type修改此特性；

1.6、URL Parameter（uri_param）

  1. 该算法通过查询源 HTTP请求报文中的某一字符串参数并将其进行 HASH后除以全部服务器权重来决定接收服务请求的服务器。如果HTTP报文中没有需要的参数，则默认使用Round_Robin算法
  2. 对于每个HTTP请求，通过< argument >指定参数；
  3. 此算法可以通过追踪请求中的用户标识进而确保同一个用户ID的请求将被送往同一个特定的服务器，除非服务器的总权重发生了变化；
  4. 此算法默认为静态的，不过其也可以使用hash-type修改此特性；

1.7、 hdr()

  1. 该算法通过查询HTTP请求报文中的HEAD字段并将HASH后除以全部服务器权重来决定接收服务请求的服务器。
  2. 如果报文中没有HEAD参数，则默认使用Round_Robin算法
  3. 对于每个HTTP请求，通过< name >指定HEAD参数；
  4. 有一个可选选项"use_domain_only"，可在指定检索类似Host类的首部时仅计算域名部分(比如通过www.feiyu.com来说，仅计算feiyu字符串的hash值)以降低hash算法的运算量；
  5. 此算法默认为静态的，不过其也可以使用hash-type修改此特性；

1.8、rdp-cookie(name)

根据cookie(name)来锁定并哈希每一次TCP请求。

2、bind

bind [<address>]:<port_range> [, …]

bind [<address>]:<port_range> [, …] interface <interface>
  1. 用于定义一个或几个监听的套接字
  2. 仅能用于frontend和listen区段。

2.1、< address >

  1. 可选选项
  1. 可以为主机名、IPv4地址、IPv6地址或*；
  1. 省略此选项、将其指定为*或0.0.0.0时，将监听当前系统的所有IPv4地址；

2.2、< port_range >

  1. 可以是一个特定的TCP端口
  2. 可以是一个端口范围(如5005-5010)
  3. 代理服务器将通过指定的端口来接收客户端请求；
  4. 每组监听的套接字< address:port >在同一个实例上只能使用一次
  5. 小于1024的端口需要有特定权限的用户才能使用，这可能需要通过uid参数来定义

2.2、< interface >

  1. 指定物理接口的名称
  2. 仅能在Linux系统上使用
  3. 其不能使用接口别名，而仅能使用物理接口名称，而且只有管理有权限指定绑定的物理接口

3、mode

mode { tcp|http|health }
  1. 设定实例的运行模式或协议。
  2. 当实现内容交换时，前端和后端必须工作于同一种模式(一般说来都是HTTP模式)，否则将无法启动实例。

3.1、tcp

  1. 实例运行于纯TCP模式，在客户端和服务器端之间将建立一个全双工的连接，且不会对7层报文做任何类型的检查；
  2. 通常用于SSL、SSH、SMTP等应用；

3.2、http

  1. 实例运行于HTTP模式，客户端请求在转发至后端服务器之前将被深度分析，所有不与RFC格式兼容的请求都会被拒绝
  2. 此为默认模式；

3.3、health

  1. 实例工作于health模式，其对入站请求仅响应"OK"信息并关闭连接，且不会记录任何日志信息；
  2. 此模式将用于响应外部组件的健康状态检查请求；
  3. 目前来讲，此模式已经废弃，因为tcp或http模式中的monitor关键字可完成类似功能

4、hash-type

hash-type <method>
  1. 用于将hash码映射至后端服务器的方法
  2. 不能用于frontend区段
  3. 可用方法有map-based和consistent，在大多数场景下推荐使用默认的map-based方法。

4.1、map-based

hash表是一个包含了所有在线服务器的静态数组。其hash值将会非常平滑，会将权重考虑在列，但其为静态方法，对在线服务器的权重进行调整将不会生效，这意味着其不支持慢速启动。

此外，挑选服务器是根据其在数组中的位置进行的，因此，当一台服务器宕机或添加了一台新的服务器时，大多数连接将会被重新派发至一个与此前不同的服务器上，对于缓存服务器的工作场景来说，此方法不甚适用。

4.2、consistent

“一致性哈希算法”，hash表是一个由各服务器填充而成的树状结构，将服务器散列在hash环上；基于hash键在hash树中查找相应的服务器时，最近的服务器将被选中。

此方法是动态的，支持在运行时修改服务器权重，因此兼容慢速启动的特性。添加一个新的服务器时，仅会对一小部分请求产生影响，因此，尤其适用于后端服务器为cache的场景。不过，此算法不甚平滑，派发至各服务器的请求未必能达到理想的均衡效果，因此，可能需要不时的调整服务器的权重以获得更好的均衡性。

5、log

log global
 
log <address> <facility> [<level> [<minlevel>]]
  1. 为每个实例启用事件和流量日志，因此可用于所有区段。
  2. 每个实例最多可以指定两个log参数，不过，如果使用了"log global",且"global"段已经定了两个log参数时，多余了log参数将被忽略。

global：当前实例的日志系统参数同”global”段中的定义时，将使用此格式；每个实例仅能定义一次"log global"语句，且其没有任何额外参数；

5.1、global

  1. 继承 global 中 log 的定义
  2. 每个实例仅能定义一次"log global"语句，且其没有任何额外参数；

5.1、< address >

定义日志发往的位置

格式1

1可以为< IPv4_address:PORT>
port:为UDP协议端口，默认为514

格式2

为Unix套接字文件路径，但需要留心chroot应用及用户的读写权限；

5.2、< facility >

可以为syslog系统的标准facility之一

5.2、< level >

  1. 定义日志级别，即输出信息过滤器
  2. 默认为所有信息
  3. 指定级别时，所有等于或高于此级别的日志信息将会被发送；

6、maxconn

maxconn <conns>
  1. 设定每个haproxy进程所接受的最大并发连接数
  2. 等同于命令行选项"-n","ulimit -n"自动计算的结果正是参照此参数设定的
  3. 不能用于 backend 区段
  4. 对于大型站点来说，可以尽可能提高此值以便让 haproxy 管理连接队列， 从而避免无法应答用户请求。
  5. 注意：
  1. haproxy 会为每个连接维持两个缓冲，每个缓存的大小为 8KB，再加上其他的数据，每个连接将大约占用 17KB 的 RAM 空间，这意味着经过适当优化后 ，有着 1GB 的可用 RAM 空间时将维护 40000-50000 并发连接。
  2. 如果指定了一个过大值，极端场景中，其最终所占据的空间可能会超过当前主机的可用内存，这可能会带来意想不到的结果，因此，将其设定一个可接受值放为明智绝对
  1. 默认为 2000

7、default_backend

default_backend <backend>
  1. 在没有匹配的"use_backend"规则时为实例指定使用的默认后端，因此，其不可应用于backend区段。2. 2. 在"frontend"和"backend"之间进行内容交换时，通常使用"use-backend"定义其匹配规则；而没有被规则匹配到的请求将由此参数指定的后端接收。

7.1、< backend>

指定使用的后端的名称；

7.2、使用案例：

use_backend dynamic if url_dyn
use_backend static if url_css url_img extension_img
default_backend dynamic

8、server

server <name> <address>[:port] [param*]
  1. 为后端声明一个server
  2. 不能用于defaults和frontend区段。
  3. 只能用于 listen 和 backend 区段

8.1、< name>

  1. 为此服务器指定的内部名称，其将出现在日志及警告信息中；
  2. 如果设定了"http-send-server-name"，它还将被添加至发往此服务器的请求首部中；

8.2、< address>

  1. 此服务器的的IPv4地址，也支持使用可解析的主机名，只不过在启动时需要解析主机名至相应的IPv4地址；

8.3、[:port]：

  1. 将连接请求发往目标服务器的端口
  2. 为可选项；未设定时，将使用客户端请求时的同一个端口；

8.4、[param*]：

  1. 为此服务器设定的一系参数；
  2. 其可用的参数非常多，下面仅说明几个常用的服务器或默认服务器参数；

8.4.1、backup

  1. 设定为备用服务器，仅在负载均衡场景中的其它server均不可用时，启用此server；

8.4.2、check

启动对此server执行健康状态检查，其可以借助于额外的其它参数完成更精细的设定,如下所示

inter < delay>
  1. 设定健康状态检查的时间间隔
  2. 单位为毫秒
  3. 默认为2000
  4. 也可以使用fastinter和downinter来根据服务器端状态优化此时间延迟；
rise < count>

某离线的server从离线状态转换至正常状态需要成功检查的次数；

fall < count>

确认server从正常状态转换为不可用状态需要检查的次数；

8.4.3、cookie < value>

为指定server设定cookie值，此处指定的值将在请求入站时被检查，第一次为此值挑选的server将在后续的请求中被选中，其目的在于实现持久连接的功能；

8.4.4、maxconn < maxconn>

  1. 指定此服务器接受的最大并发连接数；
  2. 如果发往此服务器的连接数目高于此处指定的值，其将被放置于请求队列，以等待其它连接被释放；
注意

haproxy 有n个进程，每个支持m个连接，后端有x个服务器，每个最大支持y个连接，则 nm <= xy，如果后端服务器支持排队，则nm <= x（y+z），z为每个服务器的排队队列

8.4.5、maxqueue < maxqueue>

设定请求队列的最大长度；

8.4.6、observe

  1. 通过观察服务器的通信状况来判定其健康状态
  2. 默认为禁用
  3. 其支持的类型有"layer4"和"layer7"，"layer7"仅能用于http代理场景；

8.4.7、redir < prefix>

  1. 启用重定向功能，将发往此服务器的GET和HEAD请求均以302状态码响应；
  2. 需要注意的是，在prefix后面不能使用/，且不能使用相对地址，以免造成循环；例如：
server srv1 172.16.100.6:80 redir http://imageserver.feiyu.com check

8.4.8、weight < weight>

  1. 权重
  2. 默认为1
  3. 最大值为256
  4. 0表示不参与负载均衡（不被调度）；

8.5、检查方法

option httpchk
  1. 后端服务状态检测
  2. 不能用于frontend段
案例
option httpchk
backend https_relay
mode tcp
option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www.feiyu.com
server apache1 192.168.1.1:443 check port 80
  1. 向后端服务器apache1的 80 端口发送 OPTIONS 请求(原理请参考 HTTP 协议) ，HAProxy 会根据返回内容来判断后端服务是否可用.
  2. 2xx 和 3xx 的响应码表示健康状态，其他响应码或无响应表示服务器故障。

8.6、使用案例：

server first 172.16.100.7:1080 cookie first check inter 1000
server second 172.16.100.8:1080 cookie second check inter 1000

9、capture request header

capture request header <name> len <length>
  1. 捕获并记录指定的请求首部最近一次出现时的第一个值
  2. 仅能用于"frontend"和"listen"区段。
  3. 捕获的首部值使用花括号{}括起来后添加进日志中。如果需要捕获多个首部值，它们将以指定的次序出现在日志文件中，并以竖线"|"作为分隔符。不存在的首部记录为空字符串
  4. 最常需要捕获的首部包括
  1. 在虚拟主机环境中使用的"Host"
  2. 上传请求首部中的"Content-length"
  3. 快速区别真实用户和网络机器人的"User-agent"
  4. 以及代理环境中记录真实请求来源的"X-Forward-For"。

9.1、< name>

  1. 要捕获的首部的名称
  2. 此名称不区分字符大小写，但建议与它们出现在首部中的格式相同，比如大写首字母。
  3. 注意：记录在日志中的是首部对应的值，而非首部名称。

9.2、

  1. 指定记录首部值时所记录的精确长度
  2. 超出的部分将会被忽略。

9.3、备注

  1. 可以捕获的请求首部的个数没有限制，但每个捕获最多只能记录64个字符。
  2. 为了保证同一个frontend中日志格式的统一性，首部捕获仅能在frontend中定义。

10、capture response header

capture response header <name> len <length>
  1. 捕获并记录响应首部
  2. 格式和要点 与 capture request header 相同

11、stats

11.1、stats enable

  1. 启用基于程序编译时默认设置的统计报告
  2. 不能用于"frontend"区段。
  3. 默认配置如下
- stats uri : /haproxy?stats
- stats realm : "HAProxy Statistics"
- stats auth : no authentication
- stats scope : no restriction
  1. 下面给出一个配置案例
backend public_www
server websrv1 172.16.100.11:80
stats enable
stats hide-version
stats scope .
stats uri /haproxyadmin?stats
stats realm Haproxy\ Statistics
stats auth statsadmin:password
stats auth statsmaster:password

11.2、stats hide-version

  1. 启用统计报告并隐藏HAProxy版本报告
  2. 不能用于"frontend"区段。
  3. 默认情况下，统计页面会显示一些有用信息，包括HAProxy的版本号，然而，向所有人公开HAProxy的精确版本号是非常有风险的，因为它能帮助恶意用户快速定位版本的缺陷和漏洞。尽管"stats hide-version"一条就能够启用统计报告，但还是建议设定其它所有的参数，以免其依赖于默认设定而带来非期后果。

11.3、 stats realm

stats realm <realm>
  1. 启用统计报告并高精认证领域
  2. 不能用于"frontend"区段。
  3. haproxy在读取realm时会将其视作一个单词，因此，中间的任何空白字符都必须使用反斜线进行转义。
  4. 此参数仅在与"stats auth"配置使用时有意义。
< realm>
  1. 实现HTTP基本认证时显示在浏览器中的领域名称
  2. 用于提示用户输入一个用户名和密码。

11.4、 stats scope

stats scope { <name> | "." }
  1. 启用统计报告并限定报告的区段
  2. 不能用于"frontend"区段。
  3. 当指定此语句时，统计报告将仅显示其列举出区段的报告信息，所有其它区段的信息将被隐藏。如果需要显示多个区段的统计报告，此语句可以定义多次。
  4. 注意:区段名称检测仅仅是以字符串比较的方式进行，它不会真检测指定的区段是否真正存在。
< name>：
  1. 可以是一个"listen"、"frontend"或"backend"区段的名称
  2. "."表示stats scope语句所定义的当前区段。

11.5、 stats auth

stats auth <user>:<passwd>
  1. 启用带认证的统计报告功能并授权一个用户帐号
  1. 可以定义多次以授权多个用户帐号
  1. 不能用于"frontend"区段。
  2. 可以结合"stats realm"参数在提示用户认证时给出一个领域说明信息。
  3. 在使用非法用户访问统计功能时，其将会响应一个"401 Forbidden"页面。
  4. 认证方式为HTTP Basic认证，密码传输会以明文方式进行
< user>

授权进行访问的用户名；

< passwd>

此用户的访问密码，明文格式；

11.6、 stats admin

stats admin { if | unless } <cond>
  1. 在指定的条件满足时启用统计报告页面的管理级别功能
  2. 允许通过web接口启用或禁用服务器，不过，基于安全的角度考虑，统计报告页面应该尽可能为只读的。
  3. 如果启用了HAProxy的多进程模式，启用此管理级别将有可能导致异常行为。

目前来说，POST请求方法被限制于仅能使用缓冲区减去保留部分之外的空间，因此，服务器列表不能过长，否则，此请求将无法正常工作。因此，建议一次仅调整少数几个服务器。

下面是两个案例

# 第1个:限制了仅能在本机打开报告页面时启用管理级别功能
backend stats_localhost
stats enable
stats admin if LOCALHOST

# 第2个:定义了仅允许通过认证的用户使用管理级别功能。
backend stats_auth
stats enable
stats auth haproxyadmin:password
stats admin if TRUE

12、option httplog

option httplog [ clf ]

启用日志记录HTTP请求、会话状态和计时器的功能。

12.1、clf

  1. 使用CLF格式来代替HAProxy默认的HTTP格式，通常在使用仅支持CLF格式的特定日志分析器时才需要使用此格式。
  2. 默认情况下，日志输入格式非常简陋，因为其仅包括源地址、目标地址和实例名称，而"option httplog"参数将会使得日志格式变得丰富许多，其通常包括
  1. HTTP请求
  2. 连接计时器
  3. 会话状态
  4. 连接数
  5. 捕获的首部及cookie
  6. “frontend”、"backend"及服务器名称
  7. 源地址和端口号等。

13、option logasap

option logasap
no option logasap
  1. 启用或禁用提前将HTTP请求记入日志
  2. 不能用于"backend"区段。
  3. 默认情况下，HTTP请求是在请求结束时进行记录以便能将其整体传输时长和字节数记入日志，由此，传较大的对象时，其记入日志的时长可能会略有延迟。"option logasap"参数能够在服务器发送complete首部时即时记录日志，只不过，此时将不记录整体传输时长和字节数。此情形下，捕获"Content-Length"响应首部来记录传输的字节数是一个较好选择。下面是一个例子。
listen http_proxy 0.0.0.0:80
mode http
option httplog
option logasap
log 172.16.100.9 local2

14、 option forwardfor

option forwardfor [ except <network> ] [ header <name> ] [ if-none ]

允许在发往服务器的请求首部中插入"X-Forwarded-For"首部。

14.1、 < network>

  1. 当指定时，源地址为匹配至此网络中的请求都禁用此功能。
  2. 可选参数

14.2、

  1. 可选参数
  2. 可使用一个自定义的首部，如"X-Client"来替代"X-Forwarded-For"。
  3. 有些独特的web服务器的确需要用于一个独特的首部。

14.3、if-none

仅在此首部不存在时才将其添加至请求报文问道中。

HAProxy工作于反向代理模式，其发往服务器的请求中的客户端IP均为HAProxy主机的地址而非真正客户端的地址，这会使得服务器端的日志信息记录不了真正的请求来源，"X-Forwarded-For"首部则可用于解决此问题。

HAProxy可以向每个发往服务器的请求上添加此首部，并以客户端IP为其value。

14.4、注意

HAProxy工作于隧道模式，其仅检查每一个连接的第一个请求，因此，仅第一个请求报文被附加此首部。如果想为每一个请求都附加此首部，请确保同时使用以下option

  1. “option httpclose”
  2. “option forceclose”
  3. "option http-server-close

14.5、案例。

frontend www
mode http
option forwardfor except 127.0.0.1

15、 errorfile

errorfile <code> <file>
  1. 在用户请求不存在的页面时，返回一个页面文件给客户端而非由haproxy生成的错误代码
  2. 可用于所有段中。

15.1、< code>

  1. 指定对HTTP的哪些状态码返回指定的页面
  2. 这里可用的状态码有200、400、403、408、500、502、503和504；

15.2、< file>

指定用于响应的页面文件；

15.3、案例

errorfile 400 /etc/haproxy/errorpages/400badreq.http
errorfile 403 /etc/haproxy/errorpages/403forbid.http
errorfile 503 /etc/haproxy/errorpages/503sorry.http

16、errorloc 和 errorloc302

errorloc <code> <url>
errorloc302 <code> <url>
  1. 请求错误时，返回一个HTTP重定向至某URL的信息
  2. 可用于所有配置段中。

16.1、< code>

  1. 指定对HTTP的哪些状态码返回指定的页面
  2. 这里可用的状态码有200、400、403、408、500、502、503和504；

16.2、< url>

  1. Location首部中指定的页面位置的具体路径，可以是在当前服务器上的页面的相对路径，也可以使用绝对路径
  2. 注意:如果URI自身错误时产生某特定状态码信息的话，有可能会导致循环定向；

16.3、注意

  1. 这两个关键字都会返回302状态码，这将使得客户端使用同样的HTTP方法获取指定的URL，对于非GET法的场景(如POST)来说会产生问题，因为返回客户的URL是不允许使用GET以外的其它方法的。如果的确有这种问题，可以使用errorloc303来返回303状态码给客户端。

17、errorloc303

errorloc303 <code> <url>
  1. 请求错误时，返回一个HTTP重定向至某URL的信息给客户端；
  2. 可用于所有配置段中。

17.1、< code>

  1. 指定对HTTP的哪些状态码返回指定的页面
  2. 这里可用的状态码有400、403、408、500、502、503和504；

17.2、

  1. Location首部中指定的页面位置的具体路径
  2. 可以是在当前服务器上的页面的相对路径，也可以使用绝对路径
  3. 注意：如果URI自身错误时产生某特定状态码信息的话，有可能会导致循环定向；

17.3、案例

backend webserver
server 172.16.100.6 172.16.100.6:80 check maxconn 3000 cookie srv01
server 172.16.100.7 172.16.100.7:80 check maxconn 3000 cookie srv02
errorloc 403 /etc/haproxy/errorpages/sorry.htm
errorloc303 503 /etc/haproxy/errorpages/sorry.htm