HTTP Variables

HTTP variables retrieves request and response metadata. Use this metadata to dynamically alter a request or a response.

Key information:

• HTTP variables requires Rules Engine - Advanced Rules. This component of Rules Engine must be purchased separately. Contact your CDN account manager to activate it.

• The following features support HTTP variables:

  Name	Type
  Cache-Key Rewrite	Feature
  Modify Client Request Header	Feature
  Modify Client Response Header	Feature
  URL Redirect	Feature
  URL Rewrite	Feature

This article covers the following HTTP variable-related concepts:

• Definitions

• Usage

  • Delimiter Quick Reference
  • Exceptions
  • Setting Default Header Values
  • Manipulating Variables

Definitions

The following table describes all supported HTTP variables.

A blank value is returned when GEO metadata (e.g., postal code) is unavailable for a particular request.

Name	Variable	Description	Sample Value
ASN (Requester)	%{geo_asnum}	Indicates the requester's AS number. Deprecated: %{virt_dst_asnum}The %{virt_dst_asnum} variable has been deprecated in favor of %{geo_asnum}. Although rules that use this deprecated variable will continue to work, we strongly recommend that they be updated to use the new variable.	AS15133
City (Requester)	%{geo_city}	Indicates the requester's city.	Los Angeles
Continent (Requester)	%{geo_continent}	Indicates the requester's continent through its abbreviation. Valid values are: AF: Africa AS: Asia EU: Europe NA: North America OC: Oceania SA: South America Deprecated: %{virt_dst_continent}The %{virt_dst_continent} variable has been deprecated in favor of %{geo_continent}. Although rules that use this deprecated variable will continue to work, we strongly recommend that they be updated to use the new variable.	NARepresents North America.
Cookie Value	%{cookie_CookieReplace this term with the name of the desired cookie.}	Returns the value corresponding to the cookie identified by the Cookie term.	Sample Usage: %{cookie__utma} Sample Value: 111662281.2.10.1222100123
Country (Requester)	%{geo_country}	Indicates the requester's country of origin through its country code. Deprecated: %{virt_dst_country}The %{virt_dst_country} variable has been deprecated in favor of %{geo_country}. Although rules that use this deprecated variable will continue to work, we strongly recommend that they be updated to use the new variable.	US
Designated Market Area (Requester)	%{geo_dma_code}	Indicates the requester's media market by its region code. This field is only applicable to requests that originate from the United States.	745
HTTP Request Method	%{request_method}	Indicates the HTTP request method.	GET
HTTP Status Code	%{status}	Indicates the HTTP status code for the response.	200
IP Address (Requester)	%{virt_dst_addr}	Indicates the requester's IP address.	192.168.1.1
Latitude (Requester)	%{geo_latitude}	Indicates the requester's latitude.	34.0995
Longitude (Requester)	%{geo_longitude}	Indicates the requester's longitude.	-118.4143
Metropolitan Statistical Area (Requester)	%{geo_metro_code}	Indicates the requester's metropolitan area. This field is only applicable to requests that originate from the United States.	745
Normalized Path	%{normalized_path}	Indicates the normalized relative path for the request submitted to the CDN. Key information: This relative path excludes the query string. This relative path corresponds to the request submitted to the CDN and it does not reflect URL rewrites. URL normalization, as defined in RFC 3986, was applied to this value.	/800001/corigin/directory/foo.js
Normalized Query String	%{normalized_query}	Indicates the normalized query string defined in the request URL. URL normalization, as defined in RFC 3986, was applied to this value.	Original query string: "client=/123?" Normalized query string: %22client=/123?%22
Normalized URI	%{normalized_uri}	Indicates the normalized relative path and query string for the request submitted to the CDN. Key information: This relative path corresponds to the request submitted to the CDN and it does not reflect URL rewrites. URL normalization, as defined in RFC 3986, was applied to this value.	/800001/corigin/dir/foo.js?%22client=/123?%22
Path	%{path}	Indicates the relative path to the requested content. Key information: This relative path excludes the query string. This relative path reflects URL rewrites. A URL will be rewritten under the following conditions: URL Rewrite Feature: This feature rewrites the relative path defined in the request URI. Edge CNAME URL: This type of request is rewritten to the corresponding CDN URL.	/800001/corigin/rewrittendir/foo.js
Port (Requester)	%{virt_dst_port}	Indicates the requester's ephemeral port.	55885
Postal Code (Requester)	%{geo_postal_code}	Indicates the requester's postal code. We only return the first 3 characters for Canadian postal codes. We only return the first 2 - 4 characters for United Kingdom postal codes.	90210
Query String Found	%{is_args}	The value for this variable varies according to whether the request contains a query string. Query String Found: ? No Query String: NULL	?
Query String Parameter Found	%{is_amp}	The value for this variable varies according to whether the request contains at least one query string parameter. Parameter Found: & No Parameters: NULL	&
Query String Parameter Value	%{arg_ParameterReplace this term with the name of the desired query string parameter.}	Returns the value corresponding to the query string parameter identified by the Parameter term.	Sample Usage: %{arg_language} Sample Query String Parameter: ?language=en Sample Value: en
Query String Value	%{query_string}	Indicates the entire query string value defined in the request URL.	key1=val1&key2=val2&key3=val3
QUIC Versions	%{quic_altsvc_versions}	Indicates the set of QUIC versions supported by our CDN service. This variable identifies QUIC versions using Google's latest specification. Learn more.	h3-Q049=":443"; ma=2592000,h3-Q048=":443"; ma=2592000,h3-Q046=":443"; ma=2592000,h3-Q043=":443"; ma=2592000
QUIC Versions (Legacy)	%{quic_versions}	Indicates the set of QUIC versions supported by our CDN service. This variable identifies QUIC versions using Google's legacy specification. Learn more.	43,41,39,35
Referrer Domain	%{referring_domain}	Indicates the domain defined in the Referer request header.	www.google.com
Region (Requester)	%{geo_region}	Indicates the requester's region (e.g., state or province) through its alphanumeric abbreviation. The behavior of this variable is identical to the Region Code match condition.	CARepresents California, USA.
Request Header Value	%{http_Request HeaderReplace this term with the name of the desired request header.}	Returns the value corresponding to the request header identified by the Request Header term.	Sample Usage: %{http_Connection} Sample Value: Keep-Alive
Request Host	%{host}	Indicates the host defined in the request URL.	www.mydomain.com
Request ID	%{http_x_ec_uuid}	Indicates a request's unique system-defined ID. A new ID is generated whenever a client (i.e., user agent) submits a request.	1234567890...12345678901234567890123456789012345678
Request Protocol (Client)	%{virt_http_version}	Indicates the version of the client's request protocol.	2.0
Request Protocol (Edge Server)	%{request_protocol}	Indicates the request protocol used by an edge server to proxy the request.	HTTP/1.1
Request Scheme	%{scheme}	Indicates the request scheme.	http
Request URI	%{request}	Describes the request. Syntax: HTTP MethodIndicates the HTTP method that was requested. Relative PathIndicates the relative path, including query string parameters, defined in the request URI. ProtocolIndicates the HTTP protocol and version that was requested.	GET /marketing/foo.js?loggedin=true HTTP/1.1
Request URI (Relative without query string)	%{uri}	This variable has been deprecated. Please update your configurations to use %{path} instead. Indicates the relative path to the requested content. Key information: This relative path excludes the query string. This relative path reflects URL rewrites. A URL will be rewritten under the following conditions: URL Rewrite Feature: This feature rewrites the relative path defined in the request URI. Edge CNAME URL: This type of request is rewritten to the corresponding CDN URL.	/800001/corigin/rewrittendir/foo.js
Request URI (Relative)	%{request_uri}	Indicates the relative path, including the query string, defined in the request URI.	/marketing/foo.js?loggedin=true
Response Header Value	%{resp_Response HeaderReplace this term with the name of the desired response header.}	Returns the value corresponding to the response header identified by the ResponseHeader term. Requests cannot be defined using variables associated with response metadata. For example, this variable cannot be used to define a request header via the Modify Client Request Header feature.	Sample Usage: %{resp_Content_Length} Sample Value: 100
Session ID	%{http_x_ec_session_id}	Indicates a unique system-defined ID for the request's connection to our servers. Multiple rapid requests by a single client may result in a single session ID when the connection is reused for those requests. Use Request ID if you require a unique ID for each request.	1234567890...12345678901234567890123456789012345678
SSL/TLS Cipher Suite	%{virt_ssl_cipher}	Indicates the name of the cipher suite used to secure a HTTPS connection.	ECDHE-RSA-AES256-SHA
SSL/TLS Protocol	%{virt_ssl_protocol}	Indicates the SSL/TLS protocol used to secure a HTTPS connection.	TLSv1.2

