Configuring Performance and Delivery Rules in the Portal

Important

The rule builder only works with the V2 config framework. If you see the text "configuration is not supported" on the Performance & Delivery Rules screen, you will need to have Instart migrate your configuration format. Please contact your account executive to initiate this migration. If you have the V1 configuration format, you will continue to have limited self-service control over your caching policy and over performance features HTML Streaming, JavaScript Streaming, Image Transcoding, and Brotli Compression until your configuration is updated. Refer to Delivery and Performance Configuration Overview for details.

Performance and delivery rules allow you to specify conditions for applying web performance and delivery settings for your properties. When the conditions of a request match, the specified actions are applied. 

To add, view, or edit performance rules, select a property and click Config > Performance & Delivery Rules.

Rules can apply to either the Request phase or the Response phase (see below). There are tabs to display each list of existing rules.

  • For rules applied during the Request phase, there are two sections to the list – rewrite and redirect rules, and all other rules that control caching policy, origin settings, performance optimizations, and so forth.
  • For rules applied during the Response phase, redirects and rewrites do not apply, so there is only one section.

Note that

  • Redirect and rewrite rules are processed first.
  • The list under Other rules contains two standard rules that appear in all configurations: a include statement for a global defaults file at the beginning, and a include statement for a global overrides file at the end. These rules cannot be edited.
  • The order of rules matters – any rule that changes behavior already set by a rule higher up in the list takes precedence. 
    You can reorder the rules between the global defaults and global overrides by clicking Reorder Rules and then dragging and dropping rules up or down in the list.

Creating a new rule

Click Create New Rule. The portal displays the Create a New Performance & Delivery Rule screen:

The basic process for creating a rule is:

  • enter a Rule description
  • choose the Phase the rule should be applied at – either request or response
  • If it's a request phase rule, select if it's a Rewrite/Redirect or Other rule
  • choose Criteria: select the conditions you want for the rule to match
  • choose one or more Actions: select the action(s) that will be applied if the conditions match

Phase

When traffic flows through Instart's service there are two distinct phases where rules can be applied:

  • Request phase: when the service examines the request received by a client and is determining whether it can find it in the cache or needs to forward it to the customer origin
  • Response phase: when the service examines what has been found in the cache or come back from the customer origin, prior to forwarding it to the requesting client

Certain rule actions only make sense and can only be applied at one phase or the other. For example, rewrites and redirects are only handled in the request phase; a response header and response cookie are only handled in the response phase.

If you choose request phase, you need to further specify the rule type: Redirect/rewrite or Other (for all other types of rules)

If it's a redirect:

  • provide the Redirect to domain or URL
    Select the desired Response codePermanent (301) or Temporary (302)

If it's a rewrite:

  • enter what you want the URL rewritten as in the Rewrite to field. 

Once a rule is created and saved, you cannot change its phase. Existing rules are listed on the main Performance & Delivery Rules page under separate tabs depending on phase.

Criteria

You can choose No criteria, always match to create a rule that will apply an action to all requests by default.

Or you can choose Use criteria, match with conditions to set up criteria to refine the rule's scope.

Once you select Use criteria, match with conditions, the page adds a Criteria pulldown list:


The page changes according to the type you select. For example, if you select Country, an additional pulldown appears to offer you country names to choose from, and also a choice to match if a country name is matched (equals) or is not matched (does not equal) in a request:

Many of the fields that appear while you add criteria can take multiple selections. Note that multiple selections are implicitly ORed together. In the example above, the criterion statement you are making is "if Country equals Canada OR Mexico OR United States." Another way to say this is "if Country is any one of these: Canada, Mexico, United States."

Once you have added an initial criterion, a + button appears to its right. Click this and another row appears in the Criteria section, with another selector between for choosing the desired operator for combining criterion – AND or OR (the default is AND):

Note

The boolean operator you chose will apply to all criteria that you choose. That is, you can set up a rule with

criterion 1 AND criterion 2 AND criterion 3

or

