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
always_false boolean Always returns the boolean value false
always_true boolean Always returns the boolean value true
avg_queue([<backend>]) integer Returns the total number of queued connections on <backend> divided by the number of active servers
be_conn([<backend>]) integer Returns the number of currently established connections on <backend>, possibly including the connection being evaluated
be_sess_rate([<backend>]) integer Returns the sessions creation rate on <backend>, in number of new sessions per second
connslots([<backend>]) integer Returns the number of connection slots still available in <backend>, by counting the maximum number of connections on all servers and the maximum queue size.
date([<offset>]) integer Returns the current date as the epoch (number of seconds since 01/01/1970). If <offset> is specified, then it is a number of seconds that is added to the current date before returning the value.
env(<name>) string Returns a string containing the value of environment variable <name>. As a reminder, environment variables are per-process and are sampled when the process starts.
fe_conn([<frontend>]) integer Returns the number of currently established connections on <frontend>, possibly including the connection being evaluated
fe_sess_rate([<frontend>]) integer Returns an integer value corresponding to the sessions creation rate on <frontend>, in number of new sessions per second.
nbproc integer Returns the number of HAProxy processes that were started.
nbsrv([<backend>]) integer Returns the number of usable servers in <backend>
proc integer Returns the position of the current process, between 1 and nbproc
queue([<backend>]) integer Returns the total number of queued connections on <backend>, including all the connections in server queues
rand([<range>]) integer Returns a random integer within 0 to <range> possible values. If the <range> is not specified, it defaults to 2^32 (4294967295)
srv_conn([<backend>]<server>) integer Returns the number of currently established connections on <server>, possibly including the connection being evaluated.
srv_is_up([<backend>]<server>) boolean Returns true when <server> is UP, and false when it is either DOWN or in maintenance mode
srv_sess_rate([<backend><server>)] integer Returns the sessions creation rate on <server>, in number of new sessions per second
stopping boolean Returns true if the process calling the function is currently stopping
table_avl([<table>]) integer Returns the total number of available entries in the stick-table <table>
table_cnt([<table>]) integer Returns the number of entries currently in use in the stick-table <table>
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
be_id integer Returns the current back end’s id
dst ip IPv4 Destination on the client side connection
dst_conn integer Returns the number of currently established connections on the same socket including the one being evaluated
dst_port integer Returns the destination TCP port of the client side connection, which is the port the client connected to
fe_id integer Returns the current front end’s id
sc_bytes_in_rate(<ctr>[,<table>])sc0_bytes_in_rate([<table>])
sc1_bytes_in_rate([<table>])
sc2_bytes_in_rate([<table>])
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.
sc_bytes_out_rate(<ctr>[,<table>])
sc0_bytes_out_rate([<table>])
sc1_bytes_out_rate([<table>])
sc2_bytes_out_rate([<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
sc_clr_gpc0(<ctr>[,<table>])
sc0_clr_gpc0([<table>])
sc1_clr_gpc0([<table>])
sc2_clr_gpc0([<table>])
integer Clears the first General Purpose Counter associated to the currently tracked counters, and returns its previous value.
sc_conn_cnt(<ctr>[,<table>])
sc0_conn_cnt([<table>])
sc1_conn_cnt([<table>])
sc2_conn_cnt([<table>])
integer Returns the cumulative number of incoming connections from currently tracked counters.
sc_conn_cur(<ctr>[,<table>])
sc0_conn_cur([<table>])
sc1_conn_cur([<table>])
sc2_conn_cur([<table>])
integer Returns the current amount of concurrent connections tracking the same tracked counters.
sc_conn_rate(<ctr>[,<table>])
sc0_conn_rate([<table>])
sc1_conn_rate([<table>])
sc2_conn_rate([<table>])
integer Returns the average connection rate from the currently tracked counters, measured in number of connections over the period configured in the table.
sc_get_gpc0(<ctr>[,<table>])
sc0_get_gpc0([<table>])
sc1_get_gpc0([<table>])
sc2_get_gpc0([<table>])
integer Returns the value of the first General Purpose Counter associated to the currently tracked counters.
sc_gpc0_rate(<ctr>[,<table>])
sc0_gpc0_rate([<table>])
sc1_gpc0_rate([<table>])
sc2_gpc0_rate([<table>])
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.
sc_http_err_cnt(<ctr>[,<table>])
sc0_http_err_cnt([<table>])
sc1_http_err_cnt([<table>])
sc2_http_err_cnt([<table>])
integer Returns the cumulative number of HTTP errors from the currently tracked counters.
sc_http_err_rate(<ctr>[,<table>])
sc0_http_err_rate([<table>])
sc1_http_err_rate([<table>])
sc2_http_err_rate([<table>])
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.
sc_http_req_cnt(<ctr>[,<table>])
sc0_http_req_cnt([<table>])
sc1_http_req_cnt([<table>])
sc2_http_req_cnt([<table>])
integer Returns the cumulative number of HTTP requests from the currently tracked counters. This includes every started request, whether it’s valid or not.
sc_http_req_rate(<ctr>[,<table>])
sc0_http_req_rate([<table>])
sc1_http_req_rate([<table>])
sc2_http_req_rate([<table>])
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.
sc_inc_gpc0(<ctr>[,<table>])
sc0_inc_gpc0([<table>])
sc1_inc_gpc0([<table>])
sc2_inc_gpc0([<table>])
integer Increments the first General Purpose Counter associated to the currently tracked counters, and returns its new value.
sc_kbytes_in(<ctr>[,<table>])
sc0_kbytes_in([<table>])
sc1_kbytes_in([<table>])
sc2_kbytes_in([<table>])
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.
sc_kbytes_out(<ctr>[,<table>])
sc0_kbytes_out([<table>])
sc1_kbytes_out([<table>])
sc2_kbytes_out([<table>])
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.
sc_sess_cnt(<ctr>[,<table>])
sc0_sess_cnt([<table>])
sc1_sess_cnt([<table>])
sc2_sess_cnt([<table>])
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.
sc_sess_rate(<ctr>[,<table>])
sc0_sess_rate([<table>])
sc1_sess_rate([<table>])
sc2_sess_rate([<table>])
integer Returns the average session rate from the currently tracked counters, measured in number of sessions over the period configured in the table.
sc_tracked(<ctr>[,<table>])
sc0_tracked([<table>])
sc1_tracked([<table>])
sc2_tracked([<table>])
boolean Returns true if the designated session counter is currently being tracked by the current session.
sc_trackers(<ctr>[,<table>])
sc0_trackers([<table>])
sc1_trackers([<table>])
sc2_trackers([<table>])
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.
so_id integer Returns the current listening socket’s ID.
src ip This is the source IPv4 address of the client of the session.
src_bytes_in_rate([<table>]) integer Returns the average bytes rate from the incoming connection’s source address in <table> measured in number of bytes over the period configured in the table
src_bytes_out_rate([<table>]) integer Returns the average bytes rate to the incoming connection’s source address in <table> measured in number of bytes over the period configured in the table
src_clr_gpc0([<table>]) integer Clears the first General Purpose Counter associated to the incoming connection’s source address in <table> and returns its previous value. If the address is not found, an entry is created and 0 is returned.
src_conn_cnt([<table>]) integer Returns the cumulative number of connections initiated from the current incoming connection’s source address in <table>. If the address is not found, zero is returned.
src_conn_cur([<table>]) integer Returns the current number of concurrent connections initiated from the current incoming connection’s source address in <table>. If the address is not found, zero is returned.
src_conn_rate([<table>]) integer Returns the average connection rate from the incoming connection’s source address in <table> measured in number of connections over the period configured in the table. If the address is not found, zero is returned.
src_get_gpc0([<table>]) integer Returns the value of the first General Purpose Counter associated to the incoming connection’s source address in <table>. If the address is not found, zero is returned.
src_gpc0_rate([<table>]) integer Returns the average increment rate of the first General Purpose Counter associated to the incoming connection’s source address in <table>. It reports the frequency which the gpc0 counter was incremented over the configured period.
src_http_err_cnt([<table>]) integer Returns the cumulative number of HTTP errors from the incoming connection’s source address in <table>. This includes both the request errors and 4xx error responses. If the address is not found, zero is returned.
src_http_err_rate([<table>]) integer Returns the average rate of HTTP errors from the incoming connection’s source address in <table>, measured in number of errors over the period configured in the table. This includes both the request errors and 4xx error responses. If the address is not found, zero is returned.
src_http_req_cnt([<table>]) integer Returns the cumulative number of HTTP requests from the incoming connection’s source address in <table>. This includes every started request, whether valid or not. If the address is not found, zero is returned.
src_http_req_rate([<table>]) integer Returns the average rate of HTTP requests from the incoming connection’s source address in <table>, measured in number of requests over the period configured in the table. This includes every started request, valid or not. If the address is not found, zero is returned.
src_inc_gpc0([<table>]) integer Increments the first General Purpose Counter associated to the incoming connection’s source address in <table> and returns its new value. If the address is not found, an entry is created and 1 is returned.
src_kbytes_in([<table>]) integer Returns the total amount of data received from the incoming connection’s source address in <table>, measured in kilobytes. If the address is not found, zero is returned. The test is currently performed on 32-bit integers, which limits values to 4 terabytes.
src_kbytes_out([<table>]) integer Returns the total amount of data sent to the incoming connection’s source address in <table> measured in kilobytes. If the address is not found, zero is returned. The test is currently performed on 32-bit integers, which limits values to 4 terabytes.
src_port integer Returns the TCP source port from the connection on the client side, which is the port where the client connected from.
src_sess_cnt([<table>]) integer Returns the cumulative number of connections initiated from the incoming connection’s source IPv4 address in <table> that were transformed into sessions. If the address is not found, zero is returned.
src_sess_rate([<table>]) integer Returns the average session rate from the incoming connection’s source address in <table>, measured in number of sessions over the period configured in the table. If the address is not found, zero is returned.
src_updt_conn_cnt([<table>]) integer Creates or updates the entry associated to the incoming connection’s source address in the <table>. This table must be configured to store the “conn_cnt” data type, otherwise the match is ignored. The current count is incremented by one, and the expiration timer refreshed. The updated count is returned, so this match cannot return zero. This was used to reject service abusers based on their source address.
srv_id 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
ssl_bc 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 SSL option was configured.
ssl_bc_alg_keysize integer Returns the symmetric cipher key size supported in bits when the connection to the server was made over an SSL/TLS transport layer.
ssl_bc_cipher string Returns the name of the cipher used when the connection to the was made using SSL/TLS.
ssl_bc_protocol string Returns the name of the protocol used when the connection to the server was made over SSL/TLS.
ssl_bc_unique_id 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.
ssl_bc_session_id binary Returns the SSL Session ID of the server side connection when the outgoing connection was made over SSL/TLS transport layer.
ssl_bc_use_keysize integer Returns the symmetric cipher key size used in bits when the server side connection was made over SSL/TLS.
ssl_c_ca_err 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.
ssl_c_ca_err_depth 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.
ssl_c_der binary Returns the DER formatted certificate presented by the client when the client side connection was made over SSL/TLS.
ssl_c_err 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.
ssl_c_i_dn([<entry>[,<occ>]]) 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.
ssl_c_key_alg 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.
ssl_c_notafter string Returns the end date presented by the client as a formatted string YYMMDDhhmmss[Z] when the incoming connection is made over SSL/TLS.
ssl_c_notbefore string Returns the start date presented by the client as a formatted string YYMMDDhhmmss[Z] when the incoming connection is made over SSL/TLS.
ssl_c_s_dn([<entry>[,<occ>]]) 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.
ssl_c_serial binary Returns the serial of the certificate presented by the client when the client side connection is made over SSL/TLS.
ssl_c_sha1 binary Returns the SHA-1 fingerprint of the certificate presented by the client when the client side connection is made over SSL/TLS.
ssl_c_sig_alg 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.
ssl_c_used 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.
ssl_c_verify 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.
ssl_c_version integer Returns the version of the certificate presented by the client when the client side connection is made over SSL/TLS.
ssl_f_der binary Returns the DER formatted certificate presented by the front end when the client side connection is made over SSL/TLS.
ssl_f_i_dn([<entry>[,<occ>]]) 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.
ssl_f_key_alg 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.
ssl_f_notafter 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.
ssl_f_notbefore 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.
ssl_f_s_dn([<entry>[,<occ>]]) 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.
ssl_f_serial binary Returns the serial of the certificate presented by the front end when the client side connection is made over SSL/TLS.
ssl_f_sha1 binary Returns the SHA-1 fingerprint of the certificate presented by the front end when the client side connection is made over SSL/TLS.
ssl_f_sig_alg 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.
ssl_f_version integer Returns the version of the certificate presented by the front end when the client side connection is made over SSL/TLS.
ssl_fc 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.
ssl_fc_alg_keysize integer Returns the symmetric cipher key size supported in bits when the client side connection is made over SSL/TLS.
ssl_fc_alpn 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 bind line 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.
ssl_fc_cipher string Returns the name of the cipher used when the client side connection is made over a SSL/TLS
ssl_fc_has_crt boolean Returns true if a client certificate is present over a client side connection made using SSL/TLS. Useful if verify statement 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.
ssl_fc_has_sni 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.
ssl_fc_is_resumed boolean Returns true when the SSL/TLS session has been resumed through the use of SSL session cache or TLS tickets
ssl_fc_npn 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 npn keyword on the bind line specifies a protocol list.
ssl_fc_protocol string Returns the name of the used protocol when the client side connection was made over SSL/TLS.
ssl_fc_unique_id 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.
ssl_fc_session_id 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.
ssl_fc_sni 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).
ssl_fc_use_keysize 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
req.len integer Returns the number of bytes present in the request buffer.
req.payload(<offset>,<length>)
payload(<offset>,<length>) (deprecated)
binary Extracts a binary block of <length> bytes and starting at byte <offset> in the request buffer. As a special case, if the <length> argument is zero, the entire buffer from <offset> to the end is extracted.
req.payload_lv(<offset1>,<length>[,<offset2>])
payload_lv(<offset1>,<length>[,<offset2>]) (deprecated)
binary Extracts a binary block whose size is specified at <offset1> for <length> bytes, and which starts at <offset2> if specified or just after the length in the request buffer. The <offset2> parameter also supports relative offsets if prepended with a ‘+’ or ‘-‘ sign.
req.proto_http
req_proto_http (deprecated)
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.
req.rdp_cookie([<name>])
rdp_cookie([<name>])(deprecated)
string When the request buffer looks like RDP protocol, this extracts the RDP cookie <name>, or any cookie if unspecified. The parser only checks for the first cookie, as illustrated in the RDP protocol specification. The cookie name is case insensitive. Generally the MSTS cookie name is used, as it can contain the user name of the client connecting to the server if properly configured on the client. The MSTSHASH cookie is often used as well for session stickiness to servers.
req.rdp_cookie_cnt([name])
rdp_cookie_cnt([name]) (deprecated)
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.
req.ssl_ec_ext 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.
req.ssl_sni
req_ssl_sni (deprecated)
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.

req.ssl_ver
req_ssl_ver (deprecated)

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).
res.len 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.
res.payload(<offset>,<length>) binary This extracts a binary block of <length> bytes and starting at byte <offset> in the response buffer. As a special case, if the <length> argument is zero, the the whole buffer from <offset> to the end is extracted.
res.payload(<offset>,<length>) binary This extracts a binary block whose size is specified at <offset1> for <length> bytes, and which starts at <offset2> if specified or just after the length in the response buffer. The <offset2> parameter also supports relative offsets if preceded with a ‘+’ or ‘-‘ sign.
wait_end 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
base 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.
base32 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.
base32+src 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.
capture.req.hdr(<idx>) string Extracts the content of the header captured by the capture request header, idx is the position of the capture keyword in the configuration and starts at 0.
capture.req.method string Extracts the METHOD of an HTTP request. It can be used in both request and response because it is allocated.
capture.req.uri 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.
capture.req.ver 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.
capture.res.hdr(<idx>) string Extracts the content of the header captured by the capture response header, idx is the position of the capture keyword in the configuration and starts at 0.
capture.res.ver 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.
req.body 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.
req.body_len 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 tune.bufsize parameter) Requires option option http-buffer-request in the front end. In case of chunked encoding, only first chunk is evaluated.
req.body_size integer Returns the advertized length (HTTP Header Content-Length) of the HTTP request’s body in bytes. Requires option option http-buffer-request in the front end. In case of chunked encoding, only first chunk is evaluated.
req.body_param([<name>]) string Extracts the first occurrence of the parameter <name> (case sensitive) in the body. If none provided, then all are evaluated. This fetch assumes the body of the POST request is URL-encoded. Content-Type header value is set to application/x-www-form-urlencoded.
req.cook([<name>])
res.cook([<name>])

