API Objects Reference
L7 rules
This page applies to:
- HAProxy ALOHA - all versions
The rule type can be applied at different moments during request processing. Hence, some rules are available in service only, others in the farm only, and some in both.
Rules available once the incoming connection has been accepted:
tcpreqconn(service only)
Rules available once the data has arrived on a client connection:
tcpreqcont, available in both service and farmhttpreq, available in both service and farmredirect, available in both service and farm
Rules available in service only to choose an alternative farm:
usefarm
Rules available in farm only to choose to force traffic to a server:
useservertcprspcont
Other rule types are available to perform third party actions in HAProxy:
Health checking:
tcpcheckStickiness:
stickreq,stickrsp
tcpreqconnJump to heading
Definition: Perform an action on an incoming connection:
typeJump to heading
Definition: action to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| accept | Accept an incoming connection |
| reject | Reject an incoming connection |
condJump to heading
Definition: Condition to apply the rule
Type: enum
Default value: Positive match
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
httpreqJump to heading
Definition: Perform an action on an incoming HTTP request.
To create an L7 rule for
httpreq, you must use the URL/api/2/*/*/l7/<objecttype>/<objectname>/rule/<ruletype>/<number>.The rule
<number>can have any of the following values:
| Value | Description |
|---|---|
| Tail | Get the first rule of the list |
| Head | Get the last rule of the list |
| A positive integer | Get the rule pointed by the integer |
typeJump to heading
Definition: action to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| allow | Accept incoming request; stop evaluation of next rules |
| deny | Reject incoming request; stop evaluation of next rules |
| auth | Stop the evaluation of the rules; answer with a 401 or 407 to invite the client to authenticate itself |
| redirect | Perform an HTTP redirection rule |
| tarpit | Block the request during timeout tarpit period of time; stop evaluation of next rules |
| add-header | Append an HTTP header field in the request |
| set-header | Append an HTTP header field in the request; but delete first any field with the same name |
| set-log-level | Change the log level for the current HTTP (req+resp) session |
auth-realmJump to heading
Info
This is ignored if httpreq is not set to auth.
Definition: Authentication realm string
Type: string
Default value: none
log-levelJump to heading
Info
This is ignored if httpreq is not set to set-log-level.
Definition: Log level to use
Type: enum
Default value: none
Values: Standard syslog levels: debug, info, notice, warning, err, crit, alert, emerg or their integer equivalent, respectively 0, 1, 2, 3, 4, 5, 6, 7* A specific keyword silent to prevent generating the log line, or integer 8.
redir-typeJump to heading
Info
This is ignored if httpreq is not set to redirect.
Definition: Type of HTTP redirection to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| location | Exact redir-to value is placed in the Location header field |
| prefix | Use redir-to concatened to current URI path (including query string) to create the Location header |
| scheme | Use to change the URL scheme: redir-to is concatenated to the first occurrence of the Host header and the URI path, including the query string |
redir-toJump to heading
Info
This is ignored if httpreq is not set to redirect.
Definition: A string to use when building the Location header
Type: string
Default value: none
redir-codeJump to heading
Info
This is ignored if httpreq is not set to redirect.
Definition: HTTP Status code used to perform the redirection (usually, 301 or 302)
Type: integer
Default value: none
hdr-nameJump to heading
Info
This is ignored if httpreq is not set to add-header or set-header.
Definition: Name of the HTTP header field
Type: string
Default value: none
condJump to heading
Definition: Condition to apply the rule
Type: enum
Default value: Positive match
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
redirectJump to heading
We highly recommend using thehttpreq redirect rule rather than the redirect rule. It is easier to understand a configuration that uses only http-request rules instead of a mix of different types of directives.
typeJump to heading
Definition: Type of HTTP redirection to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| location | Exact to value is placed in the Location header field |
| prefix | Use to concatened to current URI path (including query string) to create the Location header |
| scheme | Use to change the URL scheme: redir-to is concatenated to the first occurrence of the Host header and the URI path, including the query string |
toJump to heading
Definition: String to use when building the Location header
Type: string
Default value: none
codeJump to heading
Definition: HTTP Status code used to perform the redirection (usually 301 or 302)
Type: enum
Default value:
condJump to heading
Definition: condition to apply the rule
Type: Positive match
Default value:
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
usefarmJump to heading
Definition: Content switching rule to route traffic to a farm.
target-farmJump to heading
Definition: Name of the farm to route the traffic to
Type: string
Default value: none
condJump to heading
Definition: condition to apply the rule
Type: Positive match
Default value:
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
tcprspcontJump to heading
Definition: Perform an action on a session response.
typeJump to heading
Definition: Action to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| accept | Accept an incoming connection |
| reject | Reject an incoming connection |
condJump to heading
Definition: condition to apply the rule
Type: Positive match
Default value:
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
useserverJump to heading
Definition: content switching rule to route traffic to a server.
target-serverJump to heading
Definition: Name of the server to route the traffic to
Type: string
Default value: none
condJump to heading
Definition: condition to apply the rule
Type: Positive match
Default value:
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
stickreqJump to heading
Definition: Match and/or set stickiness during the request.
typeJump to heading
Definition: Action to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| matchandstore | Match the pattern in the table and stores it if not found |
| matchonly | Match the pattern in the table |
| storeonly | Store the pattern in the table |
patternJump to heading
Definition: Fetch expression to the retrieve key used to perform stickiness
Type: string
Default value: none
tableJump to heading
Definition: Stick table name
Type: string
Default value: none; if not set, use the stick table from the local farm
condJump to heading
Definition: condition to apply the rule
Type: Positive match
Default value:
Values:
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
stickrspJump to heading
Definition: Match and/or set stickiness during the request.
typeJump to heading
Definition: Action to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| storeonly | Store the pattern in the table |
patternJump to heading
Definition: Fetch expression to the retrieve key used to perform stickiness
Type: string
Default value: none
tableJump to heading
Definition: Stick table name
Type: string
Default value: none; if not set, use the stick table from the local farm
condJump to heading
Definition: condition to apply the rule
Type: Positive match
Default value:
| Value | Description |
|---|---|
| if | Positive match: apply the rule if cond_test matches |
| unless | Negative match: apply the rule if cond_test does not match |
cond-testJump to heading
Definition: HAProxy ACL(s) to perform conditions
Type: string
Default value: none
tcpcheckJump to heading
Definition: Send or expect a sequence to perform a server health check.
typeJump to heading
Definition: Action to perform
Type: enum
Default value: none
| Value | Description |
|---|---|
| connect | Establish a TCP connection to the server |
| send | Send raw data to the server |
| expect | Match content in data returned by the server |
connect-portJump to heading
Info
This is ignored if type is not set to connect.
Definition: TCP to connect to
Type: integer
Default value: Server’s port
connect-sslJump to heading
Info
This is ignored if type is not set to connect.
Definition: Establish a TLS connection
Type: enum; value accepted: enabled
Default value: disabled
expect-failonmatchJump to heading
Info
This is ignored if type is not set to expect.
Definition: Pattern (string or hexadecimal representation) to match against server response
Type: string
Default value: none
expect-matchJump to heading
Info
This is ignored if type is not set to expect.
Definition: type of matching to perform
Type: enum
Default value: string
| Value | Description |
|---|---|
| binary | Binary (hexadecimal) matching |
| rstring | Regular expression |
| string | Regular string comparison |
expect-patternJump to heading
Info
This is ignored if type is not set to expect.
Definition: Pattern (string or hexadecimal representation) to match against server response.
Type: string
Default value: none
send-dataJump to heading
Info
This is ignored if type is not set to send.
Definition: Data to send to the server
Type: enum
Default value: string
send-formatJump to heading
Info
This is ignored if type is not set to send.
Definition: Format of the data to send to the server
Type: enum
Default value: string
| Value | Description |
|---|---|
| binary | Binary (hexadecimal) matching |
| string | Regular string comparison |
Your feedback is important to us!
Do you have any suggestions on how we can improve the content of this page?