Manipulating Header or Content Data

The iRules feature includes several commands that are specifically designed to manipulate certain types of data. Data manipulation in this case refers to inserting, replacing, and removing data, as well as setting certain values found in headers and cookies.

The types of headers and content that you can manipulate with iRules are:

  • Link Layer data
  • IP headers
  • TCP headers
  • HTTP headers and cookies
  • SSL headers

Manipulating Link Layer data

Using the command described in Table 1, you can set the QoS level for transmitting a packet.

iRule Command Description
LINK::vlan_qos Set the VLAN QoS level that you want the system to use when transmitting the packet.

Manipulating IP headers

Using the command described in Table 2, you can set the ToS level for transmitting the packet.

iRule Command Description
IP::tos Sets the IP ToS level that you want the system to use when transmitting the packet.

Manipulating TCP headers and content

Using the commands described in Table 3, you can manipulate TCP headers and content data.

iRule Command Description
TCP::collect Causes TCP to start collecting the specified amount of content data.
TCP::release Causes TCP to resume processing the connection and to flush collected data.
TCP::payload replace Replaces collected payload with the given data.
TCP::respond Sends the named data directly to the peer. This command is used to complete a protocol handshake with an iRule.
TCP::close Closes the connection.

Manipulating HTTP headers and cookies

There are several iRule commands that you can use in your iRules to manipulate HTTP header data, content data, and cookies.

Manipulating HTTP headers and content

Table 4 lists the iRule commands that you can use to manipulate headers in HTTP requests and responses.

HTTP::header insert ["lws"] Inserts the named HTTP header and its value into the end of the HTTP request or response. If you specify "lws", the system adds linear white space to long header values.
HTTP::header insert ["lws"] {n1, v1, n2, v2, n3, v3, ...} Passes a Tcl list to insert into a header. In such cases, the system treats the list as a list of name/value pairs. If you specify "lws", the system adds linear white space to long header values.
HTTP::header [value] Sets the value of the named header. If the header is present, the command replaces the header; otherwise, the command adds the header. You can omit the argument if the header name does not collide with any other values.
HTTP::header replace [] Replaces the last occurrence of the named header with the string . This command performs a header insertion if the header was not present.
HTTP::header remove Removes the last occurrence of the named header from the request or response.
HTTP::redirect Redirects a HTTP request or response to the specified URL. Note that this command sends the response to the client immediately. Therefore, you cannot specify this command multiple times in an iRule, nor can you specify any other commands that modify header or content, after you specify this command.
HTTP::respond [content ] [
]+
This is a powerful API that allows users to generate or rewrite a client request or a server response. When the system runs the command on the client side, it sends the response to the client without any load balancing taking place. If the system runs the command on the server side, the content from the actual server is discarded and replaced with the information provided to this API. Note that because the system sends the response data immediately after this iRule runs, we recommend that you not run any more iRules after this API.
HTTP::header insert_modssl_fields {options} Optional parameters are "addr" or "service". These insert the HTTP header field "ClientIPAddress" or "ClientTCPService" respectively. The behavior corresponds to the BIG-IP 4.x SSL Proxy attribute "client tcp insert".
HTTP::header sanitize
+
Removes all but the headers you specify. The exception to this is some essential HTTP headers.
HTTP::request_num Returns the number of HTTP requests that a client made on the connection.
COMPRESS::enable This command enables compression for the current HTTP response. Note that when using this command, you must set the HTTP profile setting Compression to Selective. You can only use this command in the context of the iRule events HTTP_REQUEST, HTTP_REQUEST_DATA, and HTTP_RESPONSE.
COMPRESS::disable This command enables compression for the current HTTP response. Note that when using this command, you must set the HTTP profile setting Compression to Selective.You can only use this command in the context of the iRule events HTTP_REQUEST, HTTP_REQUEST_DATA, and HTTP_RESPONSE.
COMPRESS::buffer_size Sets the compression buffer size. You can only use this command in the context of the iRule events HTTP_REQUEST, HTTP_REQUEST_DATA, and HTTP_RESPONSE.
COMPRESS::gzip memory_level Sets the gzip memory level. You can only use this command in the context of the iRule events HTTP_REQUEST, HTTP_REQUEST_DATA, and HTTP_RESPONSE
COMPRESS::gzip window_size Sets the gzip window size. You can only use this command in the context of the iRule events HTTP_REQUEST, HTTP_REQUEST_DATA, and HTTP_RESPONSE.
COMPRESS::gzip level Specifies the amount and rate of compression.