criterion 1 OR criterion 2 OR criterion 3

but not both.

You can continue to select additional criteria as needed. Note that each time you add another, the button to its right changes from + to X; clicking it will remove the criterion:


For request phase redirect/rewrite rules, the available criteria are grouped into two sections in the following order:

  • Client
  • Request

For all other request phase rules, the available criteria are grouped into two sections in the following order:

  • Request
  • Client

For response phase rules, the available criteria are grouped into three sections in the following order:

  • Response
  • Request
  • Client

The corresponding match conditionals are listed in the tables below:

Request phase redirect/rewrite rules – possible criteria

Client
Criterion nameMatch conditional(s)Possible allowed values
ASNequals | does not equalValid ASN string
Browserequals | does not equalSelect one or more valid browser name (from pulldown list)
Client IPequals | does not equalValid IPv4 or IPv6 address
Countryequals | does not equalSelect one or more country names from pulldown list
Deviceequals | does not equal

Select one or more device types from pulldown list:

  • Desktop
  • Tablet
  • Mobile Phone

Network list

equals | does not equalValid network list name (from pulldown list)
Request
Criterion nameMatch conditional(s)Possible allowed values
Domainequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Valid domain name or substring 

Request phase other rules – possible criteria

Request
Criterion nameMatch conditional(s)Possible allowed values
Request headerequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Provide header name string, value; select if the match is case insensitive or case sensitive
Request cookieequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Provide header name string, value; select if the match is case insensitive or case sensitive
Request methodequals | does not equalValid HTTP method name (from pulldown list)
Request pathequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Valid path string or substring; select if the match is case insensitive or case sensitive
Request queryequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Valid query string or substring; select if the match is case insensitive or case sensitive
Domainequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Valid domain name or substring 
Client
Criterion nameMatch conditional(s)Possible allowed values
ASNequals | does not equalValid ASN string
Browserequals | does not equalSelect one or more valid browser name (from pulldown list)
Client IPequals | does not equalValid IPv4 or IPv6 address
Countryequals | does not equalSelect one or more country names from pulldown list
Deviceequals | does not equal

Select one or more device types from pulldown list:

  • Desktop
  • Tablet
  • Mobile Phone

Network list

equals | does not equalValid network list name (from pulldown list)

Response phase rules – possible criteria

Response
Criterion nameMatch conditional(s)Possible allowed values
Response headerequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match

Provide header name string or substring, value; select if the match is case insensitive or case sensitive

Request
Criterion nameMatch conditional(s)Possible allowed values
Request headerequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Provide header name string, value; select if the match is case insensitive or case sensitive
Request cookieequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Provide header name string, value; select if the match is case insensitive or case sensitive
Request methodequals | does not equalValid HTTP method name (from pulldown list)
Request pathequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Valid path string or substring; select if the match is case insensitive or case sensitive
Request queryequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match
Valid query string or substring; select if the match is case insensitive or case sensitive
Domainequals | does not equal
exists | does not exist
contains | does not contain
wildcard match | does not wildcard match

Client
Criterion nameMatch conditional(s)Possible allowed values
ASNequals | does not equalValid ASN string
Browserequals | does not equalSelect one or more valid browser name (from pulldown list)
Client IPequals | does not equalValid IPv4 or IPv6 address
Countryequals | does not equalSelect one or more country names from pulldown list
Deviceequals | does not equal

Select one or more device types from pulldown list:

  • Desktop
  • Tablet
  • Mobile Phone

Network list

equals | does not equalValid network list name (from pulldown list)

Actions

Once you have defined the criteria for the rule, select what action the service will take when the condition is matched by a request. You can, for example, specify that if the criteria match, the service will bypass the cache entirely for the matching request.

Possible actions depend on which phase you have selected.

As with criteria, selecting certain actions will might cause additional form fields to appear. For example, if you select SmartVision Transcoding, you'll see this:

If you click On, additional settings appear:

