Supported Directives

This section lists all the directives you can use in the CDN Pro Edge Logic and Load Balancer Logic. While some of them are unmodified from the open-source version of nginx, many have been enhanced to better suit the needs of a CDN proxy server. CDNetworks also introduced some proprietary directives.

Each non-proprietary directive includes a direct link to the official nginx documentation. A detailed description is provided if the directive has been modified from the original version, such as limitations on the parameters of some directives.

In the following list, the standard directives are available to all customers and should cover the most common use cases. The advanced directives are usually more resource-consuming than the standard ones and will be granted on a case-by-case basis. If you need one or more of them, contact CDNetworks customer service.

`access_log_sampling`

standard LB logic proprietary

Syntax: access_log_sampling factor;
Default: -
Contexts: server (LB-only)

Downsamples the local access log. A factor of N means one log entry for every N requests. It can be used to reduce the amount of access log to download from the portal or API. A log field can be defined with the keyword %samplerate to show this factor. This directive has no effect on the edge servers' behavior, including the real-time log, whose downsampling is controlled by realtime_log_downsample. We may also use this directive to prevent properties with large request volume from overloading the log processing system. This directive is supported only in the load balancer logic.

`add_header`

standard Enhanced LB logic

Syntax: add_header name value [policy=...] [if(...)] [always];
Default: -
Context: server, location, if in location

This directive modifies the response headers to the client when the status code is 200, 201, 204, 206, 301-304, 307, or 308. When the 'always' parameter is present, it works for all status codes. CDNetworks has made the following major changes to the open-source version:

A parameter policy= has been introduced to control the behavior more precisely:

add_header X-My-Header $header_value policy=repeat|overwrite|preserve

overwrite: If the header being added exists in the upstream response, the local configuration overrides the header value. If you want to remove a header, set the value to an empty string.

preserve: If the header being added exists in the upstream response, the header value is not changed;

repeat: (default) Add the header to the client response, regardless of whether the header exists in the upstream response. Repeating the headers below is not allowed. The property validation will fail if any of these headers is specified with 'policy=repeat':

Server, Date, Content-Encoding, Location, Refresh, Last-Modified, Content-Range, Accept-Ranges, WWW-Authenticate, Expires, ETag, Content-Length, Content-Type, Transfer-Encoding, Connection, Keep-Alive, Accept, Accept-Charset, Accept-Encoding, Accept-Language, Age, Allow, Authorization, Content-Language, Content-Location, Content-MD5, Expect, From, Host, If-Match, If-Modified-Since, If-None-Match, If-Range, If-Unmodified-Since, Max-Forwards, Pragma, Proxy-Authenticate, Proxy-Authorization, Range, Referer, Retry-After, If-Match, TE, Trailer, Upgrade, User-Agent, and Vary.

Limitation: For the following "built-in" headers, the behavior is always fixed, regardless of the configured policy:

"built-in" Header Name	Behavior
`Cache-Control`	`repeat`
`Link`	`repeat`
`Last-Modified`	`overwrite`
`ETag`	`overwrite`
`Transfer-Encoding`	`preserve`
`Connection`	`preserve`
`Keep-Alive`	`preserve`

If needed, use proxy_hide_header to remove the "Cache-Control" or "Link" headers from the origin.

Example configurations:

add_header X-Cache-Status $upstream_cache_status policy=preserve;

Example with variable:

set $cache_status_method "preserve";  
if ($arg_debug = cache_status) {
    set $cache_status_method "overwrite";
}
add_header X-Cache-Status $upstream_cache_status policy=$cache_status_method;

The new parameter if(condition) has been introduced to allow adding the header based on some condition. If the condition is true, the add_header directive adds the header and the value to the downstream response based on the policy. The if parameter should always be at the end of the directive configuration. A condition may be any of the following:

A variable name; false if the value of a variable is an empty string.
Comparison of a variable with a string using the "=" and "!=" operators.
Matching a variable against a regular expression using the operators "~" (for case-sensitive matching) and "~*" (for case-insensitive matching). Negative operators "!~" and "!~*" are also available. If a regular expression includes the "}" or ";" characters, enclose the whole expression in single or double quotes.

Example:

add_header X-Upstream-Status-OK 1 if($upstream_response_status = 200);
add_header X-Status-Good 1 if($upstream_response_status ~ ^[23]);

Another change made to this directive is the ability to merge the configurations across different levels (server/location/if). However, if the same header name appears in multiple levels, the configuration of only the deepest layer takes effect for that header.

`add_trailer`

standard Enhanced

Syntax: add_trailer name value [always];
Default: -
Context: server, location, if in location

Adds the specified field to the end of a response provided that the response code equals 200, 201, 206, 301, 302, 303, 307, or 308. When "always" is specified, the trailer is added regardless of the status code. Parameter value can contain variables. We made the following changes to the open-source version:

This directive is intended to be used in the Edge Logic to pass a variable to the L7 load balancer so the real-time logger can access it with a $upstream_trailer_* variable. Although most variables can be passed by the add_header directive, some of them do not have their values ready when the response header is being constructed. Here are a few of them: $upstream_bytes_received, $upstream_bytes_sent, $upstream_response_time, $request_cpu_time. The only way to pass them to the real-time logger is using this directive when the entire response is completed.
If the response from upstream has a Content-Length header, the open-source version would remove it and convert the Transfer-Encoding to 'chunked'. We enhanced the logic to restore the Content-Length header and the regular encoding before sending the response to the client. The added trailer won't appear in the response to the client.

`allow`

standard Enhanced LB logic

Syntax: allow address | CIDR | all;
Default: -
Context: server, location

Allows access from the specified network or address. Usually used together with deny. Enhanced the open-source version to make it work with the hierarchical cache structure.

`auth_request`

advanced Enhanced

Syntax: auth_request uri | off;
Default: auth_request off;
Context: server, location