Usage

The following table describes the proper syntax for specifying an HTTP variable.

Syntax	Example	Description
%{HTTP VariableReplace this term with the desired HTTP variable.}	%{host}	Use this syntax to get the entire value corresponding to the specified HTTP variable.
%{HTTP VariableDelimiterReplace this term with the desired delimiter (i.e., ^ and ,).}	%{host,}	Use this syntax to set the case for the entire value corresponding to the specified HTTP variable.
%{HTTP VariableDelimiterExpressionReplace this term with the desired regular expression.}	%{host/=^www\.([^\.]+)\.([^\.:]+)/cdn.$2.$3:80}	Use regular expressions to replace, delete, or manipulate an HTTP variable's value.

HTTP variable names only support alphabetic charactersa - z and underscores_. Please convert unsupported characters to underscores.

Delimiter Quick Reference

A delimiter can be specified after an HTTP variable to achieve any of the following effects:

• Transform the value associated with the variable.

  Example:

  Convert the entire value to lower-case.

• Delete the value associated with the variable.

• Manipulate the value associated with the variable.

  Example:

  Use regular expressions to change the value associated with the HTTP variable.

A brief description for each delimiter is provided below.

Delimiter	Description
:=	Indicates that a default value will be assigned to the variable when it is either: Missing Set to NULL.
:+	Indicates that a default value will be assigned to the variable when a value has been assigned to it.
:	Indicates that a substring of the value assigned to the variable will be expanded.
#	Indicates that the pattern specified after this delimiter should be deleted when it is found at the beginning of the value associated with the variable.
%	Indicates that the pattern specified after this delimiter should be deleted when it is found at the end of the value associated with the variable. The above definition is only applicable when the % symbol is used as a delimiter.
/	Delimits an HTTP variable or a pattern.
//	Find and replace all instances of the specified pattern.
/=	Find, copy, and rewrite all occurrences of the specified pattern.
,	Convert the value associated with the HTTP variable to lower-case.
^	Convert the value associated with the HTTP variable to upper-case.
,,	Convert all instances of the specified character in the value associated with the HTTP variable to lower-case.
^^	Convert all instances of the specified character in the value associated with the HTTP variable to upper-case.