As an option, the value of a header that you insert into an HTTP request can be the result of an SSL query command. To do this, specify an SSL query command as an argument to an HTTP::header insert command.

Note


Using HTTP::header insert or HTTP::remove commands in an iRule overrides the Header Insert and Header Erase settings in the corresponding HTTP profile.

Manipulating HTTP cookies

Table 5 lists the iRule commands that you can use to manipulate cookies in HTTP requests and responses.

iRule Command Description
Commands for request messages
HTTP::cookie names Returns the names of all the cookies present in the HTTP header.
HTTP::cookie count Returns the number of cookies present in the HTTP header.
HTTP::cookie [value] [string] Sets or gets the cookie value of the given name. You can omit the value of this command if the cookie name does not collide with any of the other commands.
HTTP::cookie version [version] Sets or gets the version of the cookie.
HTTP::cookie path [path] Sets or gets the cookie path.
HTTP::cookie domain [domain] Sets or gets the cookie domain.
HTTP::cookie ports [portlist] Sets or gets the cookie port lists for V1 cookies.
HTTP::cookie insert [path ] [domain ] [version <0 | 1 | 2>] Adds or replaces a cookie. The default value for the version is 0.
HTTP::cookie remove Removes a cookie.
HTTP::cookie sanitize [attribute]+ Removes all but the specified attributes from the cookie.
HTTP::cookie exists Returns a true value if the cookie exists.
Commands for response messages
HTTP::cookie names Returns the names of all the cookies present in the HTTP header.
HTTP::cookie count Returns the number of cookies present in the HTTP header.
HTTP::cookie [value] [string] Sets or gets the cookie value of the given name. You can omit the value of this command if the cookie name does not collide with any of the other commands.
HTTP::cookie version [version] Sets or gets the version of the cookie.
HTTP::cookie path [path] Sets or gets the cookie path.
HTTP::cookie domain [domain] Sets/Gets the cookie domain.
HTTP::cookie ports [portlist] Sets/Gets the cookie port lists for Version 1 cookies.
HTTP::cookie insert [path] [domain][version] Adds or replaces a cookie. The default value for the version is 0. cookies.
HTTP::cookie remove Removes a cookie.
HTTP::cookie maxage [seconds] Sets or gets the max-age. Applies to Version 1 cookies only.
HTTP::cookie expires [seconds] [absolute | relative] Sets or gets the expires attribute. Applies to Version 0 cookies only. If you specify the absolute argument, the seconds value represents number of seconds since the UNIX epoch (January 1, 1970). The default number of seconds is relative, which is the number of seconds from the current time.
HTTP::cookie comment [comment] Sets or gets the cookie comment. Applicable only to Version 1 cookies.
HTTP::cookie secure [enable|disable] Sets or gets the secure attribute. Applicable only to Version 1 cookies.
HTTP::cookie commenturl [commenturl] Sets or gets the comment URL. Applicable only to Version 1 cookies.
HTTP::cookie discard [enable|disable] Sets or gets the discard attribute. Applicable only to Version 1 cookies.
HTTP::cookie sanitize [attribute]+ Removes from the cookie all but the attributes you specify.
HTTP::cookie exists Returns a true value if the cookie exists.
HTTP::cookie encrypt ["128" | "192" | "256"] Encrypts the value for the given cookie using a key generated from the pass phrase. The default key length is 128.
HTTP::cookie decrypt ["128" | "192" | "256"] Decrypts the value for the given cookie using a key generated from the pass phrase. The default key length is 128.