cook([<name>]) (deprecated)
cookie([<name>]) (deprecated)
scook([<name>]) (deprecated)
set-cookie([<name>]) (deprecated)
string Extracts the last occurrence of the cookie <name> on a Cookie or Set-Cookie header line from the request using req.cook() or the response using res.cook() respectively, and returns its value as string. If no name is specified, the first cookie value is returned; <name> is case-sensitive.
req.cook_cnt([<name>])

res.cook_cnt([<name>])

cook_cnt([<name>]) (deprecated)
scook_cnt([<name>]) (deprecated)
integer Returns an integer value representing the number of occurrences of the cookie <name> in the request for req.cook_cnt() or in the response for res.cook_cnt(), or all cookies if <name> is not specified.
req.cook_val([<name>])

res.cook_val([<name>])

cook_val([<name>]) (deprecated)
scook_val([<name>]) (deprecated)
string

This extracts the last occurrence of header <name> in an HTTP request (req.hdr) or response (res.hdr). Optionally, a specific occurrence <occ> might be specified as a position number. Positive values indicate a position from the first occurrence, with 1 being the first one. Negative values indicate positions relative to the last one, with -1 being the last one.

The functions req.hdr() and res.hdr() consider any comma as a delimiter for distinct values. If full-line headers are desired instead, use req.fhdr() or res.fhdr() respectively.