Exceptions

The following table describes circumstances under which the specified text will not be treated as an HTTP variable.

Condition	Description	Example
Escaping % Symbol	The percentage symbol can be escaped through the use of a backslash. The sample value to the right will be treated as a literal value and not as an HTTP variable.	\%{host}
Unknown Variables	An empty string is always returned for unknown variables.	%{unknownvariable}
Invalid Characters or Syntax	Variables that contain invalid characters or syntax are treated as literal values. Example #1: The specified value contains an invalid character (i.e., -). Example #2: The specified value contains a double set of curly braces. Example #3: The specified value is missing a closing curly brace.	Example #1: %{resp_user-agent} Example #2: %{{host}} Example #3: %{host
Missing Variable Name	A NULL value is always returned when a variable is not specified.	%{}
Trailing Characters	Characters that trail a variable are treated as literal values. The sample value to the right contains a trailing curly brace that will be treated as a literal value.	%{host}}

Setting Default Header Values

A default value can be assigned to a header when it meets any of the following conditions:

• Missing/unset
• Set to NULL.

The following table describes how to define a default value.

Condition	Syntax	Example	Description
Set a header to a default value when it meets any of the following conditions: Missing Header Header value is set to NULL.	%{VariableRepresents the name of a variable.:=ValueRepresents the default value that will be assigned to the specified variable when one or more prerequisite conditions have been met.}	%{http_referer:=unspecified}	The Referer header will only be set to "unspecified" when it is either missing or set to NULL. No action will take place if it has been set.
Set a header to a default value when it is missing.	%{VariableRepresents the name of a variable.=ValueRepresents the default value that will be assigned to the specified variable when one or more prerequisite conditions have been met.}	%{http_referer=unspecified}	The Referer header will only be set to "unspecified" when it is missing. No action will take place if it has been set.
Set the header to a default value when it does not meet any of the following conditions: Missing Set to NULL.	%{VariableRepresents the name of a variable.:+ValueRepresents the default value that will be assigned to the specified variable when one or more prerequisite conditions have been met.}	%{http_referer:+unspecified}	The Referer header will only be set to "unspecified" when a value has been assigned to it. No action will take place if it is either missing or set to NULL.

Manipulating Variables

Variables can be manipulated in the following ways:

• Expanding substrings
• Removing patterns

Substring Expansion

By default, a variable will expand to its full value. Use the following syntax to only expand a substring of the variable's value.

Key information:

• The value assigned to the Offset term determines the starting character of the substring.

  • Positive: The starting character of the substring is calculated from the first character in the string.
  • Zero: The starting character of the substring is the first character in the string.
  • Negative: The starting character of the substring is calculated from the last character in the string.

• The length of the substring is determined by the Length term.

  • Omitted: Omitting the Length term allows the substring to include all characters between the starting characteras defined by the Offset term and the end of the string.
  • Positive: Determines the length of the substring from the starting characteras defined by the Offset term to the right.
  • Negative: Determines the length of the substring from the starting characteras defined by the Offset term to the left.

Example:

This example relies on the following sample request URL:

The following string demonstrates various methods for manipulating variables:

Based on the sample request URL, the above variable manipulation will produce the following value:

Pattern Removal