As with criteria, each time you add another action, the button to its right changes from + to X; clicking it will remove the action.
For convenience, you can collapse an action to a single line by clicking the collapse/expand toggle to the left of the first line:

To see the rule details again, click the collapse/expand toggle again.

When you have finished building the rule, click Save Rule. A Change reason dialog box appears:

Type a brief description of the reason for this change and click Submit.

The rule will be saved and you are returned to the list of rules. The rule you created appears at the end and is temporarily highlighted with green.

Available actions for each phase and their corresponding settings are listed in the table below.

Request phase redirect/rewrite rules – possible actions & behaviors

Action name

Available settings & associated values

Redirect

Type: Redirect or Rewrite

If Redirect, enter the desired URL in the Redirect to field and select a Response code: Permanent (301) or Temporary (302)

If Rewrite, enter what you want the URL rewritten as in the Rewrite to field

Request phase other rules – possible actions & behaviors

Action name

Available settings & associated values

Cache lookupDrop query string: true, false, or custom
Cache store

Client caching policy: HTTP header (default), Bypass, or Fixed TTL

Cloud caching policy: HTTP header (default), Bypass, or Fixed TTL

If Fixed TTL is selected, enter a number and select the time unit: sec, min, hr, or day

Origin

Valid fully-qualified domain name (FQDN) or IP address

Connection timeout: any integer between 1-300, in seconds. The default value is 30.

First byte response timeout: any integer between 1-9000, in seconds. The default value is 30.

Keepalive timeout: any integer between 1-1500, in seconds. The default value is 300.

Inter-response timeout: any integer between 1-600, in seconds. The default value is 30.

Host header: Edge domain (default), Origin domain, or Custom

If Custom, enter custom host header value

Use last mile protocol: True (default) or False

Set forwarded for: True (default) or False

Set true client IP: True or False (default)

Overwrite true client IP headers: True or False (default)

Request Failover: can select to send any and all of the following HTTP status codes
500 - Internal server error
502 - Bad gateway
503 - Service unavailable
504 - Gateway timeout


Failover origin: must also be provided as a valid fully-qualified domain name (FQDN) or IP address


Failover host header: Edge domain, Origin domain, or Custom
If Custom, enter custom host header value

Maximum retry attempts: 0, 1, 2, or 3

Response cookie

Operation: Set or Delete

If Set:

Cookie name: valid cookie name string of cookie to be set

Cookie value: valid value string

TTL: integer number of seconds, minutes, hours, or days; default 30 sec

Domain: valid domain string

Path: valid path string

Secure: Yes or No

HTTP only: Yes or No

If Delete:

Cookie name: valid cookie name string of header to be deleted

Response header

Operation: Append (default), Set, or Delete

If Append or Set:

Name: valid header name string of header to be appended (added to existing response headers) or set (replace existing response headers)

Value: valid value string

If Delete:

Name: valid header name of response header to be deleted

Request header

Operation: Append (default), Set, or Delete

If Append or Set:

Name: valid header name string of header to be appended (added to existing request headers) or set (replace existing request headers)

Value: valid value string

If Delete:

Name: valid header name of request header to be deleted

SmartVision Transcoding

On or Off (default)

If on:

Enable or disable for JPG & PNG (enabled by default)

If JPG enabled:

Profile: Lossless, Safe (default), Standard, Aggressive, Manual

Output to: JPG or Advanced Formats: WebP, JPEG XR, or both

If PNG enabled:

Lossless, Safe (default), Standard, Aggressive, Manual

Output to: PNG or Advanced Formats: WebP, JPEG XR, or both

JavaScript StreamingOn or Off
Dynamic CachingOn or Off
Brotli CompressionOn or Off

Response phase rules – possible actions & behaviors

Action name

Available settings & associated values

Cache store

Client Caching policy:
HTTP header, Bypass, or Fixed TTL

Cloud caching policy:
HTTP header, Bypass, or Fixed TTL

Response cookie

Operation: Set or Delete

If Set:

