API Objects: L7 Farm

A farm is a container for real servers. The contained servers must have the same role and deliver the same service.

Farm attributes and options define the session behavior on the server side of the load balancer, such as how to check, dispatch connections, connect, forward data, and maintain sessions to real servers.

Farms are identified by a name; allowed characters include alpha-numeric, dot, dash, and underscore.

The available farm attributes are listed below:

balance

  • Definition: load balancing algorithm used to dispatch new connections on real servers
  • Type: enum
  • Default value: roundrobin
Value Description
roundrobin Each server is used in turn according to their weights.
least-connections The new connection is affected to the server with the lowest number of connections.
hash-uri The left part of the URI (before the question mark) is hashed and divided by the total weight of the running servers. The result designates which server will receive the request.
hash-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.

protocol

  • Definition: protocol analyzer used by load balancer. Some features of HTTP protocol require to have the analyzer on.
  • Type: enum
  • Default value: tcp
Value Description
tcp Layer4 protocol TCP analyzer
http Layer7 protocol HTTP analyzer

log

  • Definition: log farm events
  • Type: enum
  • Default value:logs are disabled
Value Description
enabled Logs are enabled

log format

This attribute is ignored if log is not set to enabled.
  • Definition: log format used if logs are enabled
  • Type: enum
  • Default value: basic log format
Value Description
tcp Advanced tcp log format
http Advanced http log format (fall back to tcp mode if protocol not set to http)
clf Use common log format defined by apache (fall back to tcp mode if protocol not set to http)

http-connection-mode

This attribute is ignored if protocol is not set to http.
  • Definition: http keepalive behavior
  • Type: enum
  • Default value: tunnel
Value Description
tunnel Connection header is left untouched and body is ignored.
passive-close Connection header is changed and body is ignored.
server-close Connection header set, body scanned, and client-side keep-alive is made possible regardless of server-side capabilities
forced-close Connection header set, body scanned, and connection closed.

http-pretend-keepalive

This attribute is ignored if protocol is not set to http.
  • Definition: HTTP keepalive announced to the server regardless keepalive status
  • Type: enum
  • Default value: disabled
Value Description
enabled keepalive announces are enabled
disabled keepalive announces are disabled

http-xff-header-insert

This attribute is ignored if protocol is not set to http.
  • Definition: Inserts an HTTP header field X-Forwarded-For whose value is the client IPaddress
  • Type: enum
  • Default value:disabled
Value Description
enabled X-Forwarded-For HTTP header field insertion is enabled

http-cookie

This attribute is ignored if protocol is not set to http.
  • Definition:
  • Type: enum
  • Default value:disabled
Value Description
enabled enable session cookie affinity (require http-cookie-name, http-cookie-mode and http-cookie-nocache)

http-cookie-name

This attribute is ignored if protocol is not set to http.
This attribute can be set and it is mandatory if http-cookie is set.
  • Definition: Name of the cookie used for server affinity. On incoming connections, the request is forwarded to the server whose http-cookie-id attribute matches the current cookie value.
  • Type: string
  • Default value: no cookie affinity

http-cookie-mode

This attribute is ignored if protocol is not set to http.
This attribute can be set and it is mandatory if http-cookie is set.
  • Definition: Cookie affinity analysis / insertion behavior
  • Type: enum
  • Default value: No cookie affinity
Value Description
passive Cookie is analyzed on incoming request to choose server but load balancer does not perform any insertion update or deletion on the Cookie or Set-Cookie headers
passive-silent Cookie is analyzed on incoming request to choose server and Set-Cookie is removed from response if not needed
reset Cookie is analyzed on incoming request to choose server, and Set-Cookie value is rewritten in response if present.
set Cookie is analyzed on incoming request to choose server, and Set-Cookie value is rewritten if present or inserted in response if needed.
set-silent Cookie is analyzed on incoming request to choose server, and Set-Cookie value is rewritten if present, inserted in response if needed, or removed if not needed.
session-prefix Cookie is analyzed on incoming request to choose server whose http-cookie-id prefix matches. Set-Cookie header is prefixed using http-cookie-id server attribute value in response.
insert-only Cookie is analyzed on incoming request to choose server, and Set-Cookie value is left untouched if rewritten and present, or inserted in response if needed.
insert-only-silent Cookie is analyzed on incoming request to choose server, and Set-Cookie value is left untouched if present, inserted in response if needed, or removed if not needed.
passive-session-prefix Cookie is analyzed on incoming request to choose server whose http-cookie-id prefix matches.

http-cookie-nocache

This attribute is ignored if protocol is not set to http.
This attribute can be set and it is mandatory if http-cookie is set.
  • Definition:no-cache flag on inserted cookie to prevent proxy from caching the cookie.
  • Type: enum
  • Default value: no cookie affinity
Value Description
enabled ” nocache” flag insertion on cookie is enabled
disabled “nocache” flag insertion on cookie is disabled

check-interval

  • Definition: Interval in seconds between two consecutive server health checks.
  • Type: integer
  • Default value: 2

check-rise

  • Definition: Count of consecutive successful health checks to consider server operational.
  • Type: integer
  • Default value: 2

check-fall

  • Definition: Count of consecutive unsuccessful health checks to consider server not operational.
  • Type: integer
  • Default value: 3

check-port

  • Definition: Destination TCP port used to perform health check. Set to 0 to use server port.
  • Type: integer
  • Default value: server port is used

check-timeout

  • Definition: additional health check timeout in seconds occurring when waiting for server’s response (after the connection is established). Set to 0 for set timeout to check-interval.
  • Type: integer
  • Default value: check timeout is set to check-interval

adv-check

  • Definition: Advanced check method
  • Type: enum
  • Default value: No advanced check. Performs a TCP connect.
Value Description
http Use an HTTP request health check for server testing. If HTTP status code 2xx or 3xx is returned, the check is successful (requires adv-check-http-method and adv-check-http-uri configured).
ldap LDAPv3 anonymous simple bind health check for server testing
mysql MySQL health checks
pgsql PostgreSQL health check using a StartupMessage
smtp send a SMTP HELO command and analyze server’s response
ssl-client-hello Use SSLv3 client ‘hello’ health checks for server testing. If an SSLv3 server hello is returned, check is successful
tcp Send/expect sequence of raw TCP

adv-check-http-uri

This attribute can be set and it is mandatory if adv-check is set to http.
  • Definition: Requested URI for http health check
  • Type: string
  • Default value: Advanced check not set to http

adv-check-http-method

This attribute can be set and it is mandatory if adv-check is set to http.
    Definition: HTTP request method used during http health check. If not set, HEAD is used.

  • Type: string
  • Default value: advanced check not set to http

adv-check-http-version

This attribute can be set and it is mandatory if adv-check is set to http.
  • Definition: HTTP request protocol version. If not set, HTTP/1.0 is used. Can be used to send a Host header field.
  • Type: string
  • Default value: advanced check not set to http

queued-timeout

This attribute can be set and it is mandatory if adv-check is set to http.
  • Definition: Maximum time to wait in the queue for a server’s connection slot to be available
  • Type: integer
  • Default value: no timeout
  • Particular value:0 means no timeout

connect-timeout

WARNING: It is important to set up this parameter. Otherwise, HAProxy may run out of connection slots.
  • Definition: Maximum time to wait for a server connection attempt to succeed.
  • Type: integer
  • Default value: no timeout
  • Particular value:0 means no timeout

connect-retries

  • Definition: Number of retries to perform when trying to establish a connection to a server
  • Type: integer
  • Default value: no retries
  • Values:0 means no retry

connect-failure-redispatch

Only used when connect-retries is greater than 1
  • Definition: Session redispatch to another server in case of connection failure. Last connect-retries will be performed on another server.
  • Type: enum
  • Default value: no redispatch
Value Description
enabled session redispatch is enabled
disabled session redispatch is disabled

connect-source

  • Definition: Force source address to use when connecting to servers.
  • Type: ip
  • Default value: Use the first address on load balancer’s outgoing interface
  • Particular value: Set to 0.0.0.0 to use first address available on load balancer’s outbound interface

connect-transparent

This attribute can be set and it is mandatory if connect-source is set.
  • Definition: Transparent proxy mode; the client source address is reused as the source address to connect to server.
  • Type: enum
  • Default value: Use the first address on load balancer’s outgoing interface
Value Description
enabled transparent proxy is enabled
disabled transparent proxy is disabled
Warning: In order to work, the server must use the load-balancer as its default gateway.

continuous-statistics

  • Definition: Continuous traffic statistics updates
  • Type: enum
  • Default value: disabled, meaning traffic counters are incremented once a session finishes.
Value Description
enabled enable continuous traffic statistics monitoring

server-inactivity-timeout

  • Definition:
  • Type: integer
  • Default value: no timeout
  • Particular value:0 for no timeout

stick-table

  • Definition: Create a stick table in the farm; expect type of data to be stored as an argument
  • Type: enum
  • Default value: none
Value Description
binary blocks of at most stick-table-keylen bytes of data
integer 32 bits integer
ip IPv4 addresses
ipv6 IPv6 addresses
string regular string, of at most stick-table-keylen characters

stick-table-expire

  • Definition: Maximum life time of data in a stick-table if unrefreshed
  • Type: integer
  • Default value: 32 charaters or bytes
WARNING: Be sure not to use stick-table-nopurge if no expiration delay (stick-table-expire) is specified.

stick-table-keylen

  • Definition: Maximum size of data when storing binary or string in the table
  • Type: integer
  • Default value: 32 charaters or bytes

stick-table-nopurge

  • Definition: Maximum life time of data in a stick-table if unrefreshed
  • Type: enum
  • Default value: 32 charaters or bytes
WARNING: Be sure not to use stick-table-nopurge if no expiration delay (stick-table-expire) is specified.

stick-table-peers

  • Definition: HAProxy’s peers section name (must be already configured). Used to synchronize data after a reload and between two ALOHA load-balancers.
  • Type: string
  • Default value: none

stick-table-size

  • Definition: The maximum number of entries that can be stored in the table.
  • Type: integer
  • Default value: none

tcpreq-inspect-delay

  • Definition: Set the maximum allowed time to wait for data from the client during content inspection.
  • Type: integer
  • Default value: 0

tcprsp-inspect-delay

  • Definition: Set the maximum allowed time to wait for data from the server during content inspection.
  • Type: integer
  • Default value: 0