Querying Header or Content Data

The iRules feature includes several commands that are specifically designed to allow you to run queries on the following:

  • Link Layer headers
  • IP headers
  • TCP headers and content
  • UDP headers and content
  • SSL headers in HTTP requests
  • Authentication data

Querying Link Layer headers

You can select a pool by specifying Link Layer header information. Table 1 lists and describes these commands.

iRule Command Description
LINK::vlan_id Returns the VLAN tag of the packet.
LINK::vlan_qos Returns the VLAN Quality of Service (QoS) value of the packet.

Quality of Service (QoS) level

The Quality of Service (QoS) standard is a means by which network equipment can identify and treat traffic differently based on an identifier. As traffic enters the site, the LTM system can apply an iRule that sends the traffic to different pools of servers based on the QoS level within a packet.

To configure an iRule to select a pool based on the QoS level of a packet, you can use the LINK::vlan_qos iRule command, as you can see in the example in Figure 2.

iRule my_iRule 
when CLIENT_ACCEPTED{
  if { [LINK::vlan_qos] > 2 } {
    pool fast_pool
  } else {
    pool slow_pool
  }
}

Querying IP packet headers

You can select a pool by querying for IP packet header information. Table 3 lists and describes these commands.

iRule Command Description
IP::remote_addr Returns the remote IP address of a connection.
IP::local_addr Returns the local IP address of a connection.
IP::client_addr Returns the client IP address of a connection. This command is equivalent to the command clientside { IP::remote_addr }.
IP::server_addr Returns the server's IP address. This command is equivalent to the command
serverside { IP::remote_addr }.
IP::protocol Returns the IP protocol value.
IP::tos Returns the value of the IP protocol's Type of Service (ToS) field.
IP::idle_timeout Returns or sets the idle timeout value.

As you can see by the preceding table, the specific types of IP packet header data that you can query for within an iRule are:

  • IP addresses
  • Protocol numbers
  • ToS levels
  • Idle timeout values

Specifying an IP address

You can specify the IP::remote_addr or IP::local_addr command within an iRule to select a pool. For example, you can load balance traffic based on part of the client's IP address. You can also specify the IP::client_addr and IP::server_addr commands.

Figure 4 shows an iRule that implements the preceding statements. In this example, all client requests with the first byte of their source address equal to 206 are directed to a pool named clients_from_206 pool. All other requests are directed to a pool named other_clients_pool.

Figure 4: An iRule based on the IP::local_addr command

iRule clients_from_206_iRule 
when CLIENT_ACCEPTED{
  if { [IP::local_addr] equals 206.0.0.0 netmask 255.0.0.0 } {
    pool clients_from_206
  } else { 
    pool other_clients_pool
  }
}

Specifying an IP protocol number

The LTM system includes an iRule command, IP::protocol, that you can use to select a pool based on an IP protocol number.

To configure an iRule to select a pool based on an IP protocol number, use the syntax shown in the example in Figure 5.

iRule my_iRule 
when CLIENT_ACCEPTED{{
  if { [IP::protocol] == 6 } {
    pool tcp_pool
  } else {
    pool slow_pool
  }
}

Specifying a Type of Service (ToS) level

The Type of Service (ToS) standard is a means by which network equipment can identify and treat traffic differently based on an identifier. As traffic enters the site, the LTM system can apply an iRule that sends the traffic to different pools of servers based on the ToS level within a packet.

The command that you use to set the ToS level on a packet is IP::tos.

To configure an iRule to select a pool based on the ToS level of a packet, you can use the IP::tos iRule command, as shown in the example in Figure 6.

Figure 6: An iRule based on a Type of Service (ToS) level

iRule my_iRule 
when CLIENT_ACCEPTED{{
  if { [IP::tos] == 16 ) {
    pool telnet_pool
  } else {
    pool slow_pool
  }
}

Specifying an idle timeout value

Using the IP::idle_timeout command within an iRule, you can specify an idle timeout value as the criteria for selecting the pool to which you want the LTM system to send traffic.

Querying UDP headers and content

You can select a pool by specifying UDP header or content information. Table 7 lists and describes these commands.

iRule Command Description
UDP::remote_port Returns the remote's UDP port/service number.
UDP::local_port Returns the local UDP port/service number.
UDP::client_port Returns the client's UDP port/service number. Equivalent to the command clientside { UDP::remote_port }.
UDP::server_port Returns the server UDP port/service number. Equivalent to the command serverside { UDP::remote_port }.
UDP::payload [] Returns the current UDP payload content.
UDP::payload length Returns the amount of UDP payload content in bytes.

Querying TCP headers and content

You can select a pool by specifying TCP header or content information. Table 8 lists and describes these commands.

iRule Command Description
TCP::remote_port Returns the remote TCP port/service number.
TCP::local_port Returns the local TCP port/service number.
TCP::client_port Returns the client's TCP port/service number. Equivalent to the command clientside { TCP::remote_port }.
TCP::server_port Returns the server TCP port/service number. Equivalent to the command serverside { TCP::remote_port }.
TCP::payload [] Returns the accumulated TCP data content.
TCP::payload_length Returns the amount of accumulated TCP data content in bytes.
TCP::rtt Returns the smoothed round-trip time estimate for a TCP connection.
TCP::mss Returns the on-wire Maximum Segment Size (MSS) for a TCP connection.
TCP::unused_port Returns an unused TCP port for the specified IP tuple, using the value of as a starting point.
TCP::offset Returns the position in the TCP data stream in which the collected TCP data starts.

For example, you might want an iRule that logically states: "If the packet data contains a TCP request containing the string XYZ, then load balance using the pool xyz_servers. If the string is not found, search for the string ABC at the specified offset and load balance using the pool abc_servers. If the string ABC is not found, load balance using the pool web_servers".

To accomplish this, you can write an iRule using the TCP::payload command. Figure 9 shows an iRule that illustrates this example.

iRule my_iRule 
when CLIENT_DATA{{ 
  if { [TCP::payload []] contains "XYZ" } {
pool xyz_servers
} elseif { [substr[TCP::payload [] [](100), 50, 3] == "ABC" {
pool abc_servers
} else {
pool web_servers
}
}

Querying HTTP headers and content

You can select a destination by specifying HTTP header or content information. Table 10 lists and describes these commands. Note that this list does not include commands for querying SSL-related headers in HTTP requests.

iRule commands for querying HTTP headers and content

iRule Command Description
HTTP::header [value] Returns value of the HTTP header named . You can omit the argument if the header name does not collide with any of the subcommands.
HTTP::header names Returns a list of all the headers present on the request or response.
HTTP::header count Returns the number of HTTP headers present on the request or response.
HTTP::header at Returns the HTTP header that the system finds at the zero-based index value.
HTTP::header exists Returns true if the named header is present on the request or response.
HTTP::method Returns the type of HTTP request method.
HTTP::status Returns the response status code.
HTTP::version ["0.9" | "1.0" | "1.1"] Returns the HTTP version of the request or response.
HTTP::username Returns the user name part of the HTTP basic authorization.
HTTP::password Returns the password part of the HTTP basic authorization.
HTTP::path [] Returns the path part of the HTTP request.
HTTP::uri [] Returns the complete URI of the request.
HTTP::query [] Returns the query part of the HTTP request.
HTTP::is_redirect Returns a true value if the response is a certain type of redirect.
HTTP::is_keepalive Returns a true value if this is a Keep-Alive connection.
HTTP::collect [] Collects the amount of data that you specify with the [length] argument. When the system collects the specified amount of data, it calls the Tcl event HTTP_REQUEST_DATA or HTTP_RESPONSE_DATA. Use great caution when omitting the value of the content length. Even though this is allowed in certain cases; doing so or using a value larger than the size of the actual length can stall the connection.
HTTP::release Releases the collected data. There is no need to use the HTTP::release command inside of the HTTP_REQUEST_DATA and HTTP_RESPONSE_DATA events, since in these cases, the data is implicitly released.
HTTP::payload [] Returns the content that the HTTP::collect command has collected thus far. If you do not specify a size, the system returns the collected content.
HTTP::payload length Returns the size of the content that the command has collected thus far, not including the HTTP headers.
HTTP::payload replace Replaces the amount of content that you specified with the argument, starting at with .
HTTP::close Inserts a Connection: Close header and close the HTTP connection.
URI::protocol Extracts the protocol part from the URI string that you specify.
URI::basename Extracts the basename part from the URI string that you specify.
URI::path Extracts the path from the URI string that you specify.
URI::query Extracts the query part from the URI string that you specify.
URI::host Extracts the host part from the URI string that you specify.
URI::compare Compares URIs as recommended by RFC 2616 section 3.2.3.
URI::decode Returns the decoded URI string.
URI::encode Returns the encoded URI string
URI::port Extracts the port part from the URI string that you specify.

For example, you may want an iRule that logically states: "If the packet data contains an HTTP request with a URI ending in cgi, then load balance using the pool cgi_pool. Otherwise, if the packet data contains an HTTP request with a URI starting with /foo, then load balance using the pool foo_servers. Otherwise, load balance using the pool default_pool".

Figure 11 shows an iRule that illustrates this example.

iRule cgi_iRule 
when HTTP_REQUEST { 
  if { [HTTP::uri] ends_with "cgi" } { 
    pool cgi_pool 
  } 
  elseif { [HTTP::uri] starts_with "/foo" } { 
    pool foo_servers 
  } 
} 

Querying SSL headers of HTTP requests

You can select a destination based on data that resides in the SSL headers of an HTTP request. Table 12 lists and describes these commands.

iRule Command Description
SSL::mode In a client-side context, returns one of require, request, ignore, or auto. In a server-side context, returns one of require or ignore.
SSL::cert Returns the index of the X509 SSL certificate in the peer certificate chain, where index is a value greater than or equal to zero. A value of zero denotes the first certificate in the chain, a value of one is the next, and so on. This command is currently applicable only under a client-side context and returns an error within a server-side context.
SSL::cert issuer Returns the issuer certificate of the index of the X509 SSL certificate in the peer certificate chain, where index is a value greater than or equal to zero. A value of zero denotes the first certificate in the chain, a value of one is the next, and so on. This command is currently applicable only under a client-side context and returns an error within a server-side context.
SSL::cert count Returns the total number of certificates that the peer has offered.
SSL::verify_result Returns the result code from peer certificate verification using the same values as the OpenSSL SSL_get_verify_result() function.
SSL::cipher name Returns the current SSL cipher version using the format of the OpenSSL SSL_CIPHER_get_version() function.
SSL::cipher version Returns the current SSL cipher version using the format of the OpenSSL SSL_CIPHER_get_version() function.
SSL::cipher bits Returns the number of secret bits that the current SSL cipher used, using the format of the OpenSSL SSL_CIPHER_get_bits() function
SSL::SSL::current_sessionid Returns the SSL session ID currently negotiated, or a value of -1, if no session ID exists.
SSL::modssl_sessionid_headers [+] Returns a list of fields that the system is to add 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. The options that you can specify with this command are initial and current.

Querying authentication data

You can select a destination based on authentication data. Table 13 lists and describes these commands.

iRule Command Description
AUTH::wantcredential_prompt Returns the authorization session authid's credential prompt string that the system last requested (when the system generated an AUTH_WANTCREDENTIAL event), for example, Username:. This command is especially helpful in providing authentication services to interactive protocols (for example, telnet and ftp), where the actual text prompts and responses may be directly communicated with the remote user.
AUTH::wantcredential_prompt_style Returns the authorization session authid's credential prompt style that the system last requested (when the system generated an AUTH_WANTCREDENTIAL event). This value is either echo_on, echo_off, or unknown. This command is especially helpful in providing authentication services to interactive protocols (or example, telnet and ftp), where the actual text prompts and responses may be directly communicated with the remote user.
AUTH::wantcredential_type Returns the authorization session authid's credential type that the system last requested (when the system generated an AUTH_WANTCREDENTIAL event ). This value is either username, password, x509, x509_issuer, or unknown, based upon the system's assessment of the credential prompt string and style.
AUTH::status Returns a value of success, failure, error, or not-authed, based on the result of the most recent authorization that the system performed for the authorization session authid.
AUTH::ssl_cc_ldap_username Returns the user name that the system retrieved from the LDAP database from the last successful client certificate-based LDAP query for the authorization session authid. The system returns an empty string if the last successful query did not perform a successful client certificate-based LDAP query, or if no query has yet been performed.
AUTH::ssl_cc_ldap_status Returns the status from the last successful client certificate-based LDAP query for the authorization session authid. The system returns an empty string if the last successful query did not perform a client certificate-based LDAP query, or if no query has yet been performed.