Manipulating SSL headers and content

SSL data manipulation commands that you can use within iRules fall into two categories:

  • Commands to manipulate SSL query results
  • Commands to change settings or invoke action

The following two sections describe these commands.

Manipulating SSL query results

The iRules feature includes SSL commands that manipulate the results of SSL query commands. Table 6 shows these commands.

iRule Command Description
X509::version Returns the version number of the X509 certificate (an integer).
X509::serial_number Returns the serial number of the X509 certificate (an integer).
X509::signature_algorithm Returns the signature algorithm of the X509 certificate.
X509::issuer Returns the issuer of the X509 certificate.
X509::not_valid_before Returns the not-valid-before date of the X509 certificate.
X509::not_valid_after Returns the not-valid-after date of the X509 certificate.
X509::subject Returns the subject of the X509 certificate.
X509::subject_public_key_type Returns the subject's public key type of the X509 certificate. The value can be either RSA, DSA, or unknown.
X509::subject_public_key Returns the subject's public key of the X509 certificate.
X509::subject_public_key_RSA_bits Returns the size in bits of the subject's public RSA key of the X509 certificate. This command is only applicable when the public key type is RSA, and generates an error otherwise.
X509::extensions Returns the X509 extensions set on the certificate.
X509::whole Returns the entire X509 certificate in PEM format.
X509::hash Returns the MD5 hash (fingerprint) of the X509 certificate.
X509::verify_cert_error_string Returns the same result as the OpenSSL function X509_verify_cert_error_string(). The argument uses the same values as those that the SSL::verify result command returns.
X509::cert_fields {options} Returns a list of fields to be added to the HTTP headers in order to emulate ModSSL behavior. The return type is a Tcl list that the system then interprets as a header name/header value pair.

Changing SSL settings or invoking actions

Table 7 lists and describes a set of SSL commands that you can use to change SSL settings or invoke actions.

iRule Command Description
SSL::renegotiate This command has different results depending on whether the BIG-IP evaluates the command under a client-side or a server-side context. The command only succeeds if SSL is enabled on the connection; otherwise, the command returns an error. When the system evaluates the command under a client-side context, the system immediately renegotiates a request for the associated client-side connection, using the configuration options for forced SSL renegotiations. This renegotiation enforces any SSL settings changed for the connection including client certificate settings. When the system evaluates the command under a server-side context, the system immediately initiates a renegotiation for the associated server-side connection, using the configuration options for forced SSL renegotiations.
SSL::cert mode <"request" | "require" | "ignore" | "auto"> This command has different results depending on whether the system evaluates the command under a client-side or server-side context. When the system evaluates the command under a client-side context, the command overrides the client-side SSL connection's current setting regarding client certificates. When the system evaluates the command under a server-side context, the command overrides the server-side SSL connection's current setting regarding server certificates. Only the require or ignore arguments are valid in this instance.
SSL::authenticate <"once" | "always"> This command is only valid in a client-side context. The command overrides the client-side SSL connection's current setting regarding authentication frequency.
SSL::authenticate depth This command has different results depending on whether it is evaluated under a client-side or server-side context. When the system evaluates the command under a client-side context, the command overrides the client-side SSL connection's current setting regarding maximum certificate chain traversal depth. When the system evaluates the command under a server-side context, the command overrides the server-side SSL connection's current setting regarding maximum certificate chain traversal depth.
SSL::unclean shutdown <"enable" | "disable"> This command has different results depending on whether it is evaluated under a client-side or server-side context. When the system evaluates the command under a client-side context, the command overrides the client-side SSL connection's current setting regarding unclean shutdowns. When the system evaluates the command under a server-side context, the command overrides the server-side SSL connection's current setting regarding unclean shutdowns.
SSL::verify result Sets the result code for peer certificate verification. The argument uses the same values as those that the SSL::verify result command returns.
SSL::handshake hold Halts any SSL activity upon authentication.
SSL::handshake resume Resumes any SSL activity that the system previously halted with the SSL::handshake hold command.