HAProxy Configuration: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(52 intermediate revisions by the same user not shown)
Line 7: Line 7:
If [[HAProxy Installation#Overview|installed with yum]], the default configuration file is deployed in <tt>/etc/haproxy/haproxy.cfg</tt> and the systemd configuration file in <tt>/etc/sysconfig/haproxy</tt>.
If [[HAProxy Installation#Overview|installed with yum]], the default configuration file is deployed in <tt>/etc/haproxy/haproxy.cfg</tt> and the systemd configuration file in <tt>/etc/sysconfig/haproxy</tt>.


=Configure HAProxy to Log into a File=
HAProxy's configuration process involves 3 sources of configuration parameters:
# Arguments from the command line, which always take precedence over file configuration.
# The [[#global|global]] section, which sets process-wide parameters.
# The proxies sections, which are [[#defaults|defaults]], [[#listen|listen]], [[#frontend|frontend]] and [[#backend|backend]].
 
=TODO=


<font color=red>
<font color=red>
Instructions in /etc/haproxy/haproxy.cfg. Follow and verify.
HAProxy and OpenShift: HAProxy on lb.local. It seems that if none of the masters are not available when HAProxy starts, it fails and then it does not retry. How to I configure it to retry for each request? Maybe Ansible knows how to do that?
</font>
</font>
=Example=
The following example proxies HTTPS connections by passing them directly to the backend.
<pre>
#---------------------------------------------------------------------
# Global settings
#---------------------------------------------------------------------
global
    maxconn    20000
    log        127.0.0.1:514 local2
    chroot      /var/lib/haproxy
    pidfile    /var/run/haproxy.pid
    user        haproxy
    group      haproxy
    daemon
    # turn on stats unix socket
    stats socket /var/lib/haproxy/stats
#---------------------------------------------------------------------
# common defaults that all the 'listen' and 'backend' sections will
# use if not designated in their block
#---------------------------------------------------------------------
defaults
    mode                    http
    log                    global
    option                  httplog
    option                  dontlognull
#    option http-server-close
#    option forwardfor      except 127.0.0.0/8
    option                  redispatch
    retries                3
    timeout http-request    10s
    timeout queue          1m
    timeout connect        10s
    timeout client          300s
    timeout server          300s
    timeout http-keep-alive 10s
    timeout check          10s
    maxconn                20000
listen stats :9000
    mode http
    stats enable
    stats uri /
frontend  atomic-openshift-api
    bind *:443
    mode tcp
    option tcplog
    default_backend atomic-openshift-api
backend atomic-openshift-api
    mode tcp
    balance source
    server      master1 192.168.122.13:443 check
    server      master2 192.168.122.14:443 check
    server      master3 192.168.122.15:443 check
</pre>
=Dependency on Other Services=
Under some circumstances, HAProxy need other services to start before it starts, so it can rely on them. For example, if a local DNS server resolves the names referred from HAProxy configuration file, the named service must start before HAProxy. This is configured in the HAProxy's unit file /usr/lib/systemd/system/haproxy.service:
Requires=named.service
After=syslog.target network.target named.service
More details: [[Systemd_Declaring_a_Service_Dependency|Declaring a Dependency on a Service]].
=Logging Configuration=
==Logging Destination Configuration==
HAProxy logging concepts:
{{Internal|HAProxy_Concepts#Logging|HAProxy Concepts - Logging}}
Logging configuration consists of the following steps:
Add the following to the "global" section of the configuration file:
log 127.0.0.1:514 local2
and then add the following to each "defaults" section or to each frontend and backend section:
log global
Then make sure the local syslogd does listen to the UDP traffic. For details on how to do this for rsyslogd, see:
{{Internal|Linux_Logging_Configuration#Enable_rsyslogd_to_Listen_for_UDP_Traffic|Enable rsyslogd to Listen for UDP Traffic}}
===Configure HAProxy to Log into a File===
Assuming that logging was configured as described in the [[HAProxy_Configuration#Logging_Configuration|previous section]], configure local2 events to go to the /var/log/haproxy.log  file. Add the following line in /etc/rsyslog.conf:
local2.*  /var/log/haproxy.log
==Log Format==
HAProxy comes with two pre-defined log formats:
1. HTTP log format:
%ci:%cp\ [%tr]\ %ft\ %b/%s\ %TR/%Tw/%Tc/%Tr/%Ta\ %ST\ %B\ %CC\ %CS\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r
2. TCP log format:
%ci:%cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq
These can be requested in the corresponding section ("listen", "fronted", etc.) with the following declaration:
...
frontend
  ...
  option tcplog|httplog
The log format can be customized, by declaring it in "defaults" section or in the appropriate "listen" or "frontend"
log-format          %Ci:%Cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq
'''Important''': When declaring a custom log format, spaces must be escaped ('\ '), because log-format expects just one argument.
'''Also important''': When using a custom log format, options "tcplog" or "httplog" in the "defaults" or "frontend" sections must be commented out, otherwise they take precedence and the custom format does not surface.


=SSL Configuration=
=SSL Configuration=


{{Internal|HAProxy SSL Pass-Through Configuration|HAProxy SSL Pass-Through Configuration}}
* [[HAProxy SSL Pass-Through Configuration|HAProxy SSL Pass-Through Configuration]]
* [[OpenShift_3.6_Installation#Configure_Application_Proxying|HTTP/HTTPS HAProxy Configuration Example - OpenShift 3.6 Installation]]


=Configuration=
=Subjects=
 
* [[HAProxy Routing Among Two Classes of Backends Based on Request Structure]]
 
=Configuration Reference=


==Options==
==Options==
Line 32: Line 165:


==global==
==global==
The "global" section sets process-wide parameters.


==defaults==
==defaults==
This is one of four "proxy" sections ([[#defaults|defaults]], [[#listen|listen]], [[#frontend|frontend]], [[#backend|backend]]). It sets default parameters for all other sections following its declaration. These default parameters are overwritten by the subsequent "defaults" sections, if present.


===mode===
===mode===
Line 44: Line 181:


Used to pass secure connections off to a backend server without encrypting it.
Used to pass secure connections off to a backend server without encrypting it.
===balance===
{{External|http://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4-balance}}
Specifies the algorithm used to select a server when doing load balancing. This only applies when no persistence information is available, or when a connection is redispatched to another server. Possible values:
====roundrobin====
Each server is used in turns, according to their weights. This is the smoothest and fairest algorithm when the server's processing time remains equally distributed. This algorithm is dynamic, which means that server weights may be adjusted on the fly for slow starts for instance. It is limited by design to 4095 active servers per backend.
====source====
The source IP address is hashed and divided by the total weight of the running servers to designate which server will receive the request. This ensures that the same client IP address will always reach the same server as long as no server goes down or up. If the hash result changes due to the number of running servers changing, many clients will be directed to a different server. This algorithm is generally used in TCP mode where no cookie may be inserted. It may also be used on the Internet to provide a best-effort stickiness to clients which refuse session cookies. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type".
====static-rr====
====leastconn====
====first====
====uri====
====url_param====
====hdr(name)====
====rdp-cookie, rdp-cookie(name)====
==listen==
This is one of four "proxy" sections ([[#defaults|defaults]], [[#listen|listen]], [[#frontend|frontend]], [[#backend|backend]]). It defines a complete proxy with its fronted and backend parts combined in one section. It is generally useful for TCP-only traffic.
==frontend==
This is one of four "proxy" sections ([[#defaults|defaults]], [[#listen|listen]], [[#frontend|frontend]], [[#backend|backend]]). It describes a set of listening sockets accepting client connections.
===bind===
{{External|http://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4-bind}}
frontend ''frontend-1''
    bind 1.2.3.4:80,1.2.3.4:443
==backend==
This is one of four "proxy" sections ([[#defaults|defaults]], [[#listen|listen]], [[#frontend|frontend]], [[#backend|backend]]). It describes a set of servers to which the proxy will connect to forward incoming connections.

Latest revision as of 20:34, 21 January 2018

Internal

Overview

If installed with yum, the default configuration file is deployed in /etc/haproxy/haproxy.cfg and the systemd configuration file in /etc/sysconfig/haproxy.

HAProxy's configuration process involves 3 sources of configuration parameters:

  1. Arguments from the command line, which always take precedence over file configuration.
  2. The global section, which sets process-wide parameters.
  3. The proxies sections, which are defaults, listen, frontend and backend.

TODO

HAProxy and OpenShift: HAProxy on lb.local. It seems that if none of the masters are not available when HAProxy starts, it fails and then it does not retry. How to I configure it to retry for each request? Maybe Ansible knows how to do that?

Example

The following example proxies HTTPS connections by passing them directly to the backend.

#---------------------------------------------------------------------
# Global settings
#---------------------------------------------------------------------
global
    maxconn     20000
    log         127.0.0.1:514 local2
    chroot      /var/lib/haproxy
    pidfile     /var/run/haproxy.pid
    user        haproxy
    group       haproxy
    daemon

    # turn on stats unix socket
    stats socket /var/lib/haproxy/stats

#---------------------------------------------------------------------
# common defaults that all the 'listen' and 'backend' sections will
# use if not designated in their block
#---------------------------------------------------------------------
defaults
    mode                    http
    log                     global
    option                  httplog
    option                  dontlognull
#    option http-server-close
#    option forwardfor       except 127.0.0.0/8
    option                  redispatch
    retries                 3
    timeout http-request    10s
    timeout queue           1m
    timeout connect         10s
    timeout client          300s
    timeout server          300s
    timeout http-keep-alive 10s
    timeout check           10s
    maxconn                 20000

listen stats :9000
    mode http
    stats enable
    stats uri /

frontend  atomic-openshift-api
    bind *:443
    mode tcp
    option tcplog
    default_backend atomic-openshift-api

backend atomic-openshift-api
    mode tcp
    balance source
    server      master1 192.168.122.13:443 check
    server      master2 192.168.122.14:443 check
    server      master3 192.168.122.15:443 check

Dependency on Other Services

Under some circumstances, HAProxy need other services to start before it starts, so it can rely on them. For example, if a local DNS server resolves the names referred from HAProxy configuration file, the named service must start before HAProxy. This is configured in the HAProxy's unit file /usr/lib/systemd/system/haproxy.service:

Requires=named.service
After=syslog.target network.target named.service

More details: Declaring a Dependency on a Service.

Logging Configuration

Logging Destination Configuration

HAProxy logging concepts:

HAProxy Concepts - Logging

Logging configuration consists of the following steps:

Add the following to the "global" section of the configuration file:

log 127.0.0.1:514 local2

and then add the following to each "defaults" section or to each frontend and backend section:

log global

Then make sure the local syslogd does listen to the UDP traffic. For details on how to do this for rsyslogd, see:

Enable rsyslogd to Listen for UDP Traffic

Configure HAProxy to Log into a File

Assuming that logging was configured as described in the previous section, configure local2 events to go to the /var/log/haproxy.log file. Add the following line in /etc/rsyslog.conf:

local2.*  /var/log/haproxy.log

Log Format

HAProxy comes with two pre-defined log formats:

1. HTTP log format:

%ci:%cp\ [%tr]\ %ft\ %b/%s\ %TR/%Tw/%Tc/%Tr/%Ta\ %ST\ %B\ %CC\ %CS\ %tsc\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq\ %hr\ %hs\ %{+Q}r

2. TCP log format:

%ci:%cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq

These can be requested in the corresponding section ("listen", "fronted", etc.) with the following declaration:

...
frontend 
  ...
  option tcplog|httplog

The log format can be customized, by declaring it in "defaults" section or in the appropriate "listen" or "frontend"

log-format          %Ci:%Cp\ [%t]\ %ft\ %b/%s\ %Tw/%Tc/%Tt\ %B\ %ts\ %ac/%fc/%bc/%sc/%rc\ %sq/%bq

Important: When declaring a custom log format, spaces must be escaped ('\ '), because log-format expects just one argument.

Also important: When using a custom log format, options "tcplog" or "httplog" in the "defaults" or "frontend" sections must be commented out, otherwise they take precedence and the custom format does not surface.

SSL Configuration

Subjects

Configuration Reference

Options

httplog

tcplog

Logging is set to tcp instead of the default http.

ssl-hello-chk

A health check that verifies the the connection and its ability to handle SSL (SSLv3 specifically) connections.

global

The "global" section sets process-wide parameters.

defaults

This is one of four "proxy" sections (defaults, listen, frontend, backend). It sets default parameters for all other sections following its declaration. These default parameters are overwritten by the subsequent "defaults" sections, if present.

mode

Possible values:

http

tcp

Used to pass secure connections off to a backend server without encrypting it.

balance

http://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4-balance

Specifies the algorithm used to select a server when doing load balancing. This only applies when no persistence information is available, or when a connection is redispatched to another server. Possible values:

roundrobin

Each server is used in turns, according to their weights. This is the smoothest and fairest algorithm when the server's processing time remains equally distributed. This algorithm is dynamic, which means that server weights may be adjusted on the fly for slow starts for instance. It is limited by design to 4095 active servers per backend.

source

The source IP address is hashed and divided by the total weight of the running servers to designate which server will receive the request. This ensures that the same client IP address will always reach the same server as long as no server goes down or up. If the hash result changes due to the number of running servers changing, many clients will be directed to a different server. This algorithm is generally used in TCP mode where no cookie may be inserted. It may also be used on the Internet to provide a best-effort stickiness to clients which refuse session cookies. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type".

static-rr

leastconn

first

uri

url_param

hdr(name)

rdp-cookie, rdp-cookie(name)

listen

This is one of four "proxy" sections (defaults, listen, frontend, backend). It defines a complete proxy with its fronted and backend parts combined in one section. It is generally useful for TCP-only traffic.

frontend

This is one of four "proxy" sections (defaults, listen, frontend, backend). It describes a set of listening sockets accepting client connections.

bind

http://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4-bind
frontend frontend-1
    bind 1.2.3.4:80,1.2.3.4:443

backend

This is one of four "proxy" sections (defaults, listen, frontend, backend). It describes a set of servers to which the proxy will connect to forward incoming connections.