Cookie name: valid cookie name string of cookie to be set

Cookie value: valid value string

TTL: integer number of seconds, minutes, hours, or days; default 30 sec

Domain: valid domain string

Path: valid path string

Secure: Yes or No

HTTP only: Yes or No

If Delete:

Cookie name: valid cookie name string of header to be deleted

Response header

Operation: Append (default), Set, or Delete

If Append or Set:

Name: valid header name string of header to be appended (added to existing response headers) or set (replace existing response headers)

Value: valid value string

If Delete:

Name: valid header name of response header to be deleted

Examples

Simple rule enabling image transcoding without criteria

As a specific example, here's a simple rule we've defined that tells the service, "for any request, without any criteria, enable SmartVision Transcoding for both JPG and PNG files, using the Aggressive profile."

Rule establishing a simple redirect

Here's a rule to perform a simple redirect from acme.com to www.acme.com:

Rule defining origin settings with two criteria

In this rule, the criteria tells the service "for any request where the domain equals "wifi.blast.acme.net" and the request path wildcard-matches any of the strings 'anvils*,' 'explosives*,' 'rockets*,' or 'misc*,' take the actions that follow."

The actions when these criteria are satisfied affect communication settings with the origin will be:

  • leave the timeout settings at their defaults of Connection timeout = 300 seconds, the First byte response timeout = 30 seconds, the Keepalive timeout = 300 seconds, and the Inter-response timeout = 30 seconds
  • use the Edge domain in the Host header
  • set the Forwarded-for header
  • don't set the True client IP header and don't overwrite any that might be present
  • Set the Failover host header to be the Custom value failover.acme.com

Rule setting caching settings with one criteria

In this rule, the criteria tells the service "for any request, if the request path has a wildcard match with any of this list of common static file extensions, take the actions that follow."

The actions when these criteria are satisfied affect how objects are cached:

  • sets the client and cloud caching policies to a fixed TTL, 15 minutes for the client cache and 365 days for the cloud cache
  • drops the query string and the protocol from the cache lookup key

Editing an existing rule

Rules can be edited at any time. Note that once a rule is created, its phase cannot be changed, so the edit screen is lacking that choice.

You can also view and edit the JSON object that defines the rule by clicking the JSON tab just below the screen title.

Caution

We strongly recommend that you do not use the JSON view to modify your rule.

To edit an existing rule:

From the rule list page, click the rule you want to change. This opens the Edit Performance & Delivery Rule screen:

You can

  • modify existing criteria and actions
  • add additional criteria and/or actions
  • delete criteria and/or actions

When you have finished building the rule, click Save Rule. As happens when creating a new rule, a Change reason dialog box opens. Type a brief description of the reason for this change and click Submit. The rule will be saved and you are returned to the list of rules. The rule you edited is temporarily highlighted with green.

To view a rule's JSON representation:

Caution

The block displayed in the JSON editor pane is a JSON object which contains the rule's tree and all its nodes. So you can modify anything in the configuration and, assuming the changes you make are valid JSON, the configuration change will be applied to your traffic. Be certain that you understand the implications and know what you are changing and its effects.

From the rule list page, click the rule you want to change. This opens the Edit Performance & Delivery Rule screen. Click the JSON tab to display the JSON editor view:

The JSON view of a rule can be lengthy if there's any complexity to it, so there are a few ways to make it easier to digest aside from just scrolling up and down. You can click the collapse/expand controls; for example, here's the above JSON with the then_action block collapsed:

Another thing to point out about the JSON view: if you think of the rule as a statement of "if criteria match, then perform these actions," which is the way the rule builder interface presents it, the way that it's shown might be a little confusing: the then_action block occurs first and the predicate that expresses the criteria comes at the end. It makes no difference in how the rule works.

To delete an existing rule:

To delete an existing rule, open it for editing from the rule list page and click Delete Rule at the bottom of either the Form or JSON view.

How-to guides for actions

For details on specifying specific actions and the various parameters that can be set for each, see the following: