ltm rule command HTTP header
iRule(1) BIG-IP TMSH Manual iRule(1)
HTTP::header
Queries or modifies HTTP headers.
SYNOPSIS
HTTP::header (
( HTTP_HEADER_EXCL_SUBCOMMANDS (HTTP_HEADER_VALUE)? ) |
( 'value' HTTP_HEADER_NAME (HTTP_HEADER_VALUE)? ) |
( 'values' HTTP_HEADER_NAME ) |
( 'names' ) |
( 'count' (HTTP_HEADER_NAME)? ) |
( 'at' HTTP_HEADER_INDEX ) |
( 'exists' HTTP_HEADER_NAME ) |
( 'insert' ('lws')? (HTTP_HEADER_NAME HTTP_HEADER_VALUE)+ ) |
( 'lws' ) |
( 'is_keepalive' ) |
( 'is_redirect' ) |
( 'replace' HTTP_HEADER_NAME (HTTP_HEADER_VALUE)? ) |
( 'remove' HTTP_HEADER_NAME ) |
( 'insert_modssl_fields' (('addr' 'port') |
('addr' 'addr' 'addr') |
('port' 'port' 'port'))) |
( 'sanitize' (HTTP_HEADER_NAME)* )
)
DESCRIPTION
Queries or modifies HTTP headers. This command replaces the BIG-IP 4.X variable http_header. The header name
is not case sensitive, so for example, 'HTTP::header value HTTP_HEADER_NAME' will match a header with the name
HeAdEr_NaMe.
Syntax
HTTP::header [value]
* Returns the value of the HTTP header named .
* Returns a null string if the HTTP header named does not
exist.
* Note that the command will operate on the value of the last header
if there are multiple headers with the same name.
* You may omit the value argument if the header name does not
collide with any of the HTTP::header subcommands.
HTTP::header values
* Returns a list of value(s) of the HTTP header named . Note
that the command will return the values all of the headers as a Tcl
list if there are multiple headers with the same name. If there is
a single value for the HTTP header, that value will be returned.
* (This subcommand was added in v9.4.0)
Note: There is an issue where HTTP::header values can remove colons in
the header values it returns. The actual header values are unchanged.
This issue is tracked as CR98328 and has been fixed in 10.0.
HTTP::header names
* Returns a list of all the headers present in the request or
response.
* In v9.4.0 and higher, multiple headers with the same name will be
listed multiple times.
HTTP::header count []
* Returns the number of HTTP headers present in the request or
response. If is supplied, returns the number of HTTP headers
present in the request or response with that name.
* In v9.4.0 and higher, multiple headers with the same name will be
counted multiple times.
Note: Due to a bug described in CR114612, HTTP::header count doesn't
count the last header, so it is unintentionally zero-index based. This
was an issue at least in 9.4.x and possibly earlier (and later?). This
has been fixed in 9.4.8 and 10.0.0.
HTTP::header at
* Returns the HTTP header name that the system finds at the
zero-based index value.
HTTP::header exists
* Returns true if the named header is present and not empty on the
request or response.
HTTP::header insert ["lws"] [ ]+
* Inserts the named HTTP header(s) and value(s) onto the end of the
HTTP request or response. The input can be a single header name and
value, or a list containing name value pairs [list name1 value1
name2 value2].
* If you specify '"lws"', the system adds linear white space to long
header values.
HTTP::header lws
* Returns 1 if a header was encountered that had linear white space,
and 0 otherwise. See RFC2616 for more information on lws and HTTP
headers.
HTTP::header is_keepalive
* A synonym for HTTP::is_keepalive.
HTTP::header is_redirect
* A synonym for HTTP::is_redirect.
HTTP::header replace []
* Replaces the value of the last occurrence of the header named
with the string . This command performs a header
insertion if the header was not present. If there are multiple
instances of the header, only the last instance is replaced.
HTTP::header remove
* Removes all headers names with the name .
HTTP::header insert_modssl_fields
* If "addr port" is specified, inserts the HTTP header
ClientIPAddress with the client IP and port as the value.
* If "addr addr addr" is specified, inserts the HTTP header
ClientIPAddress with the client IP only as the value.
* if "port port port" is specified, insertd the HTTP header
ClientTCPService with the client port as the value.
* This documents the implementation in v9.4.0 (and possibly earlier
versions), which is slightly buggy. The corrected syntax should be:
HTTP::header insert_modssl_fields [addr] [service | port] and
should behave intuitively.
* Note that this command is only for HTTP requests, not responses.
HTTP::header sanitize [header name]+
* Removes all headers except the ones you specify and the following:
Connection, Content-Encoding, Content-Length, Content-Type,
Proxy-Connection, Set-Cookie, Set-Cookie2, and Transfer-Encoding.
* Note that the Host header (required by HTTP/1.1) is removed unless
explicitly specified.
* This command can be used in the client-side or server-side context,
depending on whether you want to sanitize request and/or response
headers.
* If you are using the command in the server-side context, you may
want to consider adding Location to the list of retained headers if
your application requires they be sent to clients.
* If you are using the command in the client-side context, you may
want to consider adding Cookie, Accept, and Accept-Encoding to the
list of retained headers.
RETURN VALUE
VALID DURING
ASM_REQUEST_BLOCKING, ASM_REQUEST_VIOLATION, ASM_RESPONSE_VIOLATION, CACHE_REQUEST, CACHE_RESPONSE,
HTTP_REQUEST, HTTP_REQUEST_DATA, HTTP_REQUEST_SEND, HTTP_RESPONSE, HTTP_RESPONSE_DATA, REWRITE_REQUEST_DONE,
SERVER_CONNECTED, HTTP_PROXY_CONNECT, HTTP_PROXY_RESPONSE, MR_INGRESS, MR_EGRESS
EXAMPLES
when HTTP_REQUEST {
if { [HTTP::header "Host"] starts_with "uat" } {
pool uat_pool
} else {
pool main_pool
}
}
when HTTP_RESPONSE {
# loop through and remove all instances of the unwanted
# headers from the server response
# (Server, X-Powered-By in this example)
foreach header {Server X-Powered-By} {
log local0. "Removing $header: [HTTP::header value $header]"
HTTP::header remove $header
}
}
when HTTP_RESPONSE {
# test the new (as of 9.4.0) command, HTTP::header values
# for retrieving the values of multiple, identically named headers
HTTP::header insert header_1 value_1
HTTP::header insert header_1 value_2
HTTP::header insert header_1 value_3
log local0. "\[HTTP::header header_1\]: [HTTP::header header_1]"
log local0. "\[HTTP::header value header_1\]: [HTTP::header value header_1]"
log local0. "\[HTTP::header values header_1\]: [HTTP::header values header_1]"
}
Logs:
[HTTP::header header_1]: value_3
[HTTP::header value header_1]: value_3
[HTTP::header values header_1]: value_1 value_2 value_3
HINTS
SEE ALSO
HTTP::is_keepalive HTTP::is_redirect
CHANGE LOG
@BIGIP-9.0.0 --First introduced the command.
BIG-IP 2020-06-23 iRule(1)