Enables authorization based on the result of a subrequest and sets the URI to which the subrequest will be sent. We have enhanced this directive on top of the open-source version to allow variables in the parameter. This enables you to pass the query parameters to the authorization logic:

auth_request /auth$is_args$args;

The request will be granted if the auth response returns a 2xx status code or rejected if the auth response returns a 401 or 403 status code. Other status codes are considered an error and return a 500 "internal error" to the client.

`auth_request_set`

advanced

Syntax: auth_request_set $variable value;
Default: —
Context: server, location

Sets the request variable to the given value after the authorization request completes. No change to the open-source version. Here is an example to add something returned from the remote auth server to the cache key:

auth_request /auth$is_args$args;
auth_request_set $cache_misc $cache_misc.etag=$upstream_http_etag;

location = /auth {
  internal;
  proxy_method HEAD;
  # specify remote auth server and URI
  origin_pass remote_auth_server/auth-req$is_args$args;
  # send the request URI to the auth server
  origin_set_header client-request-uri $request_uri;
}

`break`

standard

Syntax: break;
Default: —
Context: server, location, if

Stops processing the current set of ngx_http_rewrite_module directives. No change to the public version.

This directive belongs to the nginx rewrite module. It is executed imperatively with the other directives in the same module in an early phase of the request processing.

NOTE: If this directive appears in a location block, any "return" directive after it may not be executed. Hence we require the location block to directly contain an origin_pass directive.

`brotli`

advanced

Syntax: brotli on|off;
Default: brotli off;
Context: server, location, if

Enables or disables on-the-fly compression of responses.

`brotli_types`

advanced

Syntax: brotli_types <mime_type> [..];
Default: text/html
Context: server, location

Enables on-the-fly compression of responses for the specified MIME types in addition to text/html. The special value * matches any MIME type. Responses with the text/html MIME type are always compressed.

Note: Although it is currently allowed to set different MIME types for gzip and brotli compression by using gzip_types and brotli_types, the types set for the two compression algorithms will be merged in the near future. We recommend setting the same value for the two directives if both gzip and brotli compression are enabled.

`client_body_timeout`

advanced Enhanced

Syntax: client_body_timeout time;
Default: matches origin_send_timeout if it is set, or 20s
Context: server

This directive sets the maximum idle time when receiving the request body from the client. If you need to change the default value for your property, please contact our support team. The maximum value is 60s.

`client_header_timeout`

advanced Enhanced

Syntax: client_header_timeout time;
Default: client_header_timeout 10;
Context: server

This directive sets the maximum wait time for the complete request header from the client. If you need to change the default value for your property, please contact our support team. The maximum value is 60s. Please notice that if the Host header is not received within the default 10s, the server will close the connection and the setting in the Edge Logic will not take effect.

`client_max_body_size`

advanced LB logic

Syntax: client_max_body_size size;
Default: client_max_body_size 128m;
Context: server, location

Sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client. Please be aware that browsers cannot correctly display this error. Setting size to 0 disables checking of the client request body size. Usually you will need to configure this directive in both the load balancer and Edge Logic.

`client_send_timeout`

advanced Proprietary

Syntax: client_send_timeout time;
Default: matches origin_read_timeout if it is set, or 20s
Context: server

This directive is very similar to the send_timeout directive of the open-source version. It sets the maximum idle time when transmitting the response to the client. If you need to change the default value for your property, please contact our support team. The maximum value is 60s.

`custom_log_field`

advanced Proprietary LB logic

Syntax: custom_log_field id value;
Default: -
Context: server, location, if in location

This directive allows you to add up to two customized fields into the access log. The id can be either 1 or 2. The value can contain variables. Refer to the two fields using the keywords "custom_1" and "custom_2" when configuring the download log format or when using our advanced analytical tool. In case the same field is assigned in both LB7 and ES, the LB7 has precedence. If you require this feature, contact our support team.

Examples:

location / {
  custom_log_field 1 $http_x_data; # save the request header value X-Data to custom_1
  custom_log_field 2 $cookie_abc; # save the value of cookie abc to custom_2
  ...
}

`deny`

standard Enhanced LB logic

Syntax: deny address | CIDR | all;
Default: —
Context: server, location

Denies access from the specified network or address. Usually used together with allow. Enhanced the open-source version to make it work with the hierarchical cache structure.

`enable_websocket`

advanced Proprietary

Syntax: enable_websocket;
Default: -
Context: server, location

This directive enables proxying the WebSocket protocol. The client must use HTTP/1.1, not the other HTTP protocol versions. The default read and send timeouts are set to 60s and can be changed using the origin_read_timeout or origin_send_timeout directives.

`error_page`

advanced

Syntax: error_page code ... uri;
Default: -
Context: server, location, if in location

Defines the URI to redirect to when the current processing results in one of the specified status codes. No change to the public version. We configured proxy_intercept_errors on to make it also respond to status codes returned from the origin.

For example, the following configuration would try a second origin when the first one returns 401 or 403:

location /abc {
  origin_pass my-origin1;
  error_page 401 403 = @try_origin2;
}
location @try_origin2 {
  origin_pass my-origin2;
}

`eval_func`

standard Proprietary LB logic

Syntax: eval_func $result {function name} {parameters};
Default: -
Context: server, location, if

This is a directive to perform some common encoding, decoding, hash, hash-mac, encryption, decryption and comparison algorithms. It is added to the rewrite module. Supported functions are:

