When you configure certain CDN features, such as modifying outgoing response headers or request headers, you can use variables to get the context of the current request or response. Variables return values such as the request method, URL, and client IP address, which enables fine-grained control. This topic describes all variables that CDN supports, with example values and usage notes for each variable.
Variable overview
CDN variables are grouped by effective domain into access domain variables, origin fetch domain variables, and response variables:
Access domain variables: Variables that take effect in the access domain, where the CDN node processes client requests and generates the cache key.
Origin fetch domain variables: Variables that take effect during origin fetch. Some features are deployed on the origin fetch domain module. In this case, access domain variables do not take effect and must be replaced with origin fetch domain variables.
Response variables: You can use these variables to get the response headers that the origin server returns to the CDN node.
The following table lists the variable groups and variables in each effective domain:
Effective domain | Variable group | Variables |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The access domain |
| |
The origin fetch domain |
| |
The origin fetch domain |
| |
Response variables |
|
Features that support variables
Features in the access domain
Features in the origin fetch domain
Limits
Before you reference a variable, check the following conditions and limits that apply across variables:
SSL/TLS variables apply only to HTTPS requests. Their values are empty when these variables are referenced in HTTP requests.
$ssl_client_*variables have values only when client certificate verification (mutual authentication, or mTLS) is configured. Their values are empty for standard HTTPS requests.GeoIP resolution has accuracy limits. City-level and longitude/latitude fields generally identify the city center and are not suitable for blocking use cases that require precise geofencing. When a client IP address cannot be identified, the related fields return default values (for example, the country code returns
XX, and numeric code values return0).$urimight be changed by internal CDN request-routing logic, such as redirection or internal rewrite. This variable is not recommended. To get an unchanged path, use$raw_uri.
Header variable naming conventions
When CDN processes HTTP request headers and response headers, it automatically maps them to internal variables. The variable names must follow these rules:
Fixed prefix: All request header variables must start with
$http_, and all response header variables must start with$sent_http_.Lowercase conversion: All uppercase letters in a header name must be converted to lowercase.
Hyphen replacement: All hyphens (
-) in a header name must be replaced with underscores (_).
Conversion examples:
Original header name | Converted variable |
Accept-Language |
|
X-Forwarded-For |
|
X-Customize-Header |
|
Variables in the access domain
Request method
$request_method
Meaning: The HTTP request method used by the current request.
Example values:
GET,POST,HEAD,PUT,DELETE, and more.
HTTP version
$server_protocol
Meaning: The HTTP protocol version used by the current request.
Example values:
HTTP/1.1andHTTP/2.0.
URI
$uri
Meaning: The URL path of the current request, excluding query parameters.
Example value:
/1.txt.Note: This value might be changed by internal CDN request-routing logic, such as redirection or internal rewrite. This variable is not recommended. To get an unchanged path, use
$raw_uri.
$raw_uri
Meaning: The URL path of the original request, excluding query parameters. Internal CDN request-routing logic does not change this value.
Example value:
/1.txt.
$request_uri
Meaning: The complete URL path of the original request, including query parameters.
Example value:
/1.txt?chapter=1&flag=on.
Request parameters
$args
Meaning: The complete query parameter string in the URL (excluding
?).Example value:
chapter=1&flag=on.
$arg_<parameter-name>
Meaning: The value of a specific parameter in the URL query parameters. Replace
<parameter-name>with the actual parameter name.Example value:
$arg_flagextracts values from the URL/1.txt?chapter=1&flag=on. The value of the parameterflagison.
Request headers
$http_<request-header-name>
Meaning: The value of a specific HTTP request header in the client request. Replace
<request-header-name>with the actual request header name.Example values:
$http_user_agentrepresents the value of the User-Agent request header, and$http_refererrepresents the value of the Referer request header.Note: Request header variable names must follow Header variable naming conventions.
Domain name
$host
Meaning: The original domain name in the client request, which is the value of the
Host: <domain-name>request header.Example value:
www.example.com.
Request protocol
$scheme
Meaning: The protocol type used by the current request.
Example values:
httporhttps.
IP address and port
$remote_addr
Meaning: The client IP address.
Example value:
30.40.XX.XXX.
$remote_port
Meaning: The client port number.
Example value:
63213.
$x_server_addr
Meaning: The destination IP address, which is the virtual IP address (VIP) that the CDN node exposes externally.
Example value:
122.228.XX.XXX.
$x_server_port
Meaning: The destination port, which is the service port that the CDN node exposes externally.
Example values:
80or443.
IP geolocation and carrier
CDN uses the client IP address ($remote_addr) to resolve its geolocation and carrier information. The values of these variables are based on GeoIP resolution results. GeoIP resolution has accuracy limits. City-level and longitude/latitude fields generally identify the city center and are not suitable for blocking use cases that require precise geofencing. When a client IP address cannot be identified, the related fields return default values (for example, the country code returns XX, and numeric code values return 0). Each dimension provides two value forms: a code (with the _id suffix) and an English name (with the _en suffix).
$ip_isp_id
Meaning: The code of the carrier to which the client IP address belongs.
Example value: For China Telecom,
100017.
$ip_isp_en
Meaning: The English name of the carrier to which the client IP address belongs.
Example value: For China Telecom,
ChinaTelecom.
$ip_country_id
Meaning: The code of the country or region to which the client IP address belongs.
Example value: For China,
CN.
$ip_country_en
Meaning: The English name of the country or region to which the client IP address belongs.
Example value: For China,
China.
$ip_region_id
Meaning: The code of the region or province to which the client IP address belongs.
Example value: For Guangdong Province,
440000.
$ip_region_en
Meaning: The English name of the region or province to which the client IP address belongs.
Example value: For Guangdong Province,
guangdong.
$ip_city_id
Meaning: The code of the city to which the client IP address belongs.
Example value: For Shenzhen,
440300.
$ip_city_en
Meaning: The English name of the city to which the client IP address belongs.
Example value: For Shenzhen,
shenzhen.
$ip_longitude
Meaning: The longitude of the city to which the client IP address belongs.
Example value: For Shenzhen,
114.05787.
$ip_latitude
Meaning: The latitude of the city to which the client IP address belongs.
Example value: For Shenzhen,
22.54309.
SSL/TLS
SSL/TLS variables provide session information about HTTPS requests.
These variables apply only to HTTPS requests. Their values are empty when they are referenced in HTTP requests.
$ssl_client_*variables also require client certificate verification to be configured in advance. Their values are empty for standard HTTPS requests.
$ssl_cipher
Meaning: The cipher suite (a combination of cryptographic algorithms) used by the current request.
Example value:
TLS_AES_256_GCM_SHA384.
$ssl_protocol
Meaning: The SSL/TLS protocol version used by the current request.
Example value:
TLSv1.3.
$ssl_client_cert
Meaning: The client certificate data (the certificate content is returned).
$ssl_client_raw_cert
Meaning: The raw data of the client certificate (the usage is the same as that of
$ssl_client_cert, and the original certificate text is retained).
$ssl_client_serial
Meaning: The serial number of the client certificate.
$ssl_verify
Meaning: The verification result of the client certificate. The value is
SUCCESSwhen verification succeeds.Example value:
SUCCESS.
$ssl_client_s_dn
Meaning: The subject distinguished name (DN) of the client certificate.
$ssl_client_i_dn
Meaning: The issuer distinguished name (DN) of the client certificate.
Node name
$hostname
Meaning: The hostname of the CDN node that processes the current request.
Example value:
cn2522(the actual node name prevails).
Variables in the origin fetch domain
$scheme, $http_x_client_scheme, and $proxy_scheme all return the protocol type (http or https), but they differ in effective domain and in the value that each returns:
Variable | Effective domain | Description |
| The access domain | The protocol type used by the current request |
| The origin fetch domain | The protocol type that the client uses to initiate the request (the client scheme) |
| The origin fetch domain | The protocol type that the CDN node uses for origin fetch (the origin fetch scheme) |
Protocol
$http_x_client_scheme
Meaning: The protocol type that the client uses to initiate the request (the client scheme).
Example values:
httporhttps.
$proxy_scheme
Meaning: The protocol type that the CDN node uses for origin fetch (the origin fetch scheme).
Example values:
httporhttps.
Origin server
$proxy_source
Meaning: The address of the origin server to which the current request is actually sent for origin fetch.
Example values:
origin.example.comor192.0.2.1.
Origin response headers
$sent_http_<response-header-name>
Meaning: The value of a specific HTTP response header in the origin response. Replace
<response-header-name>with the actual response header name.Example value:
$sent_http_content_typerepresents the value of theContent-Typeresponse header from the origin server, such astext/html.Note: Response header variable names must follow Header variable naming conventions.