hdr is equivalent to req.hdr() when used on requests, and to res.hdr() when used on responses. Refer to these respective fetches for more details. In case of doubt about the fetch direction, please use the explicit ones.

req.hdr_cnt([<name>])

req.fhdr_cnt([<name>])

res.hdr_cnt([<name>])

res.fhdr_cnt([<name>])

hdr_cnt([<header>]) (deprecated)
integer

Returns an integer value representing the number of occurrences of request or response header field name <name> with respectively req.hdr_cnt() or res.hdr_cnt(), or the total number of header fields if <name> is not specified.

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 req.fhdr_cnt() or res.fhdr_cnt()instead.

req.hdr_val([<name>[,<occ>]])
res.hdr_val([<name>[,<occ>]])
hdr_val([<name>[,<occ>]]) (deprecated)
shdr_val([<name>[,<occ>]]) (deprecated)
integer

Extracts the last occurrence of header <name> in an HTTP request or response, with respectively req.hdr_val() or res.hdr_val(), then converts it to an integer value.

When used with ACLs, all occurrences are checked, and if <name> is omitted, every value of every header is checked. Optionally, a specific occurrence might be specified as a position number. Positive values indicate a position from the first occurrence, with 1 being the first one. Negative values indicate positions relative to the last one, with -1 being the last one.

req.hdr_names([<delim>]])
res.hdr_names([<delim>]])
integer Returns a boolean indicating whether the authentication data received from the client matches a username & password stored in the specified <userlist>. Currently only http basic auth is supported.
http_auth_group(<userlist>) 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 <userlist>. Currently only http basic auth is supported.
http_first_req boolean Returns true when the request being processed is the first one of the connection.
method 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.
path 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.
req.ver

res.ver

req_ver (deprecated)
res_ver (deprecated)
string Returns the HTTP version from the request or response using respectively req.ver and res.ver. Example or string returned: 1.1
res.comp boolean Returns the boolean true value if the response has been compressed by HAProxy, otherwise returns boolean false.
res.comp_algo string Returns a string containing the name of the algorithm used if the response was compressed by HAProxy.
req.hdr_ip([<name>[,<occ>]])
res.hdr_ip([<name>[,<occ>]])
hdr_ip([<name>[,<occ>]]) (deprecated)
shdr_ip([<name>[,<occ>]]) (deprecated)
ip Extracts the last occurrence of header <name> in an HTTP request or response, using respectively req.hdr_ip() or res.hdr_ip(), then convert it to either an IPv4 or IPv6 address and returns this address. Optionally, a specific occurrence <occ> might be specified as a position number. Positive values indicate a position from the first occurrence, with 1 being the first one. Negative values indicate positions relative to the last one, with -1 being the last one. This can be useful to learn some data into a stick table.
status integer Returns an integer containing the HTTP status code from the HTTP response. IE: 302.
status integer Returns an integer containing the HTTP status code from the HTTP response. IE: 302.
url 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.
url_ip 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.
url_port 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.
urlp(<name>[,<delim>]) url_param(<name>[,<delim>]) string Extracts the first occurrence of the parameter <name> in the query string, which begins after either ? or <delim>, and which ends before either &, ; or <delim>. The parameter <name> is case-sensitive. The result is a string corresponding to the value of the parameter <name> as presented in the request (no URL decoding is performed).
urlp_val(<name>[,<delim>]) integer See urlp. This one extracts the URL parameter <name> from the request and converts it to an integer value.