API Objects Reference
L7 rules
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 farm -
httpreq, available in both service and farm -
redirect, 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:
-
useserver -
tcprspcont
Other rule types are available to perform third party actions in HAProxy:
-
Health checking:
tcpcheck -
Stickiness:
stickreq,stickrsp
tcpreqconn Jump to heading
Definition: Perform an action on an incoming connection:
type Jump to heading
-
Definition: action to perform
-
Type: enum
-
Default value: none
| Value | Description |
|---|---|
| accept | Accept an incoming connection |
| reject | Reject an incoming connection |
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
httpreq Jump 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 |
type Jump 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-realm Jump to heading
Info
This is ignored if httpreq is not set to auth.
-
Definition: Authentication realm string
-
Type: string
-
Default value: none
log-level Jump 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-type Jump 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-to Jump 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-code Jump 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-name Jump 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
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
redirect Jump 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.
type Jump 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 |
to Jump to heading
-
Definition: String to use when building the Location header
-
Type: string
-
Default value: none
code Jump to heading
-
Definition: HTTP Status code used to perform the redirection (usually 301 or 302)
-
Type: enum
-
Default value:
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
usefarm Jump to heading
Definition: Content switching rule to route traffic to a farm.
target-farm Jump to heading
-
Definition: Name of the farm to route the traffic to
-
Type: string
-
Default value: none
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
tcprspcont Jump to heading
Definition: Perform an action on a session response.
type Jump to heading
-
Definition: Action to perform
-
Type: enum
-
Default value: none
| Value | Description |
|---|---|
| accept | Accept an incoming connection |
| reject | Reject an incoming connection |
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
useserver Jump to heading
Definition: content switching rule to route traffic to a server.
target-server Jump to heading
-
Definition: Name of the server to route the traffic to
-
Type: string
-
Default value: none
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
stickreq Jump to heading
Definition: Match and/or set stickiness during the request.
type Jump 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 |
pattern Jump to heading
-
Definition: Fetch expression to the retrieve key used to perform stickiness
-
Type: string
-
Default value: none
table Jump to heading
-
Definition: Stick table name
-
Type: string
-
Default value: none; if not set, use the stick table from the local farm
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
stickrsp Jump to heading
Definition: Match and/or set stickiness during the request.
type Jump to heading
-
Definition: Action to perform
-
Type: enum
-
Default value: none
| Value | Description |
|---|---|
| storeonly | Store the pattern in the table |
pattern Jump to heading
-
Definition: Fetch expression to the retrieve key used to perform stickiness
-
Type: string
-
Default value: none
table Jump to heading
-
Definition: Stick table name
-
Type: string
-
Default value: none; if not set, use the stick table from the local farm
cond Jump 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-test Jump to heading
-
Definition: HAProxy ACL(s) to perform conditions
-
Type: string
-
Default value: none
tcpcheck Jump to heading
Definition: Send or expect a sequence to perform a server health check.
type Jump 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-port Jump 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-ssl Jump 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-failonmatch Jump 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-match Jump 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-pattern Jump 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-data Jump 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-format Jump 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 |
Do you have any suggestions on how we can improve the content of this page?