Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 357 lines (290 sloc) 17.473 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356
\chapter{Server and default-server options}

The "server" and "default-server" keywords support a certain number of settings
which are all passed as arguments on the server line. The order in which those
arguments appear does not count, and they are all optional. Some of those
settings are single words (booleans) while others expect one or several values
after them. In this case, the values must immediately follow the setting name.
Except default-server, all those settings must be specified after the server's
address if they are used:

\begin{verbatim}
  server <name> <address>[:port] [settings ...]
  default-server [settings ...]
\end{verbatim}

The currently supported settings are the following ones.

\subsubsection[addr]{addr <ipv4|ipv6>}
  Using the "addr" parameter, it becomes possible to use a different IP address
  to send health-checks. On some servers, it may be desirable to dedicate an IP
  address to specific component able to perform complex tests which are more
  suitable to health-checks than the application. This parameter is ignored if
  the "check" parameter is not set. See also the "port" parameter.

  Supported in default-server: No

\subsubsection[backup]{backup}
  When "backup" is present on a server line, the server is only used in load
  balancing when all other non-backup servers are unavailable. Requests coming
  with a persistence cookie referencing the server will always be served
  though. By default, only the first operational backup server is used, unless
  the "allbackups" option is set in the backend. See also the "allbackups"
  option.

  Supported in default-server: No

\subsubsection[check]{check}
  This option enables health checks on the server. By default, a server is
  always considered available. If "check" is set, the server is available when
  accepting periodic TCP connections, to ensure that it is really able to serve
  requests. The default address and port to send the tests to are those of the
  server, and the default source is the same as the one defined in the
  backend. It is possible to change the address using the "addr" parameter, the
  port using the "port" parameter, the source address using the "source"
  address, and the interval and timers using the "inter", "rise" and "fall"
  parameters. The request method is define in the backend using the "httpchk",
  "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please
  refer to those options and parameters for more information.

  Supported in default-server: No

\subsubsection[cookie]{cookie <value>}
  The "cookie" parameter sets the cookie value assigned to the server to
  <value>. This value will be checked in incoming requests, and the first
  operational server possessing the same value will be selected. In return, in
  cookie insertion or rewrite modes, this value will be assigned to the cookie
  sent to the client. There is nothing wrong in having several servers sharing
  the same cookie value, and it is in fact somewhat common between normal and
  backup servers. See also the "cookie" keyword in backend section.

  Supported in default-server: No

\subsubsection[disabled]{disabled}
  The "disabled" keyword starts the server in the "disabled" state. That means
  that it is marked down in maintenance mode, and no connection other than the
  ones allowed by persist mode will reach it. It is very well suited to setup
  new servers, because normal traffic will never reach them, while it is still
  possible to test the service by making use of the force-persist mechanism.

  Supported in default-server: No

\subsubsection[error-limit]{error-limit <count>}
  If health observing is enabled, the "error-limit" parameter specifies the
  number of consecutive errors that triggers event selected by the "on-error"
  option. By default it is set to 10 consecutive errors.

  Supported in default-server: Yes

  See also the "check", "error-limit" and "on-error".

\subsubsection[fall]{fall <count>}
  The "fall" parameter states that a server will be considered as dead after
  <count> consecutive unsuccessful health checks. This value defaults to 3 if
  unspecified. See also the "check", "inter" and "rise" parameters.

  Supported in default-server: Yes

\subsubsection[id]{id <value>}
  Set a persistent ID for the server. This ID must be positive and unique for
  the proxy. An unused ID will automatically be assigned if unset. The first
  assigned value will be 1. This ID is currently only returned in statistics.

  Supported in default-server: No

\subsubsection[inter]{inter <delay>}
\subsubsection[fastinter]{fastinter <delay>}
\subsubsection[downinter]{downinter <delay>}
  The "inter" parameter sets the interval between two consecutive health checks
  to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms.
  It is also possible to use "fastinter" and "downinter" to optimize delays
  between checks depending on the server state:

  \vspace{3mm}
  \begin{tabular}{|p{6cm}|l|}
  \hline
  \head{Server state} & \head{Interval used} \\
  \hline
  UP 100\% (non-transitional) & "inter" \\
  \hline
  Transitionally UP (going down), Transitionally DOWN (going up), or yet unchecked. & "fastinter" if set, "inter" otherwise. \\
  \hline
  DOWN 100\% (non-transitional) & "downinter" if set, "inter" otherwise. \\
  \hline
  \end{tabular}
  \vspace{3mm}
   
  Just as with every other time-based parameter, they can be entered in any
  other explicit unit among \{ us, ms, s, m, h, d \}. The "inter" parameter also
  serves as a timeout for health checks sent to servers if "timeout check" is
  not set. In order to reduce "resonance" effects when multiple servers are
  hosted on the same hardware, the health-checks of all servers are started
  with a small time offset between them. It is also possible to add some random
  noise in the health checks interval using the global "spread-checks"
  keyword. This makes sense for instance when a lot of backends use the same
  servers.

  Supported in default-server: Yes

\subsubsection[maxconn]{maxconn <maxconn>}
  The "maxconn" parameter specifies the maximal number of concurrent
  connections that will be sent to this server. If the number of incoming
  concurrent requests goes higher than this value, they will be queued, waiting
  for a connection to be released. This parameter is very important as it can
  save fragile servers from going down under extreme loads. If a "minconn"
  parameter is specified, the limit becomes dynamic. The default value is "0"
  which means unlimited. See also the "minconn" and "maxqueue" parameters, and
  the backend's "fullconn" keyword.

  Supported in default-server: Yes

\subsubsection[maxqueue]{maxqueue <maxqueue>}
  The "maxqueue" parameter specifies the maximal number of connections which
  will wait in the queue for this server. If this limit is reached, next
  requests will be redispatched to other servers instead of indefinitely
  waiting to be served. This will break persistence but may allow people to
  quickly re-log in when the server they try to connect to is dying. The
  default value is "0" which means the queue is unlimited. See also the
  "maxconn" and "minconn" parameters.

  Supported in default-server: Yes

\subsubsection[minconn]{minconn <minconn>}
  When the "minconn" parameter is set, the maxconn limit becomes a dynamic
  limit following the backend's load. The server will always accept at least
  <minconn> connections, never more than <maxconn>, and the limit will be on
  the ramp between both values when the backend has less than <fullconn>
  concurrent connections. This makes it possible to limit the load on the
  server during normal loads, but push it further for important loads without
  overloading the server during exceptional loads. See also the "maxconn"
  and "maxqueue" parameters, as well as the "fullconn" backend keyword.

  Supported in default-server: Yes

\subsubsection[non-stick]{non-stick}
  Never add connections allocated to this sever to a stick-table.
  This may be used in conjunction with backup to ensure that
  stick-table persistence is disabled for backup servers.

\subsubsection[observe]{observe <mode>}
  This option enables health adjusting based on observing communication with
  the server. By default this functionality is disabled and enabling it also
  requires to enable health checks. There are two supported modes: "layer4" and
  "layer7". In layer4 mode, only successful/unsuccessful tcp connections are
  significant. In layer7, which is only allowed for http proxies, responses
  received from server are verified, like valid/wrong http code, unparsable
  headers, a timeout, etc. Valid status codes include 100 to 499, 501 and 505.

  Supported in default-server: No

  See also the "check", "on-error" and "error-limit".

\subsubsection[on-error]{on-error <mode>}
  Select what should happen when enough consecutive errors are detected.
  Currently, four modes are available:
  \begin{itemize}
  \item[-] fastinter: force fastinter
  \item[-] fail-check: simulate a failed check, also forces fastinter (default)
  \item[-] sudden-death: simulate a pre-fatal failed health check, one more failed
    check will mark a server down, forces fastinter
  \item[-] mark-down: mark the server immediately down and force fastinter
  \end{itemize}

  Supported in default-server: Yes

  See also the "check", "observe" and "error-limit".

\subsubsection[on-marked-down]{on-marked-down <action>}
  Modify what occurs when a server is marked down.
  Currently one action is available:
  \begin{itemize}
  \item[-] shutdown-sessions: Shutdown peer sessions. When this setting is enabled,
    all connections to the server are immediately terminated when the server
    goes down. It might be used if the health check detects more complex cases
    than a simple connection status, and long timeouts would cause the service
    to remain unresponsive for too long a time. For instance, a health check
    might detect that a database is stuck and that there's no chance to reuse
    existing connections anymore. Connections killed this way are logged with
    a 'D' termination code (for "Down").
  \end{itemize}

  Actions are disabled by default

  Supported in default-server: Yes

\subsubsection[on-marked-up]{on-marked-up <action>}
  Modify what occurs when a server is marked up.
  Currently one action is available:
  \begin{itemize}
  \item[-] shutdown-backup-sessions: Shutdown sessions on all backup servers. This is
    done only if the server is not in backup state and if it is not disabled
    (it must have an effective weight > 0). This can be used sometimes to force
    an active server to take all the traffic back after recovery when dealing
    with long sessions (eg: LDAP, SQL, ...). Doing this can cause more trouble
    than it tries to solve (eg: incomplete transactions), so use this feature
    with extreme care. Sessions killed because a server comes up are logged
    with an 'U' termination code (for "Up").
  \end{itemize}

  Actions are disabled by default

  Supported in default-server: Yes

\subsubsection[port]{port <port>}
  Using the "port" parameter, it becomes possible to use a different port to
  send health-checks. On some servers, it may be desirable to dedicate a port
  to a specific component able to perform complex tests which are more suitable
  to health-checks than the application. It is common to run a simple script in
  inetd for instance. This parameter is ignored if the "check" parameter is not
  set. See also the "addr" parameter.

  Supported in default-server: Yes

\subsubsection[redir]{redir <prefix>}
  The "redir" parameter enables the redirection mode for all GET and HEAD
  requests addressing this server. This means that instead of having HAProxy
  forward the request to the server, it will send an "HTTP 302" response with
  the "Location" header composed of this prefix immediately followed by the
  requested URI beginning at the leading '/' of the path component. That means
  that no trailing slash should be used after <prefix>. All invalid requests
  will be rejected, and all non-GET or HEAD requests will be normally served by
  the server. Note that since the response is completely forged, no header
  mangling nor cookie insertion is possible in the response. However, cookies in
  requests are still analysed, making this solution completely usable to direct
  users to a remote location in case of local disaster. Main use consists in
  increasing bandwidth for static servers by having the clients directly
  connect to them. \emph{Note:} never use a relative location here, it would cause a
  loop between the client and HAProxy!

  Example:
  
  \verb|server srv1 192.168.1.1:80 redir http://image1.mydomain.com check|

  Supported in default-server: No

\subsubsection[rise]{rise <count>}
  The "rise" parameter states that a server will be considered as operational
  after <count> consecutive successful health checks. This value defaults to 2
  if unspecified. See also the "check", "inter" and "fall" parameters.

  Supported in default-server: Yes

\subsubsection[send-proxy]{send-proxy}
  The "send-proxy" parameter enforces use of the PROXY protocol over any
  connection established to this server. The PROXY protocol informs the other
  end about the layer 3/4 addresses of the incoming connection, so that it can
  know the client's address or the public address it accessed to, whatever the
  upper layer protocol. For connections accepted by an "accept-proxy" listener,
  the advertised address will be used. Only TCPv4 and TCPv6 address families
  are supported. Other families such as Unix sockets, will report an UNKNOWN
  family. Servers using this option can fully be chained to another instance of
  haproxy listening with an "accept-proxy" setting. This setting must not be
  used if the server isn't aware of the protocol. See also the "accept-proxy"
  option of the "bind" keyword.

  Supported in default-server: No

\subsubsection[slowstart]{slowstart <start\_time\_in\_ms>}
  The "slowstart" parameter for a server accepts a value in milliseconds which
  indicates after how long a server which has just come back up will run at
  full speed. Just as with every other time-based parameter, it can be entered
  in any other explicit unit among \{ us, ms, s, m, h, d \}. The speed grows
  linearly from 0 to 100\% during this time. The limitation applies to two
  parameters:

  \begin{itemize}
  \item[-] maxconn: the number of connections accepted by the server will grow from 1
    to 100\% of the usual dynamic limit defined by (minconn,maxconn,fullconn).

  \item[-] weight: when the backend uses a dynamic weighted algorithm, the weight
    grows linearly from 1 to 100\%. In this case, the weight is updated at every
    health-check. For this reason, it is important that the "inter" parameter
    is smaller than the "slowstart", in order to maximize the number of steps.
  \end{itemize}

  The slowstart never applies when haproxy starts, otherwise it would cause
  trouble to running servers. It only applies when a server has been previously
  seen as failed.

  Supported in default-server: Yes

\subsubsection[source]{
source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
}
\subsubsection*{
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr\_ip(<hdr>[,<occ>]) } ]
}
\subsubsection*{
source <addr>[:<pl>[-<ph>]] [interface <name>] ...
}

  The "source" parameter sets the source address which will be used when
  connecting to the server. It follows the exact same parameters and principle
  as the backend "source" keyword, except that it only applies to the server
  referencing it. Please consult the "source" keyword for details.

  Additionally, the "source" statement on a server line allows one to specify a
  source port range by indicating the lower and higher bounds delimited by a
  dash ('\verb|-|'). Some operating systems might require a valid IP address when a
  source port range is specified. It is permitted to have the same IP/range for
  several servers. Doing so makes it possible to bypass the maximum of 64k
  total concurrent connections. The limit will then reach 64k connections per
  server.

  Supported in default-server: No

\subsubsection[track]{track [<proxy>/]<server>}
  This option enables ability to set the current state of the server by
  tracking another one. Only a server with checks enabled can be tracked
  so it is not possible for example to track a server that tracks another
  one. If <proxy> is omitted the current one is used. If disable-on-404 is
  used, it has to be enabled on both proxies.

  Supported in default-server: No

\subsubsection[weight]{weight <weight>}
  The "weight" parameter is used to adjust the server's weight relative to
  other servers. All servers will receive a load proportional to their weight
  relative to the sum of all weights, so the higher the weight, the higher the
  load. The default weight is 1, and the maximal value is 256. A value of 0
  means the server will not participate in load-balancing but will still accept
  persistent connections. If this parameter is used to distribute the load
  according to server's capacity, it is recommended to start with values which
  can both grow and shrink, for instance between 10 and 100 to leave enough
  room above and below for later adjustments.

  Supported in default-server: Yes
Something went wrong with that request. Please try again.