Text that matches a specific pattern can be removed from either the beginning or the end of a variable's value.

Syntax	Action
%{VariableReplace this term with any supported HTTP variable.#PatternReplace this term with the pattern for the text that will be removed.}	Remove text when the specified pattern is found at the beginning of a variable's value.
%{VariableReplace this term with any supported HTTP variable.%PatternReplace this term with the pattern for the text that will be removed.}	Remove text when the specified pattern is found at the end of a variable's value.

Example:

In this sample scenario, we will assume that the request_uri variable is set to:

The following table demonstrates how this syntax works.

Sample Syntax	Result	Explanation
%{request_uri#/800001}/customerorigin	/customerorigin/myorigin/marketing/product.html?language=en-US	The variable starts with the pattern/800001 and therefore it was replaced.
%{request_uri%html}htm	/800001/myorigin/marketing/product.html?language=en-US	The variable does not end with the patternhtml and therefore no change took place.

Find And Replace

Find and replace syntax is described below.

Syntax	Action
%{VariableReplace this term with any supported HTTP variable./FindReplace this term with the pattern for the text that will be replaced./ReplaceReplace this term with the new value that will replace the old value.}	Find and replace first occurrence of the specified pattern.
%{VariableReplace this term with any supported HTTP variable.//FindReplace this term with the pattern for the text that will be replaced./ReplaceReplace this term with the new value that will replace the old value.}	Find and replace all occurrences of the specified pattern.
%{VariableReplace this term with any supported HTTP variable.^}	Convert the entire value to upper-case.
%{VariableReplace this term with any supported HTTP variable.^FindReplace this term with the pattern for the text that will be replaced.}	Convert the first occurrence of the specified pattern to upper-case.
%{VariableReplace this term with any supported HTTP variable.,}	Convert the entire value to lower-case.
%{VariableReplace this term with any supported HTTP variable.,FindReplace this term with the pattern for the text that will be replaced.}	Convert the first occurrence of the specified pattern to lower-case.

Find and Rewrite

A variation on find and replace is to use the text that matches the specified pattern when rewriting it. Find and rewrite syntax is described below.

Syntax	Action
%{VariableReplace this term with any supported HTTP variable./=FindReplace this term with the pattern for the text that will be replaced./RewriteReplace this term with the value that will replace the "Find" pattern. This value can consist of any combination of plain text and pattern placeholders (e.g., $1).}	Find, copy, and rewrite all occurrences of the specified pattern.
%{VariableReplace this term with any supported HTTP variable./^FindReplace this term with the pattern for the text that will be replaced./RewriteReplace this term with the value that will replace the "Find" pattern. This value can consist of any combination of plain text and pattern placeholders (e.g., $1).}	Find, copy, and rewrite the specified pattern when it occurs at the start of the variable.
%{VariableReplace this term with any supported HTTP variable./$FindReplace this term with the pattern for the text that will be replaced./RewriteReplace this term with the value that will replace the "Find" pattern. This value can consist of any combination of plain text and pattern placeholders (e.g., $1).}	Find, copy, and rewrite the specified pattern when it occurs at the end of the variable.
%{VariableReplace this term with any supported HTTP variable./FindReplace this term with the pattern for the text that will be deleted}	Find and delete all occurrences of the specified pattern.

Key information:

• Expand text that matches the specified pattern by specifying a dollar sign followed by a whole integer (e.g., $1).

• Multiple patterns may be specified. The order in which the pattern is specified determines the integer that will be assigned to it. In the following example, the first pattern matches www or www followed by a single digit, the second pattern matches the second-level domain, and the third pattern matches the top-level domain.

  %{host/=^(www\d?)\.([^\.]+)\.([^\.:]+)/cdn.$2.$3:80}

• The rewritten value can consist of any combination of text and these placeholders.

  In the above example, the hostname will be rewritten according to this pattern: cdn.$2.$3:80 (e.g., cdn.mydomain.com:80).

• The case of a pattern placeholder (e.g., $1) can be modified through the following flags:

  • U: Upper-case the expanded value.

    Sample syntax:

    %{host/=^(www\d?)\.([^\.]+)\.([^\.:]+)/cdn.$U2.$3:80}

  • L: Lower-case the expanded value.

    Sample syntax:

    %{host/=^(www\d?)\.([^\.]+)\.([^\.:]+)/cdn.$L2.$3:80}

• An operator must be specified before the pattern. The specified operator determines the pattern capturing behavior:

  • =: Indicates that all occurrences of the specified pattern must be captured and rewritten.
  • ^: Indicates that only text that starts with the specified pattern will be captured.
  • $: Indicates that only text that ends with the specified pattern will be capture.
• Omitting the /Rewrite value will result in the deletion of the text that matches the pattern.

Edgecast CDN