Searching ALOHA 12.0
Fetching Data Samples
Fetching Data Samples
HAProxy can extract data from traffic streams, client or server information, tables, environmental information, etc. The action of extracting data is called fetching a sample. Once retrieved, these samples can be used for various purposes such as logging or routing traffic to different back ends based on the host header.
HAProxy can fetch samples from the following locations, which also correspond to a specific moment in the processing streams:
Its own internal states, available at any time:
Layer 4, available once the TCP connection is established
Layer 5, available once all the protocol handshakes are finished
Layer 6, available once some data is available in buffers
Layer 7, available once HAProxy has validated the data is conform to HTTP
Each sample from a fetch can have one of the following value type:
boolean
integer
IP
string
binary
Fetching data samples from internal states
The following table shows the type of data content that a fetch operation returns from HAProxy's internal states:
Fetch name | Type | Description |
---|---|---|
| boolean | Always returns the boolean value false |
| boolean | Always returns the boolean value true |
| integer | Returns the total number of queued connections on |
| integer | Returns the number of currently established connections on |
| integer | Returns the sessions creation rate on |
| integer | Returns the number of connection slots still available in |
| integer | Returns the current date as the epoch (number of seconds since 01/01/1970). If |
| string | Returns a string containing the value of environment variable |
| integer | Returns the number of currently established connections on <frontend>, possibly including the connection being evaluated |
| integer | Returns an integer value corresponding to the sessions creation rate on <frontend>, in number of new sessions per second. |
| integer | Returns the number of HAProxy processes that were started. |
| integer | Returns the number of usable servers in |
| integer | Returns the position of the current process, between 1 and nbproc |
| integer | Returns the total number of queued connections on |
| integer | Returns a random integer within 0 to |
| integer | Returns the number of currently established connections on |
| boolean | Returns true when |
| integer | Returns the sessions creation rate on |
| boolean | Returns true if the process calling the function is currently stopping |
| integer | Returns the total number of available entries in the stick-table |
| integer | Returns the number of entries currently in use in the stick-table |
Note
An argument is optional if it is inside brackets '[' and ']'. A local value is assumed for the front end and back end.
Fetching data samples from Layer 4
The following fetches get content from the transport layer in HAProxy. It is the closest point to the TCP connection. No content is yet available at this time.
Fetch name | Type | Description |
---|---|---|
| integer | Returns the current back end's id |
| ip | IPv4 Destination on the client side connection |
| integer | Returns the number of currently established connections on the same socket including the one being evaluated |
| integer | Returns the destination TCP port of the client side connection, which is the port the client connected to |
| integer | Returns the current front end's id |
| integer | Returns the average client-to-server byte rate from the currently tracked counters, measured in number of bytes over the period of time configured in the table. |
| integer | Returns the average server-to-client bytes rate from the currently tracked counters, measured in amount of bytes over the period configured in the table |
| integer | Clears the first General Purpose Counter associated to the currently tracked counters, and returns its previous value. |
| integer | Returns the cumulative number of incoming connections from currently tracked counters. |
| integer | Returns the current amount of concurrent connections tracking the same tracked counters. |
| integer | Returns the average connection rate from the currently tracked counters, measured in number of connections over the period configured in the table. |
| integer | Returns the value of the first General Purpose Counter associated to the currently tracked counters. |
| integer | Returns the average increment rate of the first General Purpose Counter associated to the currently tracked counters. It reports the frequency which the gpc0 counter was incremented over the configured period. |
| integer | Returns the cumulative number of HTTP errors from the currently tracked counters. |
| integer | Returns the average rate of HTTP errors from the currently tracked counters, measured in number of errors over the period configured in the table. This includes both the request errors and 4xx error responses. |
| integer | Returns the cumulative number of HTTP requests from the currently tracked counters. This includes every started request, whether it's valid or not. |
| integer | Returns the average rate of HTTP requests from the currently tracked counters, measured in number of requests over the period configured in the table. |
| integer | Increments the first General Purpose Counter associated to the currently tracked counters, and returns its new value. |
| integer | Returns the total amount of client-to-server data from the currently tracked counters, measured in kilobytes. The test is currently performed over 32-bit integers, which limits values to 4 terabytes. |
| integer | Returns the total amount of server-to-client data from the currently tracked counters, measured in kilobytes. The test is currently performed on 32-bit integers, which limits values to 4 terabytes. |
| integer | Returns the cumulative number of incoming connections that were transformed into sessions, which means that they were accepted by a tcp-request connection rule. |
| integer | Returns the average session rate from the currently tracked counters, measured in number of sessions over the period configured in the table. |
| boolean | Returns true if the designated session counter is currently being tracked by the current session. |
| integer | Returns the current number of concurrent connections tracking the same tracked counters. This number is automatically incremented when tracking begins and decremented when tracking stops. |
| integer | Returns the current listening socket's ID. |
| ip | This is the source IPv4 address of the client of the session. |
| integer | Returns the average bytes rate from the incoming connection's source address in |
| integer | Returns the average bytes rate to the incoming connection's source address in |
| integer | Clears the first General Purpose Counter associated to the incoming connection's source address in |
| integer | Returns the cumulative number of connections initiated from the current incoming connection's source address in |
| integer | Returns the current number of concurrent connections initiated from the current incoming connection's source address in |
| integer | Returns the average connection rate from the incoming connection's source address in |
| integer | Returns the value of the first General Purpose Counter associated to the incoming connection's source address in |
| integer | Returns the average increment rate of the first General Purpose Counter associated to the incoming connection's source address in |
| integer | Returns the cumulative number of HTTP errors from the incoming connection's source address in |
| integer | Returns the average rate of HTTP errors from the incoming connection's source address in |
| integer | Returns the cumulative number of HTTP requests from the incoming connection's source address in |
| integer | Returns the average rate of HTTP requests from the incoming connection's source address in |
| integer | Increments the first General Purpose Counter associated to the incoming connection's source address in |
| integer | Returns the total amount of data received from the incoming connection's source address in |
| integer | Returns the total amount of data sent to the incoming connection's source address in |
| integer | Returns the TCP source port from the connection on the client side, which is the port where the client connected from. |
| integer | Returns the cumulative number of connections initiated from the incoming connection's source IPv4 address in |
| integer | Returns the average session rate from the incoming connection's source address in |
| integer | Creates or updates the entry associated to the incoming connection's source address in the |
| integer | Returns the server's ID when processing the response |
Fetching Data Samples from Layer 5
The layer 5 usually describes the session layer which, in HAProxy, is closest to the session after all connection handshakes are finished, but when no content is yet made available.
Fetch name | Type | Description |
---|---|---|
| boolean | Returns true when the connection to the server was made over a SSL/TLS transport layer and is locally deciphered. This means the outgoing connection was made to a server where the SSLoption was configured. |
| integer | Returns the symmetric cipher key size supported in bits when the connection to the server was made over an SSL/TLS transport layer. |
| string | Returns the name of the cipher used when the connection to the was made using SSL/TLS. |
| string | Returns the name of the protocol used when the connection to the server was made over SSL/TLS. |
| binary | When the server side connection is made over SSL/TLS, returns the TLS unique ID as defined in RFC5929 section 3. The unique id can be encoded to base64 using the converter base64. |
| binary | Returns the SSL Session ID of the server side connection when the outgoing connection was made over SSL/TLS transport layer. |
| integer | Returns the symmetric cipher key size used in bits when the server side connection was made over SSL/TLS. |
| integer | When the client side connection was made over a SSL/TLS, returns the ID of the first error detected during verification of the client certificate at depth > 0, or 0 if no error was encountered. Refer to your SSL library's documentation to find the exhaustive list of error codes. |
| integer | When the incoming connection was made over a SSL/TLS, returns the depth in the CA chain of the first error detected during the verification of the client certificate. If no error is encountered, 0 is returned. |
| binary | Returns the DER formatted certificate presented by the client when the client side connection was made over SSL/TLS. |
| integer | When the client side connection is made over SSL/TLS, returns the ID of the first error detected during verification at depth 0, or 0 if no error was encountered during this verification process. Refer to your SSL library's documentation to find the exhaustive list of error codes. |
| string | When the incoming connection is made over a SSL/TLS, returns the full distinguished name of the issuer of the certificate presented by the client when no <entry> is specified, or the value of the first given entry found from the beginning of the DN. If a positive/negative occurrence number is specified as the optional second argument, it returns the value of the nth given entry value from the beginning/end of the DN. For instance, ssl_c_i_dn(OU,2) the second organization unit, and ssl_c_i_dn(CN) retrieves the common name. |
| string | Returns the name of the algorithm used to generate the key of the certificate presented by the client when the client side connection was made over SSL/TLS. |
| string | Returns the end date presented by the client as a formatted string YYMMDDhhmmss[Z] when the incoming connection is made over SSL/TLS. |
| string | Returns the start date presented by the client as a formatted string YYMMDDhhmmss[Z] when the incoming connection is made over SSL/TLS. |
| string | When the incoming connection is made over SSL/TLS, returns the full distinguished name of the subject of the certificate presented by the client when no <entry> is specified, or the value of the first given entry found from the beginning of the DN. If a positive/negative occurrence number is specified as the optional second argument, it returns the value of the nth given entry value from the beginning/end of the DN. For instance, ssl_c_s_dn(OU,2) * - the second organization unit, and ssl_c_s_dn(CN) retrieves the common name. |
| binary | Returns the serial of the certificate presented by the client when the client side connection is made over SSL/TLS. |
| binary | Returns the SHA-1 fingerprint of the certificate presented by the client when the client side connection is made over SSL/TLS. |
| string | Returns the name of the algorithm used to sign the certificate presented by the client when the incoming connection is made over an SSL/TLS. |
| boolean | Returns true if current SSL session uses a client certificate even if current connection uses SSL session resumption. See also ssl_fc_has_crt. |
| integer | Returns the verify result error ID when the incoming connection is made over SSL/TLS, otherwise zero if no error is encountered. Refer to your SSL library's documentation for an exhaustive list of error codes. |
| integer | Returns the version of the certificate presented by the client when the client side connection is made over SSL/TLS. |
| binary | Returns the DER formatted certificate presented by the front end when the client side connection is made over SSL/TLS. |
| string | When the incoming connection is made over an SSL/TLS, returns the full distinguished name of the issuer of the certificate presented by the front end when no <entry> is specified, or the value of the first given entry found from the beginning of the DN. If a positive/negative occurrence number is specified as the optional second argument, it returns the value of the nth given entry value from the beginning/end of the DN. For instance, ssl_f_i_dn(OU,2) the second organization unit, and ssl_f_i_dn(CN) retrieves the common name. |
| string | Returns the name of the algorithm used to generate the key of the certificate presented by the front end when the incoming connection is made over SSL/TLS. |
| string | Returns the end date presented by the front end as a formatted string YYMMDDhhmmss[Z] when the incoming connection is made over an SSL/TLS. |
| string | Returns the start date presented by the front end as a formatted string YYMMDDhhmmss[Z] when the incoming connection is made over SSL/TLS. |
| string | When the incoming connection is made over SSL/TLS, returns the full distinguished name of the subject of the certificate presented by the front end when no <entry> is specified, or the value of the first given entry found from the beginning of the DN. If a positive/negative occurrence number is specified as the optional second argument, it returns the value of the nth given entry value from the beginning/end of the DN. For instance, ssl_f_s_dn(OU,2) the second organization unit, and ssl_f_s_dn(CN) retrieves the common name. |
| binary | Returns the serial of the certificate presented by the front end when the client side connection is made over SSL/TLS. |
| binary | Returns the SHA-1 fingerprint of the certificate presented by the front end when the client side connection is made over SSL/TLS. |
| string | Returns the name of the algorithm used to sign the certificate presented by the front end when the incoming connection is made over SSL/TLS. |
| integer | Returns the version of the certificate presented by the front end when the client side connection is made over SSL/TLS. |
| boolean | Returns true when the front connection is made over an SSL/TLS transport layer and is locally deciphered. This means it has hit a socket declared with a bind line having the ssl option. |
| integer | Returns the symmetric cipher key size supported in bits when the client side connection is made over SSL/TLS. |
| string | This extracts the Application Layer Protocol Negotiation field from a client side connection made over TLS and locally deciphered by HAProxy. The result is a string containing the protocol name advertised by the client. Note that the TLS ALPN extension is not advertised unless the alpn keyword on the bindline specifies a protocol list. Also, nothing forces the client to pick a protocol from this list, any other one may be requested. The TLS ALPN extension is meant to replace the TLS NPN extension. See also ssl_fc_npn. |
| string | Returns the name of the cipher used when the client side connection is made over a SSL/TLS |
| boolean | Returns true if a client certificate is present over a client side connection made using SSL/TLS. Useful if verifystatement is set to optional. Note: on SSL session resumption with Session ID or TLS ticket, client certificate is not present in the current connection but may be retrieved from the cache or the ticket. Prefer using ssl_c_used if you want to check if current SSL session uses a client certificate. |
| boolean | This checks for the presence of a Server Name Indication TLS extension (SNI) in the client side connection which is made over a SSL/TLS. Returns true when the client side connection presents a TLS SNI field. |
| boolean | Returns true when the SSL/TLS session has been resumed through the use of SSL session cache or TLS tickets |
| string | This extracts the Next Protocol Negotiation field from a client side connection made over a TLS connection and locally deciphered by haproxy. The result is a string containing the protocol name advertised by the client. Note that the TLS NPN extension is not advertised unless the npnkeyword on the bindline specifies a protocol list. |
| string | Returns the name of the used protocol when the client side connection was made over SSL/TLS. |
| binary | When the client side connection is made over an SSL/TLS, returns the TLS unique ID as defined in RFC5929 section 3. The unique id can be encoded to base64 using the converter base64. |
| binary | Returns the SSL ID of the front connection when the client side connection is made over SSL/TLS. It is useful to stick a given client to a server. It is important to note that some browsers refresh their session ID every few minutes. |
| string | This extracts the Server Name Indication TLS extension (SNI) field from a client side connection made over SSL/TLS and locally deciphered by HAProxy. The result (when present) typically is a string matching the HTTPS host name (253 characters or fewer). |
| integer | Returns the symmetric cipher key size used in bits when the client side connection was made over SSL/TLS. |
Fetching Data Samples from Layer 6
Fetching data samples from buffer content is different from the sample fetches available at layers 4 and 5, because the sampled data is ephemeral. This data can only be used when it is available and is lost when it is forwarded.
Fetch name | Type | Description |
---|---|---|
| integer | Returns the number of bytes present in the request buffer. |
| binary | Extracts a binary block of |
| binary | Extracts a binary block whose size is specified at |
| boolean | Returns true when data in the request buffer looks like HTTP and correctly parses as such. It is the same parser as the common HTTP request parser which is used so there should be no surprises. The test does not match until the request is complete, failed, or timed out. |
| string | When the request buffer looks like RDP protocol, this extracts the RDP cookie |
| integer | Tries to parse the request buffer as RDP protocol, then returns an integer corresponding to the number of RDP cookies found. If an optional cookie name is passed, only cookies matching this name are considered. |
| boolean | Returns true when a client has sent the Supported Elliptic Curves TLS Extension as defined in RFC4492 in the SSL ClientHello message. This can be used to present ECC compatible clients with EC certificate and to use RSA for all others, on the same IP address. |
| string | Returns an integer value containing the type of SSL hello message found in the response buffer if the buffer contains data that parses as a complete SSL (v3 or superior) hello message. Note that this only applies to raw contents found in the response buffer and not to contents deciphered via an SSL data layer, so this cannot work with server lines having the SSL option. |
| integer | Returns an integer value containing the version of the SSL/TLS protocol of a stream present in the request buffer. Both SSLv2 hello messages and SSLv3 messages are supported. TLSv1 is announced as SSL version 3.1. The value is composed of the major version multiplied by 65536, added to the minor version. Note that this only applies to raw contents found in the request buffer and not to contents deciphered via an SSL data layer, so this cannot work with "bind" lines having the "ssl" option. The ACL version of the test matches against a decimal notation in the form MAJOR.MINOR (eg: 3.1). |
| integer | Returns an integer value corresponding to the number of bytes present in the response buffer. It is important to understand that this test does not return false as long as the buffer is changing. This means that a check with equality to zero will almost always immediately match at the beginning of the session, while a test for more data will wait for that data to come in and return false only when haproxy is certain that no more data will come in. This test was designed to be used with TCP response content inspection. |
| binary | This extracts a binary block of |
| binary | This extracts a binary block whose size is specified at |
| boolean | This fetch either returns true when the inspection period is over, or does not fetch. |
Fetching Data Samples from Layer 7
It is possible to fetch samples from HTTP contents in both requests and responses. This application layer is also called layer 7.
It is only possible to fetch the data in this section when a full HTTP request or response has been parsed from its respective request or response buffer. This is always the case with all HTTP specific rules and for sections running with mode http
. When using TCP content inspection, it may be necessary to support an inspection delay in order to let the request or response come in first.
Fetch name | Type | Description |
---|---|---|
| string | Returns the concatenation of the first Host header and the path part of the request, which starts at the first slash and ends before the question mark. |
| integer | Returns a 32-bit hash of the value returned by the basefetch method above. This is useful to track per-URL activity on high traffic sites without having to store whole URLs. Instead a shorter hash is stored, saving a lot of memory. The output type is an unsigned integer. |
| binary | Returns the concatenation of the base32 and the src fetches. The resulting type is of type binary, with a size of 8 or 20 bytes depending on the source address family. This can be used to track per-IP, per-URL counters. |
| string | Extracts the content of the header captured by the capture request header, |
| string | Extracts the METHOD of an HTTP request. It can be used in both request and response because it is allocated. |
| string | Extracts the request's URI, which starts at the first slash and ends before the first space in the request (without the host part). Unlike path and url, it can be used in both request and response because it's allocated. |
| string | Extracts the request's HTTP version and returns either HTTP/1.0 or HTTP/1.1. Unlike req.ver, it can be used in both request, response, and logs because it relies on a persistent flag. |
| string | Extracts the content of the header captured by the capture response header, |
| string | Extracts the response's HTTP version and returns either HTTP/1.0 or HTTP/1.1. Unlike res.ver, it can be used in logs because it relies on a persistent flag. |
| binary | Extracts the body from an HTTP request as a block of data. Requires option option http-buffer-request in the front end. In case of chunked encoding, only first chunk is analyzed. |
| integer | Returns the length of the HTTP request's body available, in bytes. It may be lower than the advertised length when the body is larger than the buffer (global's |
| integer | Returns the advertized length (HTTP Header Content-Length) of the HTTP request's body in bytes. Requires option |
| string | Extracts the first occurrence of the parameter |
| string | Extracts the last occurrence of the cookie |
| integer | Returns an integer value representing the number of occurrences of the cookie |
| string | This extracts the last occurrence of header The functions hdr is equivalent to |
| integer | Returns an integer value representing the number of occurrences of request or response header field name It is important to remember that one header line may count as several headers if it has several values. The function considers any comma as a delimiter for distinct values. If you want full-line headers, use |
| integer | Extracts the last occurrence of header When used with ACLs, all occurrences are checked, and if |
| integer | Returns a boolean indicating whether the authentication data received from the client matches a username & password stored in the specified |
| string | Returns a string corresponding to the user name found in the authentication data received from the client if both the user name and password are valid according to the specified |
| boolean | Returns true when the request being processed is the first one of the connection. |
| integer + string | Returns an integer value corresponding to the method in the HTTP request. Possible integer and string values are 1 - OPTIONS, 2 - GET, 3 - HEAD, 4 - POST, 5 - PUT, 6 - DELETE, 7 - TRACE, 8 - CONNECT, 9 - OTHER. In the configuration any of the integer or string form is accepted and valid. |
| string | Extracts the request's URL path, which starts at the first slash and ends before the question mark (without the host part). See also the URLand base fetch methods. |
| string | Returns the HTTP version from the request or response using respectively |
| boolean | Returns the boolean true value if the response has been compressed by HAProxy, otherwise returns boolean false. |
| string | Returns a string containing the name of the algorithm used if the response was compressed by HAProxy. |
| ip | Extracts the last occurrence of header |
| integer | Returns an integer containing the HTTP status code from the HTTP response. IE: 302. |
| integer | Returns an integer containing the HTTP status code from the HTTP response. IE: 302. |
| string | Extracts the request's URL as presented in the request. Usually, path is preferred over using URL, because clients can send a full URL as it is normally done with proxies. The only real use is to match anything which does not match in path. |
| ip | Extracts the IP address from the request's URL when the host part is presented as an IP address. Its use is very limited. |
| integer | Extracts the port part from the request's URL. Note that if the port is not specified in the request, port 80 is assumed. |
| string | Extracts the first occurrence of the parameter |
| integer | See urlp. This one extracts the URL parameter |