Type	Name	Syntax
hash	SHA256, MD5 CRC32	`eval_func $output SHA256 $input;` SHA256 and MD5 return a binary string; CRC32 returns a text string
BASE64 codec	BASE64_ENCODE BASE64_DECODE	`eval_func $output BASE64_ENCODE $input;`
URL codec	URL_ENCODE URI_ESCAPE ARG_ESCAPE URL_DECODE	`eval_func $output URL_ENCODE $input;` `eval_func $output URI_ESCAPE $input;` `eval_func $output ARG_ESCAPE $input;` These 3 functions encode `$input` with the percent sign(`%`). `URL_ENCODE` escapes the most special characters, including `/?=&`. It should be used for a component of the URL, such as a directory or filename. `ARG_ESCAPE` escapes fewer characters. In particular, it does not escape `/=`. It should be used for encoding a query string argument like `key=val`. `URI_ESCAPE` escapes even fewer, but it still escapes the question mark(`?`). It can be used to encode the URL without query string, for example, the variable `$uri`.
HEX codec	HEX_ENCODE HEX_DECODE LITTLE_ENDIAN_BYTES	`eval_func $output HEX_ENCODE $input;` `eval_func $output LITTLE_ENDIAN_BYTES $int $len;` `LITTLE_ENDIAN_BYTES` converts an integer `$int` from string format to a byte array of length `$len`. For example, `eval_func $output LITTLE_ENDIAN_BYTES 260 3;` would assign `$output` an array of 3 bytes: `0x04, 0x01, 0x00`.
AES cipher	ENCRYPT_AES_256_CBC DECRYPT_AES_256_CBC	`eval_func $output ENCRYPT_AES_256_CBC $key $iv $message;` `$key` and `$iv` should both be binary strings of 32 bytes.
cipher	ENCRYPT_SYMM DECRYPT_SYMM	`eval_func $output ENCRYPT_SYMM $key $iv $message $mode;` `$key` and `$iv` should both be binary strings. `$mode` can be any of the ciphers returned by openssl list -cipher-commands, for example, 'aes-128-cbc'.
HMAC generation	HMAC HMAC_HEXKEY	`eval_func $output HMAC $key $message {dgst-alg};` `eval_func $output HMAC_HEXKEY $hexkey $msg {dgst-alg};` `{dgst-alg}` can be `MD5`, `SHA1`, `SHA256`
RSA signature	RSA_SIGN RSA_VERIFY	`eval_func $sig RSA_SIGN {dgst-alg} $msg $privkey;` `eval_func $ok RSA_VERIFY {dgst-alg} $msg $sig $pubkey;` `{dgst-alg}` can only be `SHA256`.
integer comparator	COMPARE_INT	`eval_func $output COMPARE_INT $data1 $data2;` `$output` will be "1" when `$data1 > $data2`. "0" and "-1" for the other cases.
integer calculator	CALC_INT	`eval_func $output CALC_INT "$integer + 1000";` The expression will be evaluated and the result be assigned to `$output` . The expression only supports +, -, *, / of integers. Invalid input results in "NAN" in the output variable.
integer absolute value	ABS_INT	`eval_func $output ABS_INT $integer;` `$output` will be the absolute value of `$integer`. Invalid input results in empty string.
string manipulation	REPLACE	`eval_func $output REPLACE <old> <new> $input;`
string manipulation	TO_UPPER	`eval_func $output TO_UPPER $input;` Convert the input string to upper case.
string manipulation	TO_LOWER	`eval_func $output TO_LOWER $input;` Convert the input string to lower case.
string manipulation	SUBSTR	`eval_func $output SUBSTR <start> <length> $input;` Get a sub-string of `<length>` from position `<start>` of the input. `<start>` can be negative, same as substr() of Javascript.
time period in a day	DAY_PERIOD	`eval_func $out DAY_PERIOD 19:00-0700 12h USA-night;` return 'USA-night' when time is within 12 hours after 19:00-0700, or an empty string.

NOTE: The output value of the functions in bold is a binary string that may not be printable. You need to use the BASE64_ENCODE, URL_ENCODE, or HEX_ENCODE to convert it to a printable format.

Examples:

    eval_func $secret_key SHA256 "mySecret123!";
    eval_func $text HEX_ENCODE $secret_key;
    #the value of $text should be 
    #"ad8fdcda140f607697ec80a8c38e86af19f4bb79ee7f7544abcfaadd827901af"
    eval_func $aseout ENCRYPT_AES_256_CBC $secret_key $iv $message;
    eval_func $hmacout HMAC $secret_key $message SHA256;
    eval_func $hmacout1 HMAC_HEXKEY $text $message SHA256;
    #$hmacout and $hmacout1 should be equal

This directive belongs to the nginx rewrite module. It is executed imperatively with the other directives in the same module in an early phase of the request processing.

`expires`

standard

Syntax: expires time; expires epoch | max | off;
Default: expires off;
Context: server, location, if in location

Enables or disables adding or modifying the “Expires” and “Cache-Control” response header fields. No change to the public version. This directive affects only the header fields sent to the client. It does not change the cache time of the content on the server.

`gzip`

standard

Syntax: gzip on|off;
Default: gzip on;
Context: server, location, if in location

Enables or disables gzipping of responses. No change to the public version

`gzip_types`

advanced Enhanced

Syntax: gzip_types mime-type ...;
Default: gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/javascript application/xml;
Context: server, location

CDN Pro always uses gzip and applies it to the default MIME types above. In addition, compression is activated only when the response body size is greater than 1000 bytes. The default behavior should work well for most users. This directive can be used to enable compression on other types. The search and match are case-insensitive. We improved the public version to support up to 20 wildcards like text/* and *javascript.

`if/elseif/else`

standard Enhanced LB logic

Syntax: if (condition) { ... } elseif (condition) { ... } else {...}
Default: —
Context: server, location

Control the server behavior based on the specified condition. Make sure you fully understand how the rewrite module control flow works. We also wrote some guidelines about the best practices with this directive. We made some significant improvements to this directive:

Support the && operator, which performs logical AND of two sub-conditions. For example:

if ($http_x = 1 && $http_y != 2abc && $http_z) { ... }

Support the || operator, which performs logical OR of two sub-conditions. For example:

if ($http_x = 1 || $http_y != 2abc && $http_z) { ... }

Please notice that when used together, && has higher precedence than || and using parentheses to group sub-conditions is not supported. We support up to 9 sub-conditions and the evaluation logic automatically skips the ones that are not affecting the final result.

Support of string prefix check. The condition $s1 ^ $s2 returns true if $s1 begins with $s2. $s1 !^ $s2 does the opposite.
Support of integer value comparison with <, <=, >, >=. Make sure both operands are valid integers; otherwise, the result will be false. A valid integer can be either decimal or hexadecimal with a leading '0x'.
Support multiple elseif and a final else after an if block. For example:

if ($http_x = 1) { ... }
elseif ($http_x = 2) { ... }
elseif ($http_x >= 0xa) { ... }
else { ... }

Use this directive to add, delete, or overwrite the response header fields from the origin before any other processing. In other words, the value of any $upstream_http_* variable seen by other directives can be affected by this directive. The directive supports nginx variables.

Possible values of policy are repeat, overwrite, and preserve. The default policy is repeat.

The repeat policy always adds the header and the value into the upstream response. Repeating the headers below is not allowed. The property validation will fail if any of these headers is specified with 'policy=repeat':

Status, Content-Type, Content-Length, Date, Last-Modified, ETag, Server, WWW-Authenticate, Location, Refresh, Content-Disposition, Expires, Accept-Ranges, Content-Range, Vary, X-Accel-Expires, X-Accel-Redirect, X-Accel-Limit-Rate, X-Accel-Buffering, X-Accel-Charset, Content-Encoding, Transfer-Encoding, Connection, Keep-Alive, X-Ws-buffer-length, Cache_state, Accept, Accept-Charset, Accept-Encoding, Accept-Language, Age, Allow, Authorization, Content-Language, Content-Location, Content-MD5, Expect, From, Host, If-Match, If-Modified-Since, If-None-Match, If-Range, If-Unmodified-Since, Max-Forwards, Pragma, Proxy-Authenticate, Proxy-Authorization, Range, Referer, Retry-After, TE, Trailer, Upgrade, and User-Agent.

The overwrite policy overwrites the value if the header already exists in the upstream response. Otherwise, it adds the header and the value into the upstream response. Overwriting these 3 headers is not allowed: Transfer-Encoding, Connection, and Keep-Alive.
The preserve policy adds the header and the value into the upstream response only if the header does not exist in the upstream response.

The parameter if is introduced to add the header based on the condition. A condition can be one of the following:

A variable name; false if the value of a variable is an empty string.
A comparison of a variable with a string using the "=" and "!=" operators.
The matching of a variable against a regular expression using the operators "~" (for case-sensitive matching) and "~*" (for case-insensitive matching). Negative operators "!~" and "!~*" are also available. If a regular expression includes the "}" or ";" characters, enclose the whole expression in single or double quotes.

Examples:

Added a header X-Status based on origin's status code:

origin_header_modify X-Status Good if($upstream_response_status ~ "^[23]");
origin_header_modify X-Status ClientErr if($upstream_response_status ~ "^4");
origin_header_modify X-Status ServerErr if($upstream_response_status ~ "^5");

Delete the Cache-Control header in the origin's response:

origin_header_modify Cache-Control "" policy=overwrite;

The directive is merged across different levels (http/server/location/location if). If the same header name exists in different levels, the configuration for that header name in the innermost level takes effect.

Although CDN Pro has a hierarchical cache structure, the directive changes the header only in the origin response.

`origin_limit_rate`

standard Proprietary

Syntax: origin_limit_rate rate;
Default: origin_limit_rate 30m;
Context: server, location

This is a wrapper of the proxy_limit_rate directive. It limits the speed at which the response is read from the origin server. Measured in bytes/sec.

`origin_pass`

standard Proprietary

Syntax: origin_pass _origin_name[URI];
Default: none
Context: location, if in location

This directive specifies the origin from which to fetch the content. It is a wrapper of the nginx proxy_pass and a few other directives. It takes one parameter that is an origin name specified in the "origins" field of the property JSON. The origin name can optionally be followed by a URI which can contain variables. If no URI is specified, the full normalized and escaped request URI (which may have been modified by the rewrite directive) plus the query string are appended when accessing the origin. To drop the query string, one can use the rewrite directive with a question mark at the end of the replacement URI. Examples:

# when URI is not specified, 
# origin_pass my_origin; # URI-escaped $uri and the query string will be appended by default
rewrite ^(.*) $1? break; # the question mark at the end prevents query strings from being appended
origin_pass my_origin; # no query string will be forwarded to the origin

Please notice that the variable $uri is the original URL decoded by nginx, which may have a binary format such as UTF-8, or contain special unprintable characters, such as 0x0D, 0x0A. Therefore, you need to escape those characters in the variable before including it in the URI part of this directive. For example, this is another way to drop the query string:

eval_func $escaped_uri URI_ESCAPE $uri; # escape the special characters
origin_pass my_origin$escaped_uri; # no query string will be forwarded to the origin

`origin_read_timeout`

advanced Proprietary

Syntax: origin_read_timeout time;
Default: origin_read_timeout 20s;
Context: server

This is an enhancement of the proxy_read_timeout directive. It defines a timeout for reading a response from the origin server. The value is limited to an integer in [1,60] followed by ‘s’. We made sure that the entire chain of connections respects this timeout value. Currently, this directive is not supported at the location level.

`origin_send_timeout`

advanced Proprietary

Syntax: origin_send_timeout time;
Default: origin_send_timeout 20s;
Context: server

This is an enhancement of the proxy_send_timeout directive. It sets a timeout for transmitting a request to the origin server. The value is limited to an integer in [1,60] followed by ‘s’. We made sure that the entire chain of connections respects this timeout value. Currently, this directive is not supported at the location level.

`origin_set_header`

standard Proprietary

Syntax: origin_set_header field value [flag=any if(condition)];
Default: none
Contexts: server, location, if in location

This is a wrapper of the proxy_set_header directive to allow redefining (overwriting) or appending fields to the request header passed to the origin server. The following changes were made to the open-source version:

This directive merges the configurations across different levels (server/location/if). However, if the same header name appears in multiple levels, only the deepest layer’s configuration takes effect for that header.
CDN Pro has a hierarchical cache structure. By default, the headers set by this directive appear only in the requests to the origin servers. If you need it to also affect the requests to parent servers, use the flag=any parameter.
Use the new parameter if(condition) to set the header based on some conditions. If the condition is true, the directive takes effect. The if parameter should always be configured at the end of the directive configuration. A condition may be one of the following:

A variable name; false if the value of a variable is an empty string.
Comparison of a variable with a string using the "=" and "!=" operators.
Matching a variable against a regular expression using the operators "~" (for case-sensitive matching) and "~*" (for case-insensitive matching). Negative operators "!~" and "!~*" are also available. If a regular expression includes the "}" or ";" characters, enclose the whole expression in single or double quotes.

There are a few things to note when using this directive:

Because of the hierarchical cache structure, the built-in variables $scheme and $remote_addr cannot be used. If you need to pass the scheme or IP address used by the client to the origin servers, use the following variables:

$request_scheme: scheme used by the client
$client_real_ip: client’s IP address
$client_country_code: client’s ISO 3166 country code

For example:

origin_set_header X-Client-IP $client_real_ip;

Do not use this directive to set the Host header to origin. Instead, use the "origins.hostHeader" field of the property JSON. Otherwise, you will get a validation error.
The edge servers forward most client request header fields to the parent servers and the origin, except for these ones: If-Modified-Since, If-Unmodified-Since, If-None-Match, If-Match, Range, and If-Range. For cacheable requests, the servers will automatically regenerate these fields based on the cache policy when fetching from the origin. For non-cacheable requests, if you need to pass any of these fields to the origin, use this directive as in the example below:

proxy_no_cache 1;      # do not cache
proxy_cache_bypass 1;
# pass the If-Modified-Since field from client to the origin
origin_set_header If-Modified-Since $http_if_modified_since flag=any;
origin_pass My-Dynamic-Origin;

Note that the flag=any parameter is necessary in this case. Otherwise the If-Modified-Since header won't appear in the requests to the parent servers, hence won't be forwarded to the origin as desired.

`proxy_cache_background_update`

standard

Syntax: proxy_cache_background_update on | off;;
Default: proxy_cache_background_update off;
Context: server, location

Turning it on allows a background subrequest to be fired to update an expired cache item while a stale cached response is returned to the client. It should help with the responsiveness when serving popular large files which might take a while to fetch from the origin. It should be used in conjunction with the proxy_cache_use_stale directive with the updating option. CDN Pro introduced the proxy_cache_max_stale directive to set a maximum staleness to avoid serving too old objects to the clients.

`proxy_cache_bypass`

standard

Syntax: proxy_cache_bypass string ...;
Default: -
Context: server, location

Defines conditions under which the response will not be taken from cache. If at least one value of the string parameters is not empty and is not equal to “0”, the response will not be taken from the cache. This should be used if you know the content is not cacheable according to the conditions above. Examples:

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;

This directive does not prevent the response from being saved in the cache. That behavior is controlled by another directive proxy_no_cache, and usually the two should be used together.

`proxy_cache_lock`

advanced

Syntax: proxy_cache_lock on/off;
Default: proxy_cache_lock on;
Context: server, location

When enabled, only one request at a time will be allowed to populate a new cache element for the same cache key. Other requests of the same cache element will either wait for a response to appear in the cache or the cache lock for this element to be released, up to the time set by the proxy_cache_lock_timeout directive. No change to the public version. By default, CDN Pro enables it to better control the traffic to the origin servers. However, since locking will introduce unnecessary latency when most of the contents are not cacheable, we made proxy_cache_lock_timeout default to 0. If you know that most of the contents are cacheable, you can set it to some higher value to reduce origin traffic. In the meantime, if you have a way to accurately identify uncacheable contents, use proxy_cache_bypass and proxy_no_cache to skip caching and incur the least latency possible.

`proxy_cache_lock_age`

standard

Syntax: proxy_cache_lock_age time;
Default: proxy_cache_lock_age 15s;
Context: server, location

If the last request passed to the proxied server for populating a new cache element has not completed for the specified time, one more request may be passed to the proxied server. No change to the public version.

`proxy_cache_lock_timeout`

standard

Syntax: proxy_cache_lock_timeout time;
Default: proxy_cache_lock_timeout 0s;
Context: server, location

Sets a timeout for proxy_cache_lock. If a request has been locked for this amount of time, it will be released to the proxied server but the response will not be used to populate the cache. (proxy_cache_lock_age determines how often a request should be sent to populate the cache.) No change to the public version. The default value of 0s optimizes latency. You can change this to a higher value if you know that most of the contents are cacheable and want to reduce origin traffic.

`proxy_cache_max_stale`

standard Proprietary

Syntax: proxy_cache_max_stale if_error=$time while_revalidate=$time;
Default: -
Context: server, location

This directive allows serving of stale content that did not expire too long ago to give the end user a better experience. It has the same functionality as the parameters stale-if-error and stale-while-revalidate in the Cache-Control header field. Its priority is lower than the header value.

The parameter 'if_error=' requires 'error' to be specified in the proxy_cache_use_stale directive. The parameter 'while_revalidate=' only works with proxy_cache_background_update on;, which needs 'updating' to be specified in proxy_cache_use_stale.

`proxy_cache_methods`

standard

Syntax: proxy_cache_methods GET | HEAD | POST;
Default: proxy_cache_methods GET HEAD;
Context: server, location

If the client request method is listed in this directive, the response will be cached. “GET” and “HEAD” methods are always added to the list, though it is recommended to specify them explicitly. The methods supported are GET, HEAD and POST.

`proxy_cache_min_age`

standard Proprietary

Syntax: proxy_cache_min_age time;
Default: proxy_cache_min_age 0s;
Context: server, location, if in location

Description:

This directive allows you to configure the minimum cache time. If the received max-age from the origin is less than the specified minimum age, the max-age value is set to the configured minimum age value. For example, if the max-age value in the received HTTP header is 100s and the configured minimum age value is 200s, the effective cache time will be 200s.

CDN Pro calculates the cache time from the headers in the upstream response or from the nginx directives in the following order:

X-Accel-Expires > Cache-Control (max-age), proxy_cache_min_age > Expires > proxy_cache_valid (nginx directive)

When nginx calculates the cache time from max-age value in the Cache-Control header, it compares the value with the value configured in the proxy_cache_min_age and updates the cache time accordingly. Otherwise, nginx ignores the value in the proxy_cache_min_age directive.

Note: The time variable in this directive can have a number with one of the following suffixes or a combination of the following suffixes:

s = seconds (default, example: 10s)
m = minutes (example: 5m)
h = hours (example: 1h)
d = days (example: 1d)
w = weeks (example: 1w)
M = months (example: 2M)
y = years (example: 1y)

If there is no suffix in the time, the configured value is considered in seconds.

`proxy_cache_use_stale`

standard

Determines in which cases a stale cached response can be used during communication with the proxied server. No change to the public version. Based on the default setting, the CDN Pro edge server would return stale cached content if there is any problem establishing connection to the origin.

`proxy_cache_valid`

standard Enhanced

Syntax: proxy_cache_valid [code ...] time;
Default: —
Context: server, location

Sets cache time for different response codes. If no code is explicitly specified, the cache time applies to 200, 301, and 302 response codes. The specified time is applied only to responses without caching instructions from the origin. Response header fields Cache-Control, Expires, Set-Cookie, etc. have higher precedence unless ignored by proxy_ignore_cache_control or proxy_ignore_headers. We enhanced the open-source version to support setting time with a variable. If the variable value is not a valid time, this directive does not do anything. A value of 0 means cache the response and treat it as expired. If you can identify dynamic/non-cacheable contents based on certain parameters in the request, use proxy_cache_bypass and proxy_no_cache to bypass caching and improve performance.

The configuration at the server level is inherited by a location block only when this directive is not present in the location block. If you need to use the proxy_cache_valid directive at both the server level and in a location block, use the following example as a guide:

# server level, cache 404 status code for 10 seconds
proxy_cache_valid 404 10s;  
proxy_cache_valid $cache_time;
set $cache_time '';
location / { 
  # Location block, cache status codes 200, 301, and 302 for a day
  set $cache_time 1d;
  ...
 }

`proxy_cache_vary`

advanced Proprietary

Syntax: proxy_cache_vary on | off;
Default: proxy_cache_vary off;
Context: server, location

If proxy_cache_vary is "on", the CDN Pro cache servers honor the Vary response header from the origin and cache different variations separately. However, the varied contents should be purged using "directory purge".

If proxy_cache_vary is "off", the CDN Pro cache servers do not cache any response with the Vary header.

Related reading: The support (and non-support) of "Vary".

`proxy_cookie_domain`

advanced

Syntax: proxy_cookie_domain off; proxy_cookie_domain {domain} {replacement};
Default: proxy_cookie_domain off;
Context: server, location

Sets a text that should be changed in the domain attribute of the Set-Cookie header fields of a proxied server response. No change to the public version.

`proxy_cookie_path`

advanced

Syntax: proxy_cookie_path off; proxy_cookie_path {path} {replacement};
Default: proxy_cookie_path off;
Context: server, location

Sets a text that should be changed in the path attribute of the Set-Cookie header fields of a proxied server response. No change to the public version.

`proxy_hide_header`

standard

Syntax: proxy_hide_header {field};
Default: -
Context: server, location

Sets response header fields that will not be passed to the client. No change to the public version. Use this directive multiple times to hide multiple fields. The configuration at the server level is inherited by a location block only when this directive is not present in the location block.

`proxy_ignore_cache_control`

standard Proprietary

Syntax: proxy_ignore_cache_control directives…;
Default: none
Contexts: server, location, if in location

Disables processing of certain cache-control directives in the response from the origin. The following directives can be ignored:

no-cache
no-store
private
max-age
s-maxage
stale-while-revalidate
stale-if-error

Examples: ignore the no-cache and no-store directives:

proxy_ignore_cache_control no-cache no-store;

Note: This directive does not modify the "Cache-Control" header from the origin.

`proxy_ignore_client_abort`

advanced LB logic

Syntax: proxy_ignore_client_abort on | off;
Default: proxy_ignore_client_abort off;
Context: server, location (LB only)

Determines whether the connection with a proxied server should be closed when a client closes the connection without waiting for a response. Value on means ignore the client abort and continue the connection and data transfer with the proxied server. off means abort the upstream transfer as soon as the client side aborts, if the response is not cacheable. The transfer of cacheable responses always continues. This directive is supported only in the load balancer logic.

`proxy_ignore_headers`

standard

Syntax: proxy_ignore_headers field ...;
Default: -
Context: server, location

Disables processing of certain response header fields in the response from the origin. It is most commonly used to ignore caching instructions such as the Cache-Control or Expires fields from the origin. No change to the open-source version. If you need to ignore only some of the cache-control directives, use the proxy_ignore_cache_control directive.

`proxy_method`

standard

Syntax: proxy_method {method};
Default: -
Context: server, location

Specifies the HTTP method to use in requests forwarded to the proxied server instead of the method from the client request. Parameter value can contain variables.

`proxy_next_upstream`

standard

Specifies in which cases a request should be passed to the next server in the origin configuration. One important function of this directive is to define an "unsuccessful attempt" for the peerFailureTimeout settings of the origin. No change to the public version.

`proxy_next_upstream_timeout`

advanced

Syntax: proxy_next_upstream_timeout {time};
Default: proxy_next_upstream_timeout 0;
Context: server, location

Limits the time during which a request can be passed to the next server in the origin configuration. A value of "0" disables the limit. No change to the public version.

`proxy_next_upstream_tries`

advanced

Syntax: proxy_next_upstream_tries {number};
Default: proxy_next_upstream_tries 0;
Context: server, location

Limits the number of possible tries for passing a request to the next server in the origin configuration. A value of "0" disables the limit. No change to the public version.

`proxy_no_cache`

standard

Syntax: proxy_no_cache string ...;
Default: -
Context: server, location

Defines conditions under which the response will not be saved to a cache. If at least one value of the string parameters is not empty and is not equal to “0”, the response will not be saved:

proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;

When the parameter is 'on' (variable supported), the server calculates an MD5 hash of the request body and appends it to the cache key. This is useful when parameters are carried in the body of a POST request to query resources. These kinds of requests are usually idempotent and safe like GET requests, and the responses are well cacheable. You need to use the proxy_cache_methods directive to enable caching of the POST requests. You also need to set proxy_request_buffering to "on" to enable request buffering.

A restriction of this directive is that it works only when body size is less than 4kB. When the request body size is greater than this threshold, no hash value is appended to the cache key and this fact is indicated by a value '1' of the variable $ignored_body_in_cache_key. You can use this variable with proxy_cache_bypass to bypass caching of these requests. If it is really important to include a large request body in the cache key, you are advised to calculate the hash value in the client and pass it in the request header, then include it in the $cache_misc variable.

`proxy_set`

standard Proprietary LB logic

Syntax: proxy_set $variable value [if(...)];
Default: none
Context: server, location, if in location

This directive assigns the value to the $variable. The value can be another variable or a composition of variables and literals. While this directive looks very similar to the set directive, it differs in when it is executed. The set directive is executed during the "rewrite" phases which are very early -- almost right after the request is received from the client. On the contrary, proxy_set is executed after the response header is received from the origin (in case of a cache miss) or read from the cache. Therefore, the value can have information contained in the response header (after being modified by any origin_header_modify directive). In addition, this directive supports the if() parameter which can set a condition for the assignment to happen. Here are a few examples:

set $cache_time 1d; # by default, cache for 1 day
# if origin responds with a "cachetime" header, use it to override the default
proxy_set $cache_time $upstream_http_cachetime if($upstream_http_cachetime);
proxy_cache_valid $cache_time;
# extract a part from the origin's response header and send to client
proxy_set $version_number $1 if($upstream_http_version ~ "Version:(.*)$");
add_header version-number $version_number;
# do not cache status codes 301 and 302 from the origin
proxy_set $no_store 1 if($upstream_response_status ~ 30[12]);
proxy_no_cache $no_store;

The directive is merged across different levels (http/server/location/location if). If the same variable is assigned in different levels, the assignment in the innermost level takes effect.

`proxy_set_header`

standard Enhanced LB logic

Syntax: proxy_set_header field value if(condition);
Default: -
Contexts: server (LB only)

This is an enhanced version of the open-source version. It supports condition and can be used only in the load balancer logic to pass data to the ES.

`proxy_ssl_protocols`

advanced

Syntax: proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: server, location

Enables the specified protocols for requests to a proxied HTTPS server. No change to the public version.

`range_reorder`

advanced Proprietary

Syntax: range_reorder on | off [coalescing];
Default: range_reorder off
Contexts: server, location

This directive can be used to instruct the proxy server to reorder and merge multiple byte-ranges in one request. When range_reorder is enabled, multiple ranges requested in descending order will be re-ordered to ascending. When range_order is enabled with the coalescing parameter, multiple ranges that overlap or are separated by a gap that is smaller than the overhead of sending multiple parts will be coalesced. This ensures that multipart content is returned to the client with the 206 status code. When range_reorder is disabled, full content with 200 status code might be returned to the client for requests with multiple ranges.

`realtime_log_downsample`

standard proprietary

Syntax: realtime_log_downsample factor;
Default: -
Contexts: server, location

Overrides the "Sample Rate" specified for the Real-Time Log. factor can be an integer in [0, 65535] or a variable. A value of 0 disables the logging; 1 means do not downsample; N>1 means one log entry for every N requests. If the variable value is an empty string, the default setting is not overridden. An invalid value in the variable results in a factor of 100. The actual sample factor can be included in the log with the variable $realtime_log_ds_factor. This directive can only be used in the Edge Logic. In the Load Balancer Logic, one can directly use set $realtime_log_ds_factor {factor} to override the default sample rate.

`return`

standard LB logic

Syntax: return code [text]; return code URL; return URL;
Default: -
Contexts: server, location, if

Stops processing and returns the specified code to a client. No change to the open-source version.

This directive belongs to the nginx rewrite module. It is executed imperatively with the other directives in the same module in an early phase of the request processing.

`rewrite`

standard

Syntax: rewrite regex replacement [flag];
Default: -
Contexts: server, location, if

Rewrite the request URI when a regular expression pattern is matched. No change to the open-source version. Please note that this directive tries to match the regex pattern to the variable $uri, which is a normalized request URI without query string. A successful match assigns the value of replacement to $uri.

This directive belongs to the nginx rewrite module. It is executed imperatively with the other directives in the same module in an early phase of the request processing.

`satisfy`

standard

Syntax: satisfy all | any;
Default: satisfy all;
Context: server, location

Allows access if all (all) or at least one (any) of the ngx_http_access_module (allow, deny), ngx_http_auth_request_module (auth_request) modules allows access. No change to the public version. Please note that all these directives are executed after the ones in the rewrite module.

`sanitize_accept_encoding`

advanced Proprietary

Syntax: sanitize_accept_encoding enc1 enc2 … ;
Default: sanitize_accept_encoding gzip;
Contexts: server

This directive processes the incoming Accept-Encoding header field to consolidate its value. You can specify up to four parameters after this directive. Each parameter is a comma-separated combination of one or more content-encoding algorithms, such as "gzip,br" or "br". For each request from the clients, the CDN Pro edge server tries to match the received Accept-Encoding header field value with the specified combinations from left to right. If all the algorithms in a combination are found in the header, the header value is replaced with that combination. If no match is found, the header field is removed, which means only uncompressed version is accepted.

For example: if the configuration is:

sanitize_accept_encoding "gzip,br" "gzip" "deflate" "br";

The processing logic will be:

if (A-E-header.contains("gzip") && A-E-header.contains("br"))
    A-E-header="gzip,br";
else if (A-E-header.contains("gzip")) A-E-header="gzip";
else if (A-E-header.contains("deflate")) A-E-header="deflate";
else if (A-E-header.contains("br")) A-E-header="br";
else remove A-E-header;

It is not hard to see that the default setting of this directive rewrites the header value to either "gzip" or empty. Combined with the default caching policy, CDN Pro would cache the response in only one of the two encoded formats. If a client's request is asking for the other format, the server would compress or decompress the cached version on-the-fly to fulfill it.

If you use this directive and override the default setting, most likely you also want to cache the response in different encodings separately. You can achieve this by adding the header field value into the cache key:

set $cache_misc $cache_misc."ae=$http_accept_encoding";

`secure_link`

advanced

Syntax: secure_link expression;
Default: —
Context: server, location

Defines a string with variables from which the checksum value and lifetime of a link will be extracted. No change to the public version.

`secure_link_md5`

advanced

Syntax: secure_link_md5 expression;
Default: —
Context: server, location

Defines an expression for which the MD5 hash value will be computed and compared with the value passed in a request. No change to the public version.

`secure_link_secret`

advanced

Syntax: secure_link_secret word;
Default: —
Context: location

Defines a secret word used to check authenticity of requested links. No change to the public version.

`set`

standard LB logic

Syntax: set $variable value;
Default: -
Contexts: server, location, if

Assigns a value to the specified variable. No change to the public version. In particular, the cache key can be customized by assigning a value to the $cache_misc variable.

This directive belongs to the nginx rewrite module. It is executed imperatively with the other directives in the same module in an early phase of the request processing.

`slice`

standard Enhanced

Syntax: slice size;
Default: slice 0;
Contexts: server, location

Sets the size of the slices when fetching large files from the origin. The valid values are 0, which disables slicing, OR an nginx size that is between 512k and 512m, inclusive. The origin has to support range requests and respond with status code 206. If caching is desired, use the statement proxy_cache_valid 206 ... to enable caching of the partial responses. We made the following changes to this directive on top of the open-source version:

CDN Pro requires all cached slices to carry the same ETag value to ensure the content is consistent. When a slice fetched from the origin has a value that is different from the cached ones, any in-progress transfers to clients are terminated and all the cached slices are purged immediately. Please make sure the ETag value of each file on origin does not change unless the file's content has changed. This behavior can be disabled using slice_ignore_etag on;.
When slicing is enabled, the server automatically removes the Accept-Encoding header in the request to origin to disable compression. If this behavior is overridden, for example, by the origin_set_header Accept-Encoding ... directive, the client may receive a corrupted response.

standard

Syntax: sub_filter_types {mime-type} ...;
Default: sub_filter_types text/html;
Context: server, location

Enables string replacement in responses with the specified MIME types in addition to “text/html”. No change to the public version.

`upstream_origin_only`

standard Proprietary

Syntax: upstream_origin_only on|off;
Default: upstream_origin_only off
Contexts: server, location, if in location

Enable or disable origin only upstreaming. When set to on, a matching request is forwarded directly to the origin, bypassing any intermediate cache including origin shields. For example, you may have configured an origin's directConnection setting to "noDirect" to always use an intermediate cache or "auto" for us to dynamically determine the best course, by default. The upstream_origin_only directive lets you bypass that setting and allow a subset of requests to go directly to the origin. Even if you set directConnection to "alwaysDirect", the edge may still send retry requests to an intermediate server when the origin is not reachable directly. upstream_origin_only on; eliminates this possibility.

`valid_referers`

standard

Syntax: valid_referers none | blocked | server_names | {string} ...;
Default: —
Context: server, location

Specifies the “Referer” request header field values that will cause the embedded $invalid_referer variable to be set to an empty string. No change to the public version.

Staging Environment Built-in Variables

ON THIS PAGE

Supported Directives access_log_sampling add_header add_trailer allow auth_request auth_request_set break brotli brotli_types client_body_timeout client_header_timeout client_max_body_size client_send_timeout custom_log_field deny enable_websocket error_page eval_func expires gzip gzip_types if/elseif/else ignore_invalid_range internal keepalive_timeout limit_rate limit_rate_after location origin_connect_timeout origin_fast_route origin_follow_redirect origin_header_modify origin_limit_rate origin_pass origin_read_timeout origin_send_timeout origin_set_header proxy_cache_background_update proxy_cache_bypass proxy_cache_lock proxy_cache_lock_age proxy_cache_lock_timeout proxy_cache_max_stale proxy_cache_methods proxy_cache_min_age proxy_cache_use_stale proxy_cache_valid proxy_cache_vary proxy_cookie_domain proxy_cookie_path proxy_hide_header proxy_ignore_cache_control proxy_ignore_client_abort proxy_ignore_headers proxy_method proxy_next_upstream proxy_next_upstream_timeout proxy_next_upstream_tries proxy_no_cache proxy_pass_header proxy_pass_request_body proxy_pass_request_headers proxy_redirect proxy_request_buffering proxy_request_body_in_cache_key proxy_set proxy_set_header proxy_ssl_protocols range_reorder realtime_log_downsample return rewrite satisfy sanitize_accept_encoding secure_link secure_link_md5 secure_link_secret set slice slice_ignore_etag slice_verify_header sorted_querystring_filter_parameter sub_filter sub_filter_last_modified sub_filter_once sub_filter_types upstream_origin_only valid_referers