ESConfigGuide Customer

May 14, 2012

Edge Server Configuration Guide

Akamai Confidential. Non-Disclosure Agreement Required

Akamai Technologies, IncAkamai Customer Care: 1-877-425-2832 or, for routine requests, email [email protected]

The EdgeControl Management Center, for customers and resellers: http://control.akamai.com

Edge Server Configuration Guide (version 6.4.0)Copyright © 2002–2012 Akamai Technologies, Inc. All Rights Reserved.

Reproduction in whole or in part in any form or medium without express written permission is prohibited. Akamai, the Akamai wave logo, and the names of Akamai services referenced herein are trademarks of Akamai Technologies, Inc. Other trademarks contained herein are the property of their respective owners and are not used to imply endorsement of Akamai or its services. While every precau-tion has been taken in the preparation of this document, Akamai Technologies, Inc. assumes no responsibility for errors, omissions, or for damages resulting from the use of the information herein. The information in these documents is believed to be accurate as of the date of this publication but is subject to change without notice. The information in this document is subject to the confidentiality pro-visions of the Terms & Conditions governing your use of Akamai services.

Apple and QuickTime are trademarks of Apple Inc., registered in the U.S. and other countries.

All other product and service names mentioned herein are the trademarks of their respective owners.

US Headquarters8 Cambridge Center

Cambridge, MA 02142

Tel: 617.444.3000Fax: 617.444.3001

US Toll free 877.4AKAMAI (877.425.2624)

For a list of offices around the world, see: http://www.akamai.com/en/html/about/locations.html

http://control.akamai.com

http://www.akamai.com/en/html/about/locations.html

Contents

Preface • 9

Chapter 1 Conditions: Defining the Scope of Features • 13Host Header or In-ARL Hostname ........................................................ 14Directory Path ..................................................................................... 15Filename ............................................................................................. 16Filename Extension.............................................................................. 17Request URL Sub-string (uri.wildcard) .................................................. 18ARL Type............................................................................................. 19Client IP .............................................................................................. 20Client Request Completion.................................................................. 21Client Cookies..................................................................................... 22Client SSL............................................................................................ 23Client Status Code Served ................................................................... 24Client Timeout .................................................................................... 25Content Provider Code........................................................................ 26EdgeScape Data .................................................................................. 27Extracted Value ................................................................................... 29Fail-Action Attempt............................................................................. 30Fragment Request ............................................................................... 31Forward-Rate-Limit Blocked Request ................................................... 32Protocol .............................................................................................. 33Query String Arguments...................................................................... 34Referrer Denied................................................................................... 35Request Headers ................................................................................. 36Request Method ................................................................................. 37Request Type ...................................................................................... 39Response Headers ............................................................................... 40Response Status .................................................................................. 41Serving From Cache Only .................................................................... 42Time Intervals...................................................................................... 43Typecode ............................................................................................ 44Random.............................................................................................. 45Receipt................................................................................................ 46Variable Value and Variable-Error ........................................................ 47

Edge Server Configuration Guide 5/14/12 3

Contents

Chapter 2 Caching • 49About Caching and Caching Terms..................................................... 51Default Caching Behaviors .................................................................. 52A Quick Reference to Caching Topics.................................................. 54Cacheable Responses.......................................................................... 55Uncacheable Content (no-store and bypass-cache).............................. 61Cache Control – Time-To-Live (TTL) ..................................................... 63Honor HTTP Cache-Control:max-age and Expires Headers................... 66Scheduled Invalidation ........................................................................ 70Require Revalidation ........................................................................... 72Zero-TTL Content................................................................................ 73Asynchronous Refresh (prefresh) ......................................................... 75

Chapter 3 Caching - Advanced • 79Entity Tag Validation Support.............................................................. 80Cache POST Responses ....................................................................... 82Limiting Refresh Requests to the Origin............................................... 83Error Response Time To Live (Negative TTL) ......................................... 84Preserve Stale Object on Error Response Codes ................................... 85Cache 302 Responses by Default ........................................................ 86Quick If-Modified-Since Response ....................................................... 87Serve Only If Cached........................................................................... 88

Chapter 4 Downstream Caching • 89Default Behaviors................................................................................ 90Controls for Downstream Cacheability ................................................ 91Configuration Options - Static Content ............................................... 94Configuration Options - Dynamic Content .......................................... 96Busting Downstream Caches............................................................... 97Overriding Cache-busting Behaviors.................................................... 99

Chapter 5 Cache Key Modification • 101The Default Cache Key...................................................................... 102Ignore Query String........................................................................... 104Ignore Query Arguments................................................................... 105Ignore Path Components .................................................................. 108Ignore Path Parameters ..................................................................... 110Ignore Case in Cache Key ................................................................. 112 Flexible Cache ID.............................................................................. 113

Chapter 6 Enhanced Availability • 117Failover (was Advanced Default Content) .......................................... 118Custom Error Pages .......................................................................... 123Monitor Origin Server ....................................................................... 125SureRoute for Failover....................................................................... 127Request Queuing .............................................................................. 128

4 Akamai Technologies, Inc.

Contents

Chapter 7 Auth - Browser to Edge • 131General Access Control ..................................................................... 132Referrer Checking ............................................................................. 133Block Access by Client IP ................................................................... 135Centralized Authorization ................................................................. 136Remote Authorization....................................................................... 138Edge Authorization - Cookie-Based................................................... 141Edge/Central Hybrid Authorization .................................................... 145Edge Authorization - URL-Based - Origin Tokens ............................... 146Edge Authorization - URL-Based - Edge Server Tokens....................... 151

Chapter 8 Auth: Edge to Origin • 157Set User Agent.................................................................................. 158Akamai-ID Cookie............................................................................. 159Signature Header Authentication ...................................................... 160SSL Client Certificate Authentication ................................................. 162

Chapter 9 Edge Computing • 165Edge Side Includes ............................................................................ 166EdgeAkamaizer ................................................................................. 167Process POST Body Through DCA...................................................... 169DCA Output Caching........................................................................ 170

Chapter 10 Edge Services - General • 173Add, Pass, or Remove Headers .......................................................... 174Cloning HTTP Headers ...................................................................... 175Forward Status Code Override........................................................... 176Client Status Code Override .............................................................. 177Custom Client IP Header ................................................................... 178Constructed Response ...................................................................... 179Support for 100 Continue Responses ................................................ 181Support for WebDAV Requests / Responses....................................... 182EdgeScape - Content Targeting......................................................... 185

Chapter 11 EdgeServices - Cookie Handling • 187Cookies Set by the Origin.................................................................. 189Generate Unique Cookies ................................................................. 191Set Explicit Cookie Via Configuration File .......................................... 193Expire Browser Cookies (Beta) ........................................................... 194

Chapter 12 EdgeServices - Redirect Handling • 195Redirect Chasing............................................................................... 196Generate Redirects Based on URL Marker.......................................... 198Generate Redirects Based On Configuration...................................... 200

Chapter 13 Performance • 203Support Compressed Content ........................................................... 204Last Mile Accelerator......................................................................... 205


Contents

Chunked Encoding ........................................................................... 208Prefetching ....................................................................................... 210

Chapter 14 Forward Server • 213General Forward Connection Settings ............................................... 214Host Header Modification ................................................................. 217Origin Server Assignment.................................................................. 218Tiered Distribution ............................................................................ 219SureRoute for Performance ............................................................... 220Site Shield......................................................................................... 222

Chapter 15 Forward Path • 225Prune or Modify Query String............................................................ 226Path Modification By Rule ................................................................. 227Path Modification by Regular Expression ........................................... 228

Chapter 16 Network • 229DNS .................................................................................................. 230 HTTP................................................................................................ 231ICP.................................................................................................... 232Persistent Connections (pconns)........................................................ 233TCP Optimizations ............................................................................ 235Timeouts........................................................................................... 237Adaptive Connect Timeout (Beta)...................................................... 238Client-Side Traffic Shaping (Beta) ...................................................... 240

Chapter 17 Reporting • 241Log Delivery ...................................................................................... 242Edge Logging (Download Receipts) ................................................... 245

Chapter 18 Security Related Features • 249Support POST Requests..................................................................... 250Support for PUT and DELETE Methods .............................................. 251Munged URL..................................................................................... 252Object ID Checking ........................................................................... 253Authenticate Object ID's ................................................................... 255Use SSL Going Forward..................................................................... 256

Chapter 19 Using Variables • 257Variables Syntax................................................................................ 258Extracting Values Into Variables......................................................... 260Assigning and Transforming Variables............................................... 262Comparing Variables......................................................................... 265

Chapter 20 Other Capabilities • 267Session ID Support ............................................................................ 268Download Manager .......................................................................... 271Progressive Download Seeking.......................................................... 272


Contents

Chapter 21 Related Services • 273NetStorage ....................................................................................... 274

Glossary • 275


Contents


Preface

In This Preface

Audience • 10

Current Version • 10

New Material in This Version • 10

Pricing • 11

Document Conventions • 11

Organization • 11

Related Documents • 12

Welcome to the Akamai Edge Server Configuration Guide. The edge server provides an integrated suite of services for content and application delivery, content targeting, edge processing, business intelligence, and streaming media. These services are delivered by Akamai servers at the edge of the Internet, close to the end users requesting customer content. Akamai edge servers can be configured to serve content according to each content provider’s needs. This guide describes many of the configurable features and options of the Akamai edge server. It also references related services of interest to edge server users.

Please take a moment to read this Preface to ensure that the document is intended for you and that you understand the conventions used and basic assumptions made in preparing the document.


Preface

Audience This guide is intended for current and prospective Akamai customers, partners, resellers, and Akamai Professional Services personnel. At a minimum, readers should already be familiar with Akamai's distributed content delivery network and site acceleration technologies and have a basic understanding of the HTTP protocol.

CurrentVersion

The capabilities of the edge server are continually evolving. As a result, this document is rapidly superseded by new versions. Please check the date and version number of this document to ensure it is still current. You’ll find the date at the bottom of odd numbered pages and the version number on page two with the copyright notice. If the document is more than four months old, it is likely to be out of date, and you should check whether a newer version is available on the Akamai customer portal, https://control.akamai.com, or ask your Akamai contact.

New Materialin This Version

The following material has been added or changed in this version of the Edge Server Configuration Guide. Some of these additions and changes reflect new functionality in the Akamai server, while others reflect only improvements to the documentation.

New in version 6.4.0

Several feature descriptions have been added in this version of the document to bring it more up-to-date with the state of the server. In many cases this new material is currently intended for use only by internal readers. Often only a general description of the feature is provided with links to the original design document and metadata tags for more details. In addition, some existing features have had their descriptions enhanced. Following are a few changes of note:

• Edge Authorization 2.0 - Token Auth was added to the Authorization chapter.

• Intermediate Processing Agent was added to the Edge Services - General chapter.

• Progressive Media Seeking was added to the Other Capabilities Chapter.

• Cacheable Responses section was added to the Cache chapter. This material used to be the "Cacheability of Responses" document. It has been updated in this edit.

• The listing of variable transformations has been updated

ConfigurationManagerSupport

Where appropriate, this document identifies features that can be directly configured by customers and Akamai partners through the Configuration Manager interface that is part of the Edge Control Management Center (ECMC) at https://portal.akamai.com. You’ll see the Configuration Manager interface if you click “Configuration” under your product link in the left sidebar of the ECMC.

Not all features can be directly controlled by customers or partners. Those that can be directly controlled must be part of a contracted solution or feature before they will appear in your Configuration Manager interface. If you have any questions about availability of a feature through Configuration Manager, please contact your Akamai implementation support team.


https://portal.akamai.com

https://portal.akamai.com

Confidential & Proprietary

Pricing Features are included in this document without regard to pricing. That is, no attempt has been made to designate which features are part of any particular service, solution, or product bundle. Some features may involve additional service charges. Contact your Account Manager if you have questions regarding feature availability and pricing.

DocumentConventions

For the most part, the conventions followed in this document are self-explanatory. As you read, please keep in mind the special conventions listed here.

Examples The examples in this document often use example.com as the customer. However, these are fictional examples and not meant to represent a valid request or feature application for example.com. The company example.com doesn’t actually exist, and the domain name was used for that very reason.

What "Beta"Means

Some feature headings include the word "Beta" to indicate that the feature has not yet been implemented for a customer serving live traffic. These features have been thoroughly tested within Akamai and have received live traffic in a testing environment. You are encouraged to use these features without restriction. They are designated as "Beta" simply to alert you to the possibility that the implementation for your site may uncover limitations or side effects that could not be discovered through lab testing. Your Integration Consultant will work closely with you to resolve any issues that may arise.

Organization This document organizes the features of the edge server by general function with a chapter devoted to each function. For example, features related to cacheability are in the Caching and Coherence chapter.

The first chapter, Defining the Scope of Feature, is an exception in that it describes the various criteria you can use to assign features to particular content. You should read this chapter first to gain an understanding of how features are applied.

Within most individual feature descriptions you’ll find the following types of material:

• Overview – a very high level description of what the feature does and in some cases how Akamai servers behave without the feature enabled (their default behavior).

• Scenario – a situation in which the feature is useful to Akamai customers.

• Caveats – a listing of any issues related to use of the feature.

• Technical Details – the workings of the feature in some technical detail.

• Integration – what must be done by the content provider, or by Akamai personnel on behalf of the content provider, to enable the feature. Since changes to the edge server configuration files are submitted by the Integration Consultants, integration generally involves contacting the IC and providing the required information.


Preface

RelatedDocuments

Following is a list of documents related to Akamai services that are referenced in this document. You can find these documents on the Akamai customer portal, https://control.akamai.com.

Time-to-Live in Cache: Methods and Considerations

Handling of Edge-Control & Other HTTP Headers

ESI Developer’s Guide

Content Control Utility User’s Guide

Akamai Log Delivery Service: Service Description & Customer Technical Guide

Session ID Support

Freeflow Typecode Guide


Edge Server Configuration Guide 5/14/12

In This Chapter

Host Header or In-ARL Host

Directory Path • 15

Filename • 16

Filename Extension • 17

Request URL Sub-string (uri

ARL Type • 19

Client IP • 20

Client Request Completion

Client Cookies • 22

Client SSL • 23

Client Status Code Served •

Client Timeout • 25

Content Provider Code • 2

EdgeScape Data • 27

Extracted Value • 29

Fail-Action Attempt • 30

Fragment Request • 31

Forward-Rate-Limit Blocked

Query String Arguments •

Referrer Denied • 35

Request Headers • 36

Request Method • 37

Request Type • 39

Response Headers • 40

Response Status • 41

Serving From Cache Only •

Time Intervals • 43

Typecode • 44

Random • 45

Receipt • 46

Variable Value and Variable

1
Conditions: Defining the Scope of Features
name • 14

.wildcard) • 18

• 21

24

6

Request • 32

34

42

-Error • 47

The edge server configuration file lets you define the scope to which the features apply. You can apply features to the entire site on one extreme, or to a single file on the other. For example, every Web site should have a default time-to-live assigned to the entire site. Features such as Support Compressed Content and Support Chunked Encoding are generally applied to the entire site, because whether or not the feature is used depends on HTTP headers from the client browser or origin server.

Other features are best applied to only a small area of the Web site. For example, Dynamic Content Assembly should be applied only to text files (such as .html or .xml) that can be processed for dynamic assembly.

This chapter lists the criteria you can use for applying features to requests and provides a brief explanation of each. The list of these criteria is in the right column of this page under the In This Chapter header.

These criteria can be further combined to form a fairly complex logic for applying features. For example, you could apply a feature only to requests for objects in the "secure" directory that had the file extension ".zip" when the client failed to present a cookie named "authorized". You can also use a special <choose> structure to apply features based on one condition out of several, or define the handling of the request when a condition is not met, in addition to when it is met.

13

Chapter 1: Conditions: Defining the Scope of Features

Host Header or In-ARL Hostname

Akamai servers use the Host header or in-ARL hostname to determine the origin server from which the original content should be retrieved. This is also the coarsest division of content into distinct groupings for the application of features. Though it is not generally efficient to do so, you could create a separate edge server configuration file for each Host header in-ARL hostname used by the site.

Within a configuration file, hostnames and in-ARL Tokens can be grouped within a single match condition, or each hostname can be listed separately with a feature set unique to that host.

For example, if the origin server origin.example.com serves content for the hostnames example.com and example2.com, features can be applied to the two hostnames either equally or differently depending on how the configuration file is organized.


Directory PathConfidential & Proprietary

Directory Path

When assigning features to content, the directory structure of the origin server can be used to distinguish one set of content from another. For example, all files in the 'html' directory might be processed using Dynamic Content Assembly, and all the files in the 'secure' directory might be handled using Centralized Authorization.

You can assign features to:

• A directory and all of its subdirectories

• A directory but not its subdirectories

• The subdirectories of a directory, but not the directory itself

You can choose whether or not a directory is matched case-sensitively and whether or not a path parameter should be considered a part of the directory to match.

You can also combine these options with the file extension and filename matching options listed in this chapter.



Filename

The filename match is very flexible in its ability to identify objects to which you want to apply metadata. You can identify the files to which metadata applies in at least four different ways:

Exact File

By specifying both the path and the exact filename, you're able to assign a feature to a single object. For example, you might make one of the following requests:

Enable Centralized Authorization for www.example.com/downloads/secure/widget.exe

Honor Cache-Control headers for www.example.com/banners/firesale.gif

Global Filename

You can apply metadata to a specific filename in any directory by indicating that the match on the filename should be “recursive.”

Default File

You can match on the default file (either in a particular directory or in any directory) by indicating that the filename has no characters (it doesn’t exist)

Partial Filename

You can define the substring of characters that should be found inside the filename, and match on that substring in any file (and in any directory recursively).


Filename ExtensionConfidential & Proprietary

Filename Extension

Akamai servers can apply features based on a particular file extension. For example, you can request that a feature be applied only to files with the extension .jsp or .exe.

Examples of typical requests would include:

Assign all files of type .exe a time-to-live of seven (7) days

Enable dynamic content assembly for all files of type .html

Log cookies for all files of type .zip in the directory www.example.com/downloads/secure/



Request URL Sub-string (uri.wildcard)

You can apply features to any URL that contains a particular substring. For example, you can assign features to any URL that contains the substring “jsessionid” to remove the session ID from the cache key for the object.

This option also provides for use of simplified regular expressions. That is, you can use wildcards when you define the substring you wish to match anywhere in the URL. An asterisk (*) represents zero or more characters, and the question mark (?) represents any one character.

You can also choose whether or not the match is case sensitive.

Note: the query string is not evaluated by this match type. The match compares the request URL path (starting with ‘/’ and without any question mark and query string) with a given string.


ARL TypeConfidential & Proprietary

ARL Type

This condition is used to apply features based on the format of the request ARL This condition is primarily useful if the Web site serves content using both CNAMEd ARLs and legacy FreeFlow ARLs, or for denying access to content using v1-ARLs as a means of increasing security for content that requires authorization.

There are three types of ARL:

typecode – applies to any ARL that uses Typecodes. This is the format used by the FreeFlow service.

cname – is any ARL (actually a URL) that isn't one of the other two. It is called "cname" because it uses the edge server based on a hostname CNAMEd to Akamai.

prepend – applies to ARLs that use an ARL token but not a Typecode. This format is very rare.



Client IP

Akamai servers can assign features based on the client IP in the request. This is commonly used to deny access to particular end users (see Block Access by Client IP). When you use this option, you can identify the IP addresses by range or by CIDR block if necessary.

This option could be used to assign other features, or to turn off other features. For example, you might choose to tunnel all requests from a particular IP (your personal IP!) to ensure that you received content directly from the origin server.

When the use-headers attribute is set to "on," this match will use the value of the X-Forwarded-For header as seen by the Akamai server in the actual client request. Any attempt to modify the X-Forwarded-For header in the same metadata tree before it is evaluated by this match will fail. For example, if you are trying to remove a bad value, such as "unknown," from the beginning of the incoming X-F-F request header before the header is evaluated by this match, you will need to remove the bad value in one tree of metadata and then forward the request to a second tree of metadata to apply the match:client.ip condition.


Client Request CompletionConfidential & Proprietary

Client Request Completion

This condition identifies whether the client request was served successfully. This is used primarily for large file downloads.

The match allows you to test whether the client download triggered any of the following conditions:

• first byte of object served

• last byte of object served

• full requested bytes served

• aborted connection.



Client Cookies

Akamai servers can apply features to content based on cookies presented by the client. Cookies can be evaluated on several criteria:

• Presence/absence of a cookie with a particular name (or a substring within the name)

• Presence of a cookie with a particular name that contains (or does not contain) a particular value string

• Presence of a cookie with a particular name where the value string contains (or does not contain) a particular substring

You can also specify whether or not the matching function should be case sensitive.

Examples of where this condition might be useful include:

• Block access based on absence of a cookie

• Set a cookie if it is not already present

• Log cookies if a particular cookie is present

• Enable Centralized Authorization if a particular cookie is not present

• Enable POST method if a particular cookie is present


Client SSLConfidential & Proprietary

Client SSL

There are several conditions that can be used to detect the type of SSL connection used by the client request. These conditions are generally used to enforce a minimum level of security for the transaction with the client.

Minimum SSLVersion

This condition matches on the SSL version used by the client (browser) request. The condition can be used to detect that the client failed to use an SSL version above a desired level. In this way, the condition can be used to enforce a minimum level of security for the transaction with the client.

Minimum SSLCipher

Strength

You can match on the strength of the cipher the client is using. The strength of the cipher refers to the number of bits in the encryption key.

SSL CipherName

You can match on the full name of the SSL cipher the client is using. An example use of this tag might be to set preferred_ciphers to DES-CBC3-SHA (the most secure setting) and must_have_ciphers to everything else. We could then match on whether the client is using DES-CBC3-SHA. If not, we know that the client doesn't support that algorithm.

SSL CipherAlgorithm

You can match on the name of the encryption algorithm the client is using.

SSL CipherMAC

You can match on the name of the MAC the client is using.

Export Cipher This condition allows for determining whether the client is using an export grade (very weak, 40 or 56-bit) cipher. Note that not all 56-bit ciphers are export grade.



Client Status Code Served

Matches on the HTTP status returned by an Akamai server to its client. This tag is used for download receipts, because the match:response.status tag matches on the HTTP status from the forward server, which can be different from the HTTP status returned to the client in case of 206 and 304 or any time a fail-action is applied to the response.


Client TimeoutConfidential & Proprietary

Client Timeout

Akamai servers can apply features to content based on whether the ‘client-timeout’ setting was reached. Client-timeout is a setting that places a limit on the amount of time the Akamai server can spend attempting to obtain content to serve the client. If the Akamai server needs to request content from the origin server, and the origin server is not responsive, client-timeout may be triggered, and the Akamai server will then serve the client an error. You can use this condition to determine that the client-timeout was reached, and take some alternate action, such as serving a redirect or fetching the content from a fail-over server.

TechnicalDetails

Note that the time specified in the 'client-timeout' metadata tag does not literally specify a minimum response time to the client. Instead, it specifies how much time the Akamai server can spend on the forward side (for example, attempting to retrieve content from the origin server) for each forward request. If there is only one forward request, a response will be sent to the client in approximately the client-timeout. But, if Default Content is used to retrieve content from another location after the first attempt times out, this new forward request will again have the time specified for client-timeout to complete. This match condition will evaluate to ’true’ each time the client-timeout is triggered.

This match type will only be executed for GET requests (client-timeout is only supported for GETs), and it won't take effect until the forward-response stage (since that's when client-timeout may kick in).



Content Provider Code

This condition lets you apply features based on the customer billing code.

For obvious reasons, this match is useful primarily in cases where a content provider has more than one CP code.


EdgeScape DataConfidential & Proprietary

EdgeScape Data

EdgeScape is an IP intelligence service. It leverages Akamai’s server deployment and relationships with networks throughout the world to enable collection of geography and bandwidth-sensing information. The resulting database provides companies with a highly accurate knowledge base of where and how users access the Internet. This enables e-businesses to leverage geography-based business strategies, customize content to provide more relevant information, and protect their goods and information.

Akamai servers can apply features to content based on any data field supplied by EdgeScape to the Akamai edge server. This is commonly used to target content by geography. For example, you could deny access to content based on the country from which the request originated. Similarly, you could redirect requests to a separate domain to serve localized content based on the client country information.

This Content Targeting feature is only available to customers using Akamai’s EdgeScape service as part of their edge server configuration.

Caveats Please carefully review the following caveats with regard to using the match on EdgeScape data:

• Not all fields in the EdgeScape database are available to the Akamai edge server. In particular, the company, domain and device_type fields are not available and thus cannot be used to conditionally handle a request. For an up-to-date listing of available fields, consult the EdgeScape User Guide available on the Akamai Portal.

TechnicalDetails

The EdgeScape database gives the Akamai server information about a given IP address and the match condition for EdgeScape information gives you some choices as to which IP address you test. You can choose to test:

• the connecting client IP

• the first routable IP address in the X-Forwarded-For header

• all routable IP addresses in the X-Forwarded-For header

• the IP address of the Akamai server handling the request

• any combination of the above

Which IP address (or combination of IP addresses) to test will depend on the goal of your configuration. For example, if you want to redirect the user to a web site in their local language, you may want to test only the first routable IP address in the X-Forwarded-For header. This address normally is the address of the end-user. If you want to deny requests originating from certain countries to comply with export rules, you may want to check the connecting IP address and the first routable IP address in the X-Forwarded-For header. If you want to strictly enforce that the request/response not even traverse a disallowed region, you may check all routable IP addresses in the X-Forwarded-For header. In some rare cases, business requirements may call for



ensuring that content is not delivered from an Akamai server in a particular location (or outside a particular location). All of these can checks can be accomplished with the EdgeScape match condition.


Extracted ValueConfidential & Proprietary

Extracted Value

Akamai servers can extract a value from the client request and place it in a variable. The server can then match on the variable or value to apply features. The variable can be evaluated on several criteria:

• Presence/absence of the variable in the request.

• Whether or not it contains a specific string (case sensitive or not)

• Whether or not it contains a particular substring (case sensitive or not)

• Whether or not it contains an integer within a given range of values.



Fail-Action Attempt

Akamai servers can apply features based on how many attempts have been made to take an alternate action (Default Content, Default Redirect, Recreate Request). This makes it possible to try various mechanisms for serving the client a useful response before resorting to serving an error.


Fragment RequestConfidential & Proprietary

Fragment Request

Akamai servers can apply features based on whether or not the request was for a fragment in ESI processing. This can be used to forward template page requests to the origin server for validation of a session ID, but not forward the fragment requests, which would use the session ID of the template page.



Forward-Rate-Limit Blocked Request

Akamai servers can apply features to requests that were not forwarded to the origin server for a response because the origin server was busy, as determined by the Forward Rate Limiting feature. This makes it possible to apply an alternate action (Default Content, Default Redirect, Recreate Request) to serve the client.

TechnicalDetails

Note that only client-response or client-done metadata tags can be applied inside this match. These are the metadata tags that are applied after the Akamai server has forwarded the request to the origin.


ProtocolConfidential & Proprietary

Protocol

Akamai servers can apply features based on whether the request was made using HTTPS: or HTTP: as the protocol.



Query String Arguments

Akamai servers can apply features to content based on the query string arguments in the client request. One use for this match is to determine whether the request URL contains a session ID in the query string. As with matching on cookies, you can match for whether the query string argument:

• Is either present or missing

• Has or doesn't have a particular value

• Has or doesn't have a particular sub-string inside its value

You can also specify whether or not the matching function should be case sensitive.


Referrer DeniedConfidential & Proprietary

Referrer Denied

If a request arrives with a Referer: header that is disallowed according to the configuration file, the request will be denied. This condition lets you apply features to a request that is about to be served an error (403 Forbidden) based on the client’s Referer header. This is primarily useful for serving a custom error page or alternate content.

Only metadata tags that apply at client-response and client-done stages can be applied within this match.



Request Headers

Akamai servers can inspect the HTTP headers that accompany a request and, based on the contents of the headers, apply features. Headers can be evaluated on several criteria:

• A specific substring can be found anywhere in the request headers. The match can be case sensitive or not.

• A specific request header contains a specific value (can be an exact value or a substring match). The match can be case sensitive or not.


Request MethodConfidential & Proprietary

Request Method

Akamai servers can apply different features based on the request method. You can use this condition to match on any value in the method portion of the client request. Of course, the match is generally useful only if the method is also supported by the Akamai server. This condition is usually used to treat POST requests differently from the usual GET.

If a request method is conditionally supported (that is, it must be enabled in the customer configuration), then you must be careful to ensure that a match on that method is useful for the given context. Only in rare cases does it make sense to match on a method that has not been enabled.

Supported Methods

GET and HEAD methods are supported by default.

POST is commonly supported through an additional configuration option.

PUT and DELETE can be separately supported through a configuration option, though this is rarely enabled. (These are also automatically enabled when WebDAV support is enabled.)

If WebDAV support has been enabled (another infrequent option), the following methods are supported: PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, OPTIONS. OPTIONS is not strictly a WebDAV method, but it is included with those as clients commonly check for available options before employing the other request methods. However, it is very important that customers understand the limitations of Akamai’s support for the OPTIONS method. An end client request must not expect the Akamai server to provide special services or capabilities available only on the origin server, or the customer application will break. See the section on WebDAV Support in the EdgeServices chapter. It is possible to restrict the methods permitted when enabling WebDAV by enabling support conditionally.

Notice that the example above enables WebDAV support (which also enables use of DELETE), conditionally so that only the DELETE method is allowed, not all of the methods that are part of WebDAV. Similarly, it is possible to allow all of the methods included in WebDAV support except OPTIONS, through use of a "false" match, like this:

For purposes of this match, the value should be written as one of the strings from the following lists:

Common HTTP/1.1methods:

GETHEADPOST - must be enabled (security:allow-post)PUT - must be enabled (security:allow-put)



HTTP_DELETE - must be enabled (security:allow-delete)OPTIONS - must be enabled (edgeservices:webdav.status)

WebDAV Methods

These methods are available with WebDAV support has been enabled through edgeservices:webdav.status

DAV_COPYDAV_PROPFINDDAV_PROPPATCHDAV_MKCOLDAV_MOVEDAV_LOCKDAV_UNLOCK


Request TypeConfidential & Proprietary

Request Type

This condition matches on the type of request the Akamai server receives. There are two overlapping groups of possible request type. One group distinguishes among the requests by whether it is a user request or a request from a server function (user, ESI fragment, ESI war file, ESI tunnel). The other group distinguishes among requests by whether it is an end client request or a request from another Akamai server (end client, peer server, hierarchy child server).



Response Headers

Akamai servers can inspect the HTTP headers that accompany a response and, based on the contents of the headers, apply features. The headers can be checked for whether one of various conditions is true or false, including:

• Presence of a particular status code

• Presence of a header with a particular name

• Presence of a header with a particular name and value. This comparison can be case sensitive or not, can be for an exact string or substring, or can be a numeric comparison (greater than, less than, equal to).

Response header matching is very much like the Request Header matching with an important difference: the set of features that can be applied based on response headers is somewhat limited. In many cases, a feature cannot be applied at this late stage of processing. For example, at the point the response is received, it is too late to modify the cache key for the response object.

TechnicalDetails

This match tag matches on characteristics of the response header as received from the forward side functions. Usually this is the response received from the origin server and intended for the client, but it may be the response generated or modified by the Akamai server for the client depending on which stage of metadata application is being used.

Not all metadata tags can be applied inside a response-header match, and, the metadata may be applied in one of several different stages. The stage at which a metadata tag is applied may effect how it can be used. For example, you cannot turn a configuration file no-store setting off using response-header matching, because the decision to go forward will be made before the no-store setting within the response-header match is applied.


Response StatusConfidential & Proprietary

Response Status

You can apply features based on the status code received in the response from the forward server, which is usually the origin server. This could also be the status code generated by the forward-side functions of the Akamai server, for example, when it cannot connect to the forward server, or connects but receives no response.

In the most common case, this is used to match on response status codes that indicate an error on the forward server (400 and 500-504) and attempt to obtain the content from another source, or serve alternate content, rather than serve the error to the end user.



Serving From Cache Only

Akamai servers can apply features based on whether it was instructed to only serve the content from cache (not go forward to the origin server to retrieve content) and actually has the requested content in cache. This makes it possible to treat the content and a potential error (a 504, for example) differently. For example, if the condition was false, and an error would be served, an alternate action could be taken to pull the content from another location.


Time IntervalsConfidential & Proprietary

Time Intervals

Akamai servers can apply features for a time interval based on the date and time with settings for:

• Start of the time interval

• Length of the time interval

• Repeat time for the interval

• Expiration of the interval repetition

• Whether the Start and End should be adjusted for the onset or end of Daylight Saving Time in the local time zone.

Using this option you can prepare feature settings in advance of when they are needed. For example, Tiered Distribution could be configured on the network in advance of a major Web event, but only take effect at the time of the event.

This option also lets you change features on scheduled intervals. For example, a Web site might have one time-to-live set for its content during business hours, and another at night, when the content is expected to change less frequently. The time-to-live for a stock quote could be scheduled to change from five seconds during market hours to one hour when all markets are closed.

Supported Timezones

The Akamai server currently supports the following time zones for use with Time format for specifying the start or end time of the match condition. :

UTCUS/Central US/Eastern US/Mountain US/Pacific Asia/Shanghai

Timezones can be added to this list through an update to baseline metadata settings. As of , the following time zones have been added through baseline metadata:

Europe/LondonEurope/ParisWETCETMETEETIsraelAustralia/SydneyAustralia/PerthAsia/Tokyo



Typecode

This condition tag makes it possible to apply features to requests made using a FreeFlow ARL with a particular typecode.


RandomConfidential & Proprietary

Random

This tag provides a way to randomly match on some percentage of the requests to which the tag is applied.

The random value assigned to the request and evaluated by the match is supplied by the system random number generator. It does not use any in-band information about the request such as IP, geo-location, user agent, or time. Thus this condition is intended to be truly random.



Receipt

See the entry under “Edge Logging” in the Reporting section of this document.

This condition matches on receipt requests directed toward the origin server. The condition allows for applying features to these requests differently that to a normal client request.


Variable Value and Variable-ErrorConfidential & Proprietary

Variable Value and Variable-Error

You can match on the value of a variable. The variable can be:

• a built-in variable (such as AK_URL)

• created through the extract-value feature

• created through the assign:variable feature.

You can use this to test whether the value of the variable is:

• a particular value (including an empty string),

• one of several possible values, or,

• if it is an integer, whether the value falls within a given range.

In addition to the simple variable matching tests, you can also test whether the content of a variable matches a regular expression, and assign any matched portions to a new variable or list of variables.

The variable-error condition lets you test whether a variable created through assignment or transformation was successful.





In This Chapter

About Caching and Caching

Default Caching Behaviors

A Quick Reference to Cachi

Cacheable Responses • 55

Uncacheable Content (no-st• 61

Cache Control – Time-To-Liv

Honor HTTP Cache-Control:Headers • 66

Scheduled Invalidation • 7

Require Revalidation • 72

Zero-TTL Content • 73

Asynchronous Refresh (pref

2
Caching
Terms • 51

• 52

ng Topics • 54

ore and bypass-cache)

e (TTL) • 63

max-age and Expires

0

resh) • 75

This chapter, and the two following it, discuss features that control content caching on Akamai servers and maintain consistency of the content on Akamai servers with the content on the origin server.

This chapter provides a brief overview of caching on the Akamai server and discusses the basic caching options such as max-age, requiring revalidation, no-store, expiration of content, and prefresh.

The next chapter, Caching - Advanced, discusses the more advanced options for controlling the Akamai server’s cache. These include, Entity Tag validation, caching of POST responses, and caching partial objects among others.

The chapter titled Downstream Caching describes how the Akamai server sets the values of Cache-Control and Expires headers it sends in the response to the client (proxy or browser) and how you can configure these behaviors.

49

Chapter 2: Caching

RelatedResources

There are major topics not covered in this guide but in other documents. These materials are available at the Akamai EdgeControl Management Center athttps://control.akamai.com. After logging in, go to Support -> Documentation.

• TTL overview. For background overview of TTL (time-to-live), including considerations regarding the features and settings to use, rules of precedence, and downstream cacheability settings, see Time-to-Live in Cache: Methods and Considerations.

• Content Control - direct removal or invalidation of objects in cache. For information on actively removing/refreshing objects in Akamai caches see the guide, Akamai Content Control Interfaces.


About Caching and Caching TermsConfidential & Proprietary

About Caching and Caching Terms

Caching in Akamai refers to objects retrieved from an origin, or dynamically created, which are then cached at any number of Akamai servers. The objects can then be more quickly served from cache to end users or used in the creation of dynamic objects.

The two main benefits of caching are to reduce traffic and load on the origin and reduce latency (increase performance) in serving objects to the end client.

Time-to-live Time-to-live is the time period for which an Akamai server may serve an object from cache without revalidating its freshness with the origin server. It is often used as a synonym to max-age (or maxage), as in “setting the TTL.” However, it can also refer to the time remaining in cache for an object that was served some time in the past. An object can be said to have a TTL of 1 hour if it was fetched 3 hours ago with a max-age set at 4 hours. Throughout this document this latter concept is referred to as remaining lifetime to clearly distinguish between the initial setting (max-age or TTL) and the amount remaining (remaining lifetime).

Remaining Lifetime Remaining Lifetime is the time remaining before an object in cache must be refreshed with the origin server.

Static and Dynamic Static content is contant that does not change frequently and is the same regardless of who requests it. Dynamic content changes frequently, often because it is customized for each end user request. Static content is cacheable for at least some period of time, while dynamic content must be retrieved or revalidated for each client request. The benefits of caching are clear for static objects, even if their lifetime is short. Dynamic objects may also benefit from caching in some cases.

Downstream Downstream refers to caching in proxies or clients (browsers) at the end-user side of the content flow. It refers to objects Akamai has served in response to client requests.

Consistency In Akamai, consistency refers to the relationship between an object cached in Akamai servers and the same object at the origin. If the object is the same in both locations, there is consistency. If the object in Akamai cache is different from the one on the origin server, there is a lack of consistency.

Fresh and Stale An object is fresh if its TTL has not expired and the object has not otherwise been invalidated. It is stale if the TTL has expired.

Invalidation Invalidation is a mechanism by which objects are marked for refresh or refetch at a given point in time or on a recurring schedule. This can happen separately from the expiration of the max-age (or TTL).

Refresh The Akamai server will refresh an object by sending a conditional (If-Modified-Since) GET request for the object.

ARL and In-ARL Akamai fetches objects from ARLs, an Akamai Resource Location, which is similar to and looks like a URL, but represents an “Akamaized” location—that is, it is known to and fetchable by Akamai. The ARL representation may contain caching instructions or other coded information, and when it does that information is known as In-ARL data.

Cache Keys Akamai indexes the cached objects with cache keys, which are configurable.


Chapter 2: Caching

Default Caching Behaviors

The following is a brief description of the default caching behaviors of the Akamai server. This is not intended to be and exhaustive discussion, but will help familiarize you with the basics.

Default Time-to-Live An object is assumed to be cacheable for one day if there are no other caching directives applied to the request/response and the response is cacheable. One day is the default max-age for the Akamai cache. Normally every customer configuration file sets the desired default max-age for that customer’s content, and the max-age can be set to different durations based on the nature of the content.

No-store andBypass-cache Override

Max-age

If an object receives a no-store or bypass-cache setting from the edge server configuration file or an Edge-Control response header, that object will not be cached, and the max-age setting for the object is irrelevant. To make the object cacheable, you must turn the no-store or bypass-cache setting off. This is equally true when Honor Cache-Control or Honor Expires is being used to set the TTL for Akamai server cache.

Edge-ControlCacheability Directives

Cacheability settings in an Edge-Control response header take precedence over all other sources of cacheability information. That is, if the Edge-Control header contains a no-store, !no-store, bypass-cache, !bypass-cache, no-cache, or max-age setting, those settings override any corresponding settings from another source (configuration file or Cache-Control header with Honor Cache-Control enabled). Note that Edge-Control: max-age does not override a setting of no-store, no-cache, or bypass-cache from another source; the correct Edge-Control setting would be Edge-Control: !no-store, max-age=1d to both make the object cacheable, and set the max-age.

No-store andBypass-cache Bust

Downstream Caches

If an object receives a no-store or bypass-cache setting, the response to the client (proxy or browser) will contain cache-busting headers to prevent caching downstream. In some cases this behavior is undesirable, because the response should be cacheable to the browser. To allow caching by the client, the configuration must manually remove the cache-busting headers and pass through the origin’s cacheability headers.

Default Downstream-TTL By default, the Akamai server sends the client cacheability headers with a max-age equal to the lesser of the remaining lifetime for the object in Akamai cache or the values sent by the origin server.

Downstream-TTL for ESI Responses that use ESI processing are sent to the client with a max-age setting that is equal to the lowest value TTL for any of the included fragments. This ensures that the client does not cache beyond the point that the response is likely to be stale.

Serving Stale on FailedRevalidation

If the Akamai server fails to contact the origin server when it needs to refresh an object in cache, it marks the object as fresh and continues to serve that stale object until its TTL expires and again requires revalidation. (You can modify this behavior by requiring revalidation success to mark the object fresh or by setting a smaller amount of time for which the object can be refreshed on a failed revalidation.)

Prefresh is Enabled byDefault

Once 90% of the object’s TTL has expired, the Akamai server will refresh the object after serving a client request if that request arrives before the TTL completely expires. This “prefresh” behavior allows the Akamai server to keep the object fresh without


Default Caching BehaviorsConfidential & Proprietary

impacting the response time to clients. As a side effect, popular objects will be requested from the origin server slightly more frequently than the assigned TTL would indicate. You can adjust this prefresh percent.

Jitter of RemainingLifetime

When the Akamai server sends a response object to a peer, it includes an Age: header to indicate how long the response has been in cache since last refresh. This ensures that the lifetime of the object is not extended with each transfer within the Akamai network. The value sent in this header is "jittered" by up to +/- 5% of the TTL, but not more than 30 seconds in either direction. This jittering is done to prevent refresh requests from peers being synchronized with each other.

POST Responses NotCached

By default responses to POST requests are not cached. You can configure the Akamai serve to cache these responses.

Output of ESI ProcessingNot Cached

By default the output of ESI processing is not cached. You can configure the server to configure the output from processing and assign a TTL to this content.


Chapter 2: Caching

A Quick Reference to Caching Topics

If You Want To Do This… See This Feature… Page

Basics

Set max-age on objects using edge server configuration or EdgeControl response Header

Cache Control – Time-To-Live (TTL) 63

Set the max-age or Expires data using HTTP Cache-control or Expires

Honor HTTP Cache-Control:max-age and Expires Headers

66

Mark content to be refreshed at a specific point in time or on a particular schedule

Scheduled Invalidation 70

Require revalidation before an object can be served after its TTL has expired

Require Revalidation 72

Require IMS (If-Modified-Since) request with every client request, using TTL=0.

Zero-TTL Content 73

Use no-store (no-cache) and bypass-cache Uncacheable Content (no-store and bypass-cache)

61

Use prefresh (asynchronous refresh, not waiting for a client request to refresh objects) with other caching options to increase performance and reduce latency

Asynchronous Refresh (prefresh) 75

Advanced

Limit the refresh requests to the origin. Limiting Refresh Requests to the Origin 83

Set a TTL on error responses to refresh attempts Error Response Time To Live (Negative TTL) 84

Use Entity Tags Entity Tag Validation Support 80

Cache 302-Redirects by default Cache 302 Responses by Default 86

Cache POST responses Cache POST Responses 82

Downstream

Manage caching downstream of Akamai, including busting caches and handling browser issues

Downstream Caching 89


Cacheable ResponsesConfidential & Proprietary

Cacheable Responses

The primary factor in deciding whether a response can be cached is the HTTP status code of the response. The table below summarizes Akamai server behavior with respect to cacheability of the origin response based on the response code. (These are the default cacheability behaviors. You can make additional status codes cacheable with configuration settings as described below in this section.)

Cacheability: Unless noted otherwise, the object is not cached. In particular, unknown response codes (between the range of 100 and 600) are passed to the client and not cached.

Evicts existing entry: Unless noted otherwise the existing entry is not evicted.The term "existing entry" refers to a stale object in cache. Because the object is stale, the server forwards a request to the origin server to revalidate the object freshness, and the response returned by the origin (or generated by the Akamai server itself ) determines whether the object (the "existing entry") is evicted or refreshed.

Response Code Cacheability Evicts existing entry

Informational 1xx

100 Continue*

Successful 2xx

200 OK cached yes

201 Created

202 Accepted

203 Non-Authoriative Information * cached yes

204 No Content negatively

205 Reset Content *

206 Partial Content *

Redirection 3xx

300 Multiple Choices cached yes

301 Moved Permanently cached if no redirect chase c

302 Moved Temporarily cached if expiry info if no redirect chase c

303 See Other *

304 Not Modified

305 Use Proxy (proxy redirect) * negatively

307 Temporary Redirect*

Client Error 4xx

400 Bad Request negatively (if origin) a no b

401 Unauthorized

402 Payment Required *

403 Forbidden negatively if configured d

404 Not Found negatively yes

405 Method Not Allowed * negatively yes

406 Not Acceptable *

407 Proxy Authentication Required *

408 Request Timeout *

409 Confict *


Chapter 2: Caching

Notes to the Table

Following are explanations of the footnote symbols in the table.

* These Response Codes are HTTP 1.1

a These errors (400, 500, 502, 503, 504) are negatively cached only if they come from the forward server and the cache:preserve-stale-objects metadata is set to "off". If the Akamai server generates a 503 or a 504 error (due to name lookup failures or connectivity problems) the errors are not negatively cached. Also, if the requested object is in cache, rather than serve the error, the Akamai server will serve the object stale unless the must-revalidate or authorization metadata is turned on.

b If the cache:preserve-stale-objects metadata tag is "off" these errors will evict the requested object from cache. This tag is "on" by default, and exists to handle some situation in which it is desirable to have the objects evicted in favor of the error.

c When redirect chasing is "off," a 301 or 302 response evicts the existing entry. When redirect chasing is "on" the response does not evict the existing entry; the server defers this decision until the chase is complete. Then, the final response determines whether the existing entry is evicted. Note that a 302 response evicts the existing entry, even if it is determined to be uncacheable itself. There is more information on caching of 302 responses below.

d Responses to 403 requests can be made cacheable by setting the metadata tag cache:cache-403..

410 Gone * cached yes

411 Length Required *

412 Precondition Failed *

413 Request Entity To Large *

414 Request-URI Too Long *

415 Unsupported Media Type

Server Error 5xx

500 Internal Server Error negatively (if received) a no b

501 Not Implemented negatively (if received) yes

502 Bad Gateway negatively (if received) a no b

503 Service Unavailable negatively (if received) a no b

504 Gateway Timeout * negatively (if received) a no b

505 HTTP Version Not Supported *

Response status codes less than 100 or greater than 600 are automatically converted to a special error on the forward-side functions, and the client receives "502 Bad Gateway" error. If the origin server wants to send a custom status code, it must fall within this range. Also, the reason phrase of a cached response (for example, OK, Not Modified, Not Found, etc.) is fixed in the code and cannot be altered. For uncacheable responses, you can pass the origin server’s reason phrase to the client by setting the metadata edgeservices:modify-incoming-response.pass-reason-phrase.



Factors ThatImpact

Cacheability

This section discusses some of the factors that determine whether or not a response is ultimately cacheable. While the HTTP status code may indicate that the response can be cached, there may be other properties of the request or response that prevent caching. Following is s list of some of those properties.

Request Method Many request methods result in uncacheable responses. Here is a brief summary of how the Akamai server treats the primary request methods:

GET and HEAD responses are cacheable by default

PUT, DELETE, and OPTIONS responses are uncacheable, and there is no mechanism to make them cacheable.

POST responses are uncacheable unless the cache:post-caching metadata is enabled. Even when the post-caching metadata is enabled, the response may be uncacheable if the request does not meet size and Content-Type requirements.

Responses to WebDAV methods are uncacheable, though it is possible to configure PROPFIND as a cacheable request method. See the description of WebDAV support in the EdgeServices chapter.

No-store orBypass-Cache

Metadata

If bypass-cache metadata applies to a request/response, the response is not cacheable.

If no-storemetadata applies to a ’positively’ cacheable request/response (such as a 200 response to a GET request), the no-store setting renders the response uncacheable. (Negatively cached responses are not affected by a no-store setting.)

Both no-store and bypass-cache can be set in either the customer's configuration file (arl.data) or in response headers.

Vary: Headers Responses that contain a Vary: header with a value of anything other than "Accept-Encoding" (and with a corresponding Content-Encoding: gzip header) are not cacheable. This is because the Vary: header would be indicating that the response could be different even though the URL is the same: the response varies on a characteristic of the request other than the URL. To make these responses cacheable, you must remove the Vary: header (preferably at the origin server). If it is necessary to cache different versions of a file based on some other property (such as User Agent or Cookie value), you can accomplish this using the Flexible Cache ID feature described in this guide.

Caching a 302 302 responses are cached only if

• they contain an Expires header (with any value), or

• they contain a Cache Control: max-age header (with a value >= 0), or

• they have been made cacheable by default with cache:cache-302, explained below.

The cacheability of the response is based on the existence of these two headers with the required values. Without one of these headers, the response is not cached.(Notice that a 307 Temporary Redirect response is uncacheable; it does not currently behave as a 302 response would in Akamai server 5.6.4.)


Chapter 2: Caching

If the 302 is cacheable, it will be cached under the same TTL a 200 response would have received based on the metadata settings (arl.data, Edge-Control headers, HTTP headers).

Based on the above, an Edge-Control header to set a max-age in the absence of Cache-Control or Expires headers will not by itself cause the response to be cached, because the decision will be that the response is not cacheable, and the max-age will not be relevant.

Caching 302's by Default

You can configure the Akamai server to cache 302 responses by default by setting the following tag in the customer's configuration file:

<cache:cache-302>on</cache:cache-302>

Note that this makes the response "cacheable." It does not guarantee that the response will be cached. Whether or not the response is cached can be influenced by any of the normal factors (no-store or bypass-cache metadata, other feature metadata, etc.).

Also, setting this tag to "off" does not make the 302 uncacheable. Off is the default setting for the tag, and in that setting the cacheability of the response is determined by Cache-Control and Expires headers as explained above.

Other FeatureMetadata

Following is a listing of some features of the Akamai server that can result in a response being treated as cacheable or uncacheable, depending on the effect of the feature.

Additional (Cacheable) Status Codes

The listing of cacheable HTTP Satus Codes in the table above indicates the default behaviors of the Akamai server. For example, a 200 status response is "positively" cacheable, meaning that it uses the regular cache:max-age setting for the response to determine its time-to-live. Similarly, a 404 status response is "negatively" cacheable, meaning it takes its time-to-live from the cache:negative-ttl setting.

Many status codes, such as 414, do not have their cacheability specifically defined and are treated as uncacheable by default. Status codes in the range from 100 to 600 that are not already defined as positively or negatively cacheable can be made cacheable with settings in the configuration file to specify the status code and whether it should be cached positively or negatively.

Negative Cacheability

Responses that are cached "negatively" do not take the time-to-live specified for the normal (200 OK) response. Instead, these objects are cached based on the negative-ttl setting. This defaults to 10 seconds on the edge server, but can be set to a different value for each customer in their EdgeSuite configuration file (arl.data). The original negative-ttl metadata (cache:negative-ttl) does not allow for setting a different TTL based on response status code.

You can define a negatively cached response code to use an individualized TTL setting through use of the metadata <cache:negative-ttl2>. This metadata can be



applied within a match on the desired response code (usually 404) to give these responses a longer or shorter setting than defined by cache:negative-ttl.

Flexible Cache ID Feature (cache:key.force metadata)

When the Flexible Cache ID feature is used to construct the cache key, a request/response is treated as "uncacheable" if the request doesn't match any of the rules defined for the Cache ID. A common mistake is to include a request header value in the Cache ID rule, but not provide a default rule for the case when the header is not present in the request.

Popularity Threshold

If the Popularity Threshold metadata (cache:popularity-threshold) is used, the response is not cacheable until it reaches the required threshold.

Hash Serial and Forward

When the hash-serial-and-foward metadata <forward:hash-serial-and-forward> is used, the response is not cacheable on the edge server that received the client request, unless that server is also the one to handle the hash-serial request.

Factors ThatImpact

Eviction

This section discusses some of the factors that determine whether or not an existing entry is evicted from cache when a new response is received.

Preserve-stale-objects Metadata

As explained in the notes to the Table above, status codes 400, 500, 502, 503, and 504 normally do not evict the existing entry from cache. When the Akamai server generates these errors, they are not cacheable. When they are received from the origin and cache:preserve-stale-objects is "off," these responses will evict the existing entry and be cached under the negative-ttl setting.

No-storeMetadata

If no-store metadata applies to the request, it evicts the existing positively cached entry from cache. (No-store metadata will not affect negatively cached responses.) This metadata can be set in either the customer's configuration file (arl.data) or in response headers.

Bypass-cacheMetadata

If cache:bypass metadata applies to the request, it does not evict the existing entry from cache. This metadata can be set in either the customer's configuration file (arl.data) or in response headers.

If both no-store and bypass-cache are applied to the request at the same level of precedence (both in configuration file or both in response header), no-store takes precedence over bypass-cache, and the existing entry is evicted. Otherwise, as is normally the case, a setting in a response header takes precedence over a setting in the configuration file.


Chapter 2: Caching

Chase-redirectsMetadata

As mentioned in the notes to the table above, when edgeservices.redirect.chase.status is "on," the Akamai server will defer the decision whether to evict the existing entry until the redirect chase is complete. the server will then base the eviction decision on the final response. Otherwise, a 301 or 302 response evicts the existing entry.


Uncacheable Content (no-store and bypass-cache)Confidential & Proprietary

Uncacheable Content (no-store and bypass-cache)

By default, an origin response is assumed to be cacheable unless there is something about the response that renders it uncacheable (presence of a Vary header, for example).

These features (bypass-cache and no-store) instruct the Akamai server not to serve the request from cache and not to store the response from the origin in cache, but to forward it to the client. There are a few situations where this may be useful:

• Some content is highly personalized (is different for each end user) and can only be assembled at the origin server. This content should not be cached, because it cannot be properly served to more than one client.

• Java applets and Shockwave applications that need to pass information back to the origin server may have difficulty unless the requests are passed unaltered.

• The origin server may be using a very small object to set a cookie on the client browser. If the cookie needs to be set on every request, and the response that contains the cookie is very small, it is better to use no-store or bypass-cache than zero-TTL, which would result in an IMS request. (It’s more efficient to serve a very small object through no-store than to process an IMS request.)

There are two options for ensuring that an object is not stored in cache, or served from cache:

• no-store instructs the Akamai server not to serve the request from cache, not to store the origin response in cache, and to remove any existing object from cache.

• bypass-cache instructs the Akamai server not to serve the request from cache, not to store the origin response in cache, but to leave any existing object in cache.

The bypass-cache option is useful when the origin server is sending an alternate response to a client. For example, if the origin server sends a 302 redirect in response to a failed authorization, the response should include an Edge-Control: bypass-cache header to prevent this alternate response from evicting the requested object from cache.

If both no-store and bypass-cache are set for the same object using the same mechanism (response headers or configuration file) no-store takes precedence over bypass-cache. If they are set using different mechanisms, the more specific setting (response header) takes precedence.

Integration No-store and bypass-cache can be set using either HTTP response headers or configuration files.

By HTTPResponse Header

You can specify no-store or bypass-cache using the Edge-control header. This metadata element takes no argument.

For example:

Edge-Control: no-storeEdge-Control: bypass-cache

You can also un-set no-store or bypass-cache using an Edge-Control header with the


Chapter 2: Caching

exclamation mark (!).

Edge-Control: !no-storeEdge-Control: !bypass-cache

By ConfigurationFile

You can mark content to be handled as uncacheable by setting this option through Configuration Manager. In the Configuration Manger, No-Store is a subset of the feature called “Time To Live Rules.”

Note: no-store and bypass-cache override cache-maxage. If both cache-maxage and no-store (or bypass-cache) are set, the object is not stored.


Cache Control – Time-To-Live (TTL)Confidential & Proprietary

Cache Control – Time-To-Live (TTL)

Time-to-live is the period for which an Akamai server may serve an object from cache without revalidating its freshness with the origin server. This term is roughly synonymous with the max-age component of the HTTP Cache-Control header. However, max-age (either in the HTTP header or in the edge server configuration file) is just one specific mechanism for setting the time-to-live for an object.

TTL is sometimes used loosely to mean “the time remaining before the object must be refreshed.” An object may be said to have a TTL of 1 hour if the max-age was set at 3 hours and 2 hours have already past since the object was placed in cache. Throughout this document this latter concept is referred to as remaining lifetime to clearly distinguish between the initial setting (max-age or TTL) and the amount remaining (remaining lifetime).

For a detailed discussion of Time-To-Live, see Time-to-Live in Cache: Methods and Considerations. This document is available on the Akamai EdgeControl Management Center at https://control.akamai.com.

Generally speaking, the time-to-live should be set for a period that represents the stalest acceptable response to the client.

The TTL for an object can be set through multiple mechanisms. The primary mechanisms are the max-age setting in the configuration file and an Edge-Control: maxage response header sent with the object by the origin server.

In the case where an object’s TTL is set in more than one location, the order of precedence of the primary mechanisms for determining time-to-live for an object in cache is, from highest to lowest:

• In-ARL TTL

• Edge-Control: maxage header

• Content provider configuration file cache-maxage


Chapter 2: Caching

Integration The time-to-live for an object can be set through HTTP Edge-Control response headers and configuration files, or it can be set by HTTP Cache-control or Expires headers as discussed in this chapter. (Further, the TTL can also be set through ESI markup, but that topic is beyond the scope of this document. See the ESI Developer’s Guide for more information.)

By HTTPResponseHeaders

You can specify time-to-live in a response header using the Edge-Control header cache-maxage. Examples:

Edge-control: cache-maxage=90mEdge-control: cache-maxage=1hEdge-control: cache-maxage=5d

Cache-maxage takes as its content an integer followed by a unit specifier. Current unit specifiers are: 's' (seconds), 'm' (minutes), 'h' (hours), 'd' (days); these are not case sensitive.

The Edge-control header also accepts syntax similar to Cache Control: max-age.

Edge-Control: max-age=90

That is, you can spell “max-age” with the hyphen, and list a number of seconds

Note: TTL and the Vary Header. The presence of a Vary: header with a value other than “Accept-Encoding” causes the response to be uncacheable. The Vary header must be removed to make the objects cacheable. Even if the Vary header has the value "Accept-Encoding", the object would become uncacheable if the object does not use gzip compression. In these cases the Vary header must be removed to make the objects cacheable. If you need to send responses that differ based on something other than the request URL, such as a header value, you can achieve this functionality and make the responses cacheable by using the Flexible Cache ID feature.

Note: TTL and Cache Index. The TTL setting is not used as part of the index to an object in cache; changing the TTL does not result in Akamai servers caching a new object.

Note: Age Header in Response. The Age header is the mechanism by which a caching server informs others of how long the object was held in cache before being served. Akamai servers use this header when communicating with each other. The origin server should not send an Age header in its response to the Akamai server, because the value of the header will be subtracted from the max-age for the response and reduce its remaining lifetime. At this time it is not possible for the Akamai server to remove an Age header sent by the origin server.


Cache Control – Time-To-Live (TTL)Confidential & Proprietary

without the explicit “s”.


All Web sites served through Akamai must have a default cache-maxage established at the time the configuration file is first created. This default maxage is a required "global setting" in the request to set up the account.

You can directly control the max-age settings for your content through Configuration Manager, where the features is called “Time To Live Rules”.

Important: no-store, bypass-cache, and max-age are separate directives, and both no-store and bypass-cache take precedence over max-age. As a result, if the configuration file sets no-store or bypass-cache metadata for an object, setting max-age by itself through Edge-Control headers will have no effect. To set the max-age and cause the object to be cached, you will need to also turn off no-store and/or bypass-cache. For example:

Edge-control: cache-maxage=90m,!no-store,!bypass-cache

Note that the directives are comma-delimited with no space characters.


Chapter 2: Caching

Honor HTTP Cache-Control:max-age and Expires Headers

Akamai servers generally ignore HTTP Cache-Control and Expires headers in responses from origin servers and use only their own mechanisms to determine the freshness of an object.

If set to honor HTTP Cache-Control or Expires headers, however, Akamai servers will use some of the Cache-Control or Expires values to determine the time-to-live (TTL) for the object. In addition, Akamai servers can honor Cache-Control extensions implemented in Internet Explorer, as described in this section.

This feature may be useful to you if you are accustomed to using these headers to control downstream cacheability, because you do not need to specify a separate Edge-Control: cache-maxage header to set the lifetime of an object in Akamai cache. In particular, the Honor Expires feature allows you to set a specific date and time for content to expire rather than rely on a TTL setting.

When combined with use of the Edge-Control: cache-maxage header, this feature also makes it possible to explicitly bust caches downstream from Akamai while permitting Akamai to cache the objects.

Caveats The Honor Expires feature should be used with care. It is most appropriate where the origin server sets an expiration time that corresponds to the time the object will actually change. If the object does not change at a specific time there is no reason to indicate a specific expiration, and a Cache-Control: max-age setting is the more appropriate mechanism for maintaining freshness.

Akamai servers do not honor the must-revalidate setting in the Cache-Control header.

TechnicalDetails

When Honor Cache Control is enabled, the Akamai server will honor the following settings from the Cache-Control header sent by the origin server:

• max-age

• no-store

• no-cache (however, it behaves like no-store: the object is not cached)

• pre-check (serves as a max-age setting if there is no max-age)

• post-check (serves as an Akamai Prefresh setting)

No other Cache-Control directives are honored through the Honor Cache Control feature. However, it is possible to write separate configurations to mimic the behavior of honoring private and must-revalidate directives

Precedence When Honor Cache Control and Honor Expires features are enabled, the Cache-Control and Expires headers take precedence over corresponding cacheability settings in the configuration files, but will not override TTL settings in


Honor HTTP Cache-Control:max-age and Expires HeadersConfidential & Proprietary

an ARL or the Edge-Control: response header if one is included. So, the order of precedence from highest to lowest for determining the object lifetime in Akamai cache is:

• In-ARL TTL (This is relevant only when using the legacy FreeFlow service ARL format.)

• Edge-Control: response header containing a recognized cacheability setting (no-store, !no-store, bypass-cache, !bypass-cache, or max-age).

• HTTP Cache-Control: header containing a cacheability setting (no-store, no-cache, max-age)

• HTTP Expires header

• Customer-level edge server configuration file cache-maxage

You should also remember that no-store/no-cache and max-age are separate directives that can all apply to the same response. When multiple conflicting directives appear in the Cache-Control header, the most restrictive behavior takes precedence. So, if your Cache-Control header is:

Cache-Control: max-age=600, no-store

the response will not be cached, and it will evict any pre-existing response from cache, because no-store is the most restrictive behavior. In the presence of a no-store setting, a max-age setting is meaningless.

This behavior also applies to settings in different contexts. For example, if the Cache-Control header is set with a max-age of five minutes, but cache:no-store is set in the configuration file for this request/response, the response will not be cached. To make the response cacheable, you would need to turn cache:no-store off, and there is no way to do this through a Cache-Control header. In short, if you want to control cacheability with the Cache-Control header, you must first ensure that the objects are cacheable according to the configuration file.

Edge-Control Negates Honor-Cache-Control and Honor-Expires

The current code for honoring Cache-Control and Expires headers completely skips evaluation of the headers if there is an Edge-Control header that contains a cacheability statement (no-store, bypass-cache, or max-age). Unfortunately, the code is written such that an Edge-Control: !bypass-cache or Edge-Control: !no-store will also cause the Cache-Control and Expires headers to be ignored. As a result, it is not possible to turn off cache:no-store or cache:bypass settings in the configuration file through use of an Edge-Control header, and also set the max-age with a Cache-Control header. It’s necessary in this case to set the max-age with the Edge-Control header.

ControllingAkamai Cache

With HTTPHeaders

In the absence of other settings that would take precedence, the following is the simple version of how Cache-Control: maxage and Expires headers are used:

• If Honor Cache Control is “on” and the Akamai server receives a Cache-Control: max-age header in the response from the origin server, it uses that setting for the lifetime of the object. Note that Cache-Control: no-store


Chapter 2: Caching

and Cache-Control: no-cache are honored along with Cache-Control: max-age.

Cache-Control: private and Cache-Control: must-revalidate are not automatically honored, but it is possible to mimic these behaviors through separate settings in the customer configuration file.

• If Honor Expires is “on” and the Akamai server receives an Expires header in the response from the origin server and the expiration is in the future, the Akamai server uses the “implicit max-age” (the Expires minus the Date) as the lifetime for the object.

To evaluate the tokens in the Cache-Control header, the Akamai server looks at the individual strings (separated by commas if there is more than one) or prefix sub-strings where the sub-string is what comes before an equal sign ‘=’.

For example:

Cache-control: no-cache="set-cookie,set-cookie2"

The above setting would be interpreted as a no-cache directive.

Headers inResponses to

Clients

In the response to clients, if the Akamai server receives a Cache-Control: max-age header from the origin, it sends a Cache-Control: max-age header to the client, with the value set to the remaining object lifetime in Akamai cache.

If the Akamai server receives an Expires header, and the implicit max-age (Expires minus Date) is greater than zero, it adds an Expires header equal to "now + implicit maxage" in the response to the client. (The Expires header is never sent with a value less than "now.")

This behavior for Expires headers preserves the downstream cache busting capabilities of the origin server (more below).

Busting AllCaches (Including

Akamai)

If the configuration file sets an object as un-cacheable (no-store), or if the Akamai server receives a response from the origin server that includes Edge-Control:no-store, the Akamai server does not store the object, and it busts downstream caches. To bust downstream caches, it sends the following HTTP headers in the response to the client:

Expires: nowCache-Control: max-age=0Cache-Control: no-storePragma: no-cache

This cache-busting behavior also applies if:

• honor-cc is "on" and the Akamai server receives HTTP Cache-Control: no-cache or Cache-Control: no-store headers in a response from the origin server.


Honor HTTP Cache-Control:max-age and Expires HeadersConfidential & Proprietary

• honor-expires is "on" and the Akamai server receives an Expires header in the past but no Cache-Control: max-age header.

BustingDownstreamCaches Only

With these settings, it is possible to have Akamai cache an object, but bust the caches downstream, and control all cacheability settings from the origin server. To do this, you would use both an Edge-Control: cache-maxage header and Cache-Control: no-store and/or Expires headers. For example:

Edge-Control: cache-maxage=1hCache-Control: no-storeExpires: “now”

This would cause the Akamai server to cache the object for one hour, but pass the Cache-Control: max-age and Expires: “now” headers to the client on every request. You can accomplish similar behavior by using the Set Downstream Cacheability feature, but in that case the downstream cacheability setting is relatively static, as it can only be changed in the configuration file.

Cache-ControlExtensions in

Internet Explorer

Internet Explorer allows a post-check and a pre-check parameter in the Cache-Control HTTP header as specified at http://msdn.microsoft.com/workshop/author/perf/perftips.asp.

If the Honor Cache-Control features is enabled, Akamai servers will honor these two parameters. Pre-check serves as the TTL and post-check as the akamai-prefresh setting.

In other words, until the number of seconds specified in post-check elapse, Akamai servers serve the content from cache. After this interval, the object is refreshed after the object is served from cache. If the specified interval in pre-check is reached, the object is refreshed before it is served to the client.

Both parameters are defined in seconds.

No-cache, no-store, and max-age Cache-Control headers take precedence over pre-check.

These headers are passed both downstream and upstream, and when no-store is set, Akamai servers bust the cache downstream.

Integration You can directly control the Honor Cache-Control and Honor Expires behaviors through Configuration Manager, where these features are called “HTTP Cache-Control Headers” and “HTTP Expires Headers”.

Note: This cache busting behavior for Expires headers does not apply to ARLs that include a time-to-live. As indicated above, in-ARL TTL still takes precedence over Cache-Control and Expires headers. The cache busting behavior does apply to any URL or ARL that takes its coherence setting from configuration files.


Chapter 2: Caching

Scheduled Invalidation

Scheduled Invalidation provides a mechanism for "expiring" content on the Akamai server without actively purging the content. This is particularly useful for content providers who republish their site on a regular schedule and need to expire a large quantity of data.

For example, a content provider could indicate that all content for their site that was stored in cache before Sunday, January 8, 2005 at 11:00PM should be refetched after that time. If the content provider then republished their site on January 8th, they could be assured that end users would receive only fresh content after the refetch timestamp.

You can also have this invalidation applied on a recurring basis. For example, you could schedule content to be invalidated every evening at 11:00 PM to match the publishing schedule of a news site.

Caveats Scheduled Invalidations may significantly increase load on the origin servers at the time of expiration. Because all Akamai servers will simultaneously treat content as expired, they will all need to refetch or revalidate content upon receiving the first client request for content after the expiration time (revalidation occurs only on a client request). Obviously the expiration should not be set for a known high-traffic time for the web site.

Usage Notes Scheduled Invalidation sets an expiration time against which each object's timestamp is compared before the object is served. If the object's timestamp is before the expiration time, the object must be refetched or revalidated before serving.

You can specify whether the object can be refreshed with an If-Modified-Since request or must be refetched with a full GET.

When an Akamai server retrieves an object from a peer, it compares that object's new timestamp, minus its Age, with the expiration time to determine whether the object is expired. This avoids the problem of serving objects with timestamps that are more recent than the expiration time when the underlying object is actually older.

The time settings for Scheduled Invalidations can be specified either as an epoch time based on UTC, or as a ‘Time.” When the epoch time format is used, there is no adjustment of the value for daylight saving time. When the “Time” format is used with a timezone parameter, the value can be automatically adjusted for daylight saving time.

This feature can be applied with the same granularity as most other features. That is, it can apply to an entire site or a single object.

Important: Scheduled Invalidation is not a substitute for purging content if the content must be invalidated on short notice. New configuration settings are deployed to the network several times per day. This means a potential delay of hours to invalidate content using Scheduled Invalidation.


Scheduled InvalidationConfidential & Proprietary

Integration The Integration Consultant should submit a provisioning request that includes:

• The time at which the invalidation should occur

• If desired, the interval for recurrence of the invalidation (that is, daily, weekly, etc.)

• Whether the invalidation should cause a full GET request for the content or an If-Modified-Since refresh.


Chapter 2: Caching

Require Revalidation

By default, if an Akamai server receives a request for an object that is stale in cache, and the origin server cannot be reached to revalidate the object, the Akamai server will serve the stale object to the client.

If you want to ensure that stale objects are not served, you can instruct the Akamai server to serve an error (504 or 503) rather than serve a potentially stale object in the event that the origin server cannot be reached. This condition is strict coherence. For example, you might prefer to serve an error than serve a potentially old stock quote.

Caveats There are no caveats other than that this feature should be used only where truly necessary.

Integration You can instruct Akamai servers to require revalidation through either HTTP response headers or the configuration file.


The response header metadata component must-revalidate instructs Akamai servers not to serve a cached object that may be stale and cannot be revalidated. For example:

Edge-control: must-revalidate

By ConfigurationFiles

The Integration Consultant should submit a provisioning request that includes the basic required information. No additional information is required.


Zero-TTL ContentConfidential & Proprietary

Zero-TTL Content

Zero-TTL (cache-maxage=0s) causes Akamai servers to contact the origin server on every request to ensure that the cached object is still fresh before serving it to the client. This behavior is useful if:

• The content is extremely time sensitive but is not dynamic—does not change on every request. For example, the headlines for a news oriented site might be treated with a zero-TTL so that a change in the headline is recognized immediately by the Akamai servers.

• The content is static but the origin server needs to set a cookie on the client browser. (Set Cookie headers are passed by the Akamai server only if the response is synchronous with the request. That is, the response that contains the Set Cookie header must be a response to the particular request, not previously stored for a prior request.)

• The content provider needs real-time feedback on site usage. With zero-TTL the origin can receive and log each request without serving the content itself. (However, using the Asynchronous Refresh (page 75) feature is often a better way to obtain the same result without having the client wait for the origin response.)

Caveats • This feature is primarily useful for large objects that are not dynamically generated. An If-Modified-Since request takes time to process and adds more load to origin servers than simply serving a small object.

• The Akamai server can send an If-Modified-Since request to revalidate an object only if the object includes a Last-Modified header. In the absence of a Last-Modified header, the Akamai server makes its request to the origin server as a full GET request.

• Like No-Store, this feature is best restricted to a particular directory or directories on the Web site’s origin server or to particular file types.

Usage Notes On the surface, Zero-TTL looks a lot like No-Store: every time Akamai's edge servers receive a request for an object, the request is forwarded to the origin server, regardless of whether the object has already been fetched and stored. Zero-TTL offers some similar benefits to No-Store: the content provider can immediately log all traffic, and they can replace stale objects immediately and achieve perfect coherence between the edge servers and the origin without having to use a purge utility tool.

What differentiates Zero-TTL from No-Store is that when Zero-TTL is used, Akamai's servers will cache the fetched objects. The servers forward an HTTP If-Modified-Since (IMS) request instead of a full GET at each request.

If the object has not changed, the origin server returns a 304 Not-Modified response, and Akamai serves the cached version. This can result in significant bandwidth savings for the Zero-TTL over the No-Store.

Also, if the origin server cannot be reached, the Akamai server can serve the object in cache rather than serve an error.

If you are interested in the benefits of Zero-TTL, you should also look at the


Chapter 2: Caching

Asynchronous Refresh feature. It can offer similar benefits (other than passing cookies) but without requiring the client to wait for the origin response, because Asynchronous Refresh can be configured to contact the origin server on every request after the client has been served.

Integration Zero-TTL can be set using HTTP response headers or configuration files.

By HTTPResponse Header

You can specify Zero-TTL in a response header using the Edge-control header cache-maxage. For example:

Edge-control: cache-maxage=0s




Asynchronous Refresh (prefresh)Confidential & Proprietary

Asynchronous Refresh (prefresh)

This feature lets you specify when an object should be asynchronously refreshed before it expires. Asynchronous refresh, or prefresh, means that if the object is requested after the asynchronous refresh period has begun but before the time-to-live has expired, the Akamai server will refresh (with an IMS request) the object after the client is served.

Akamai Prefresh specifies a time, as a unit of time or as percentage of the object’s TTL setting, after which an object will be refreshed with the origin server after a client has requested and been served the object.

Enabling Asynchronous Refresh has several benefits or applications:

Performance in serving clients is improved, since latency in serving objects is decreased. The clients are less likely to wait for a revalidation with the origin when the objects are kept fresh asynchronously.

• Time-sensitive content can be kept almost perfectly up-to-date without delaying the response to the client. For example, a news site may want the headlines current, but not want to delay responses to clients. You could configure the Akamai server to refresh asynchronously on every request, while setting the time-to-live to several minutes. When the headlines are changed, only one end user (per Akamai server) would potentially receive the old headline.

• Web sites can achieve real-time logging of end user activity at the origin without serving the content themselves, and without having the user wait for the origin response. As above, this is achieved by instructing the Akamai server to refresh asynchronously after every request.

Caveats If the content on the origin server changes during the asynchronous refresh period, the first request (per Akamai server) after the change may be served stale content. Asynchronous refresh should not be considered a substitute for an appropriate TTL setting. The time-to-live should be set for a period that represents the stalest acceptable content.

An If-Modified-Since request takes time to process and adds more load to origin serves than just serving a very small object. Asynchronous Refresh should be used to contact the origin server on every request only if the cost to deliver the object body is greater than the cost to process the If-Modified-Since request.

Default Behavior In general, the following rules apply to refresh:

• If the object has expired, the Akamai server revalidates with the origin server synchronously (before serving the object) with an If-Modified-Since (IMS) request.

Asynchronous Refresh is currently enabled by default with a setting of 90%. This means that for all requests, if a client request is received in the last 10% of the time-to-live, the Akamai server performs an asynchronous refresh of the content.


Chapter 2: Caching

• If the object has not yet expired when a request is received, the content is served from cache. If the expiration time of the object was within the specified prefresh-percent (10% before expiration) at the time of the request, the Akamai server revalidates with the origin server asynchronously (after serving the object) and updates the timestamp of the object. This results in the object remaining fresh for the length of another time-to-live.

Behavior WithAkamai Prefresh

When the Asynchronous Refresh feature is used, the Akamai server's refresh behavior is modified by the additional parameter cache:prefresh

The value of akamai-prefresh can be expressed as either a percent (%) or a time. In either case, the setting is relative to the time the object was last refreshed and specifies the period before the Akamai server will asynchronously refresh the object with an IMS request. If the object reaches its TTL expiration, the object is synchronously refreshed on a subsequent request.

Akamai-prefresh has a default value of 90%.

Examples Following are examples of how prefresh interacts with TTL settings to determine the point at which an object is revalidated.

Prefresh After 80% of TTL Expired

Set cache:max-age (TTL) to whatever is appropriate for the content.

Set cache:prefresh to 80% in the configuration file.

In this case, the Akamai server will not do any revalidation on the object until 80% of the TTL passes from the time the object was refreshed. After that, the object will be refreshed asynchronously. When the object expires (the TTL is reached), it will be synchronously refreshed.

Synchronous Refresh on Every Request for the Object

Set cache:max-age (TTL) to zero.

The cache:prefresh setting is not relevant in this case, because the time-to-live will always have expired and the content must be refreshed synchronously.

La

st Re

fresh

Total TTL

akam

ai-p

refresh

no refresh asynchronous prefreshsynchronous refresh


Asynchronous Refresh (prefresh)Confidential & Proprietary

Asynchronous Refresh on Each Request Unless the TTL Expires

Set cache:max-age (TTL) to whatever is appropriate for the content.

Set cache:prefresh to 0%.

The Akamai server will revalidate the object after each client request is served. If the TTL expires, the object will be synchronously refreshed on the next request.

Integration The Integration Consultant should submit a provisioning request that includes the basic required information and explicitly states the following:

• The setting desired for asynchronous refresh. Be very clear whether the request is for a percent or a time and what the time units are.

• The expected behavior when asynchronous refresh is enabled. (This is to provide a check to ensure that the default TTL has been correctly considered and that the desired effect will be achieved.)

If the content provider needs direct control over the akamai-prefresh setting and can make this setting as an absolute number of seconds, this can be accomplished by turning on the Honor Cache-Control headers feature and setting a Cache-Control: post-check= header. See “Cache-Control Extensions in Internet Explorer” on page 69.

If you configure akamai-prefresh at 0% you should also configure the Akamai server to send a prefresh request for each client request. By default the Akamai server will make a prefresh request for an object only once. If other clients request the same object while the server is waiting for the origin to respond to the prefresh request, the clients are served from cache, but no new prefresh request is created.


Chapter 2: Caching



In This Chapter

Entity Tag Validation Suppo

Cache POST Responses • 8

Limiting Refresh Requests t

Error Response Time To Live

Preserve Stale Object on Err85

Cache 302 Responses by De

Quick If-Modified-Since Res

Serve Only If Cached • 88

3
Caching - Advanced
rt • 80

2

o the Origin • 83

(Negative TTL) • 84

or Response Codes •

fault • 86

ponse • 87

This chapter discusses some of the less frequently used controls over cacheability of content or the coherence of content on Akamai servers with that on the origin server. Many of these features are used to modify or fine tune the behavior of basic caching features.

79

Chapter 3: Caching - Advanced

Entity Tag Validation Support

You can configure the Akamai server to support the use of entity tags (ETags) to validate a client request with the object in cache, or the object in cache with the response from the origin server. This is useful for ensuring consistency across caches when objects are republished in place with the same URL.

Caveats The current implementation does not support use of the If-Match header in the client request.

TechnicalDetails

When this feature is enabled, the value of an If-None-Match header in the client request is compared against the value of the ETag header in the cached response to determine whether the client should receive a new object or a 304 Not-Modified response. If the value of the If-None-Match header in a GET or HEAD request matches the ETag, the response is a 304 Not Modified. (If a method other than GET or HEAD is used, the response is a 412 Precondition Failed, as required by the specification.)

Enabling this feature does not require that the client use the If-None-Match header; it simply enables the comparison functionality if the If-None-Match header is used. When the feature is off, the Akamai server ignores the If-None-Match header.

The Akamai server will include an If-None-Match header in requests to revalidate content with the origin server so that the origin can determine whether the object in Akamai cache is still valid based on the ETag.

This feature doesn’t change how the Akamai server determines the freshness of an object in cache. Time to Live settings are used to determine when the object must be revalidated.

ETag andIf-Modified-Since

If the client request contains both an If-None-Match header and an If-Modified-Since header, the Akamai server will serve a 304 Not-Modified response only if both header values match the corresponding values in the object's response headers.

Examples Case 1: The ETag matches the If-None-Match value.

If the request includes an If-None-Match header such as:

If-None-Match: "a", "b", "c"

For this feature to perform correctly, the origin server’s ETag header should be properly formed. This includes wrapping the value of the ETag header in quotation marks:ETag: “744b1614390ff16722d6d9c8df269a86”If the origin server returns an ETag header without the quotation marks, it is possible to optionally configure the Akamai server to accept the ETag without quotations.


Entity Tag Validation SupportConfidential & Proprietary

and the origin response contained:

ETag: "b"

The Akamai server will respond to the client with 304 Not-Modified.

Case 2: The ETag does not match the If-None-Match value.

If the client request includes an If-None-Match header such as:

If-None-Match: "c", "d", "e"

and the origin response contained:

ETag: "b"

The Akamai server will respond to the client with a 200 OK and the cached response object.

Strong ValidatorsRequired

The Akamai server supports only the use of "strong" validators.

A validator is strong if it changes every time the object changes. For example, an integer incremented for each version of the object would be a strong validator. By contrast, the time in seconds of the object generation is a weak validator, because it is possible for two versions of the object to have been generated within the second granularity. For a good discussion of strong versus weak ETags, see

http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.3.3

When the Akamai server compares the value of the If-None-Match header and the ETag header, it treats them as opaque strings.

Multiple ETagBehaviors

In theory, an origin server should only return one ETag with an object. However, the HTTP 1.1 spec does not explicitly forbid sending more than one ETag with an object.

If the Akamai server receives multiple ETags from an origin server, it will honor the first and disregard the rest. This means only the first ETag will be sent to the client and stored with the cached object. If a client then sends an "If-None-Match" with the value of the origin's second ETag, the Akamai server will find no match and will send the client the object from cache.

Wildcards When the If-None-Match header contains an asterisk (*) as a value, the asterisk is interpreted as “match any ETag”.

Size Limit The limit on the size of an individual ETag is 128 bytes. Since the ETag header can contain multiple ETags, the total header size can be much larger than 128 bytes. Any individual ETag value that is larger than 128 bytes is ignored by the Akamai server.



Cache POST Responses

By default the Akamai server passes POST requests directly to the origin server and does not cache the response to the POST. You can optionally instruct the Akamai server to cache responses to POST requests, and the body of the POST request can then be used to determine the cache key of the POST response. This might be desirable if the POST requests are nominated for Dynamic Content Assembly on the Akamai server (as described in the preceding section). In this case the POST body is passed to the DCA processor and combined with the POST response from cache. The results of processing are then served to the client.

You can choose one of three methods for forming the cache key of the POST response:

Ignore the POST body - This option causes the response to be cached under the POST URL and all POST requests generated with that URL will be served from the same cached response.

MD5 Hash the POST body - POST responses are cached based on the contents of the POST request body that has been converted to an MD5 hash and appended to the request URL as a query argument.

Convert the POST Request Body to a Query String - For purposes of forming the cache key, the POST request body is appended to the request URL as a query string. For this option to work, the POST request must be of Content Type “application/x-www-form-urlencoded.” Otherwise the Akamai server will ignore the POST body and the response is not cached. When this option is used, it should be combined with the Flexible Cache ID feature to define the arguments in the query string that are relevant to the cache key.

Caveat There is a strict limit on the size of the POST request with which this feature can be used. The current limit on the request size is 16K.

Integration To implement caching of POST responses, select the method by which you want the cache key to be formed and, if you chose Convert POST Request Body to Query String, identify the query arguments that are relevant to the cache key.

The Integration Consultant should submit a provisioning request that contains all of the basic required information and identifies:

• The POST requests for which the response should be cached

• The method to use to form the cache ID for the POST response.

Sending the POSTbody to ESI

To send the POST request body to ESI for processing, there is an additional metadata setting. You’ll find this described in the chapter Edgecomputing under the title Process POST Body Through DCA.


Limiting Refresh Requests to the OriginConfidential & Proprietary

Limiting Refresh Requests to the Origin

By default the Akamai server can make more than one request to the origin server for a single object during the same time period. This can happen if multiple clients request the same object very close together and the object needs to be retrieved or refreshed before it is served.

The Akamai server may forward the first request to the origin to obtain the object, or a refresh response, but not receive the HTTP headers before the second request arrives. In this case the response to the first request is not available to the second client and a new request is forwarded to the origin server. You can imagine that if the origin server is slow for any reason, a very popular object could trigger many requests to the origin server.

You can reduce the number of forward requests to the origin in a few ways:

• Use Tiered Distribution to reduce the number of servers that directly communicate with the origin server.

• Enforce that a new “refresh” request cannot go forward to the origin server if there is an outstanding (unanswered) prefresh or refresh request to the origin server.

• Cause the Akamai server to make the expected origin response available for serving to new client requests even before the HTTP headers are returned and the response code is known.



Error Response Time To Live (Negative TTL)

By default the Akamai server caches a negative response from the origin server for ten seconds before attempting again to retrieve the requested object for a client. For example, if the origin server returns a 404 Not Found response for an object, the Akamai server would cache that response and serve it to clients for ten seconds before it would again forward a client request to the origin to retrieve the desired object.

You can change this default and set a different time-to-live for negative responses.


Preserve Stale Object on Error Response CodesConfidential & Proprietary

Preserve Stale Object on Error Response Codes

The Akamai server’s default behavior is to preserve stale objects in cache on a negative reply (400 or 5xx error codes) from the origin server. It is possible to disable the default behavior so that a negative reply from the origin server will cause the underlying stale object in cache to be evicted and the error to be cached in its place.



Cache 302 Responses by Default

Akamai edge servers will cache a 302 response only if it contains a Cache-Control or Expires header. When a 302 is cached, the same TTL is applied that would have applied to a 200 response.

You can instruct the Akamai edge server to cache 302 responses by default, without regard to the presence of Cache-Control or Expires headers. This is useful if the origin doesn’t include these headers in a 302 response.


Quick If-Modified-Since ResponseConfidential & Proprietary

Quick If-Modified-Since Response

This feature causes the Akamai edge server to serve a 304 response to a client If-Modified-Since request without reading the response object, assuming that the object is fresh and it doesn’t contain any Edge-Control headers that might make it stale. This can potentially avoid unnecessary disk reads and improve the speed of response to these client IMS requests.

TechnicalDetails

The Akamai server can make a decision about the remaining lifetime of an object in cache based on the request ARL, associated metadata, and the corresponding cache entry. A bit in the cache entry indicates whether the response contains anything (like an Edge-Control header) that would affect the object's TTL. If the bit is on, the server reads the object before serving a response to the client IMS request. If the bit is off, the server returns a 304 response.



Serve Only If Cached

You can instruct the Akamai server to serve requests from cache without going forward to the origin server. When you set this option, the Akamai server will act as if the Cache-Control: only-if-cached header was present in the client request, except that it will ignore the time-to-live and serve the object even if it is stale.

This is primarily useful as part of a fail-over mechanism.

This feature does not override the bypass-cache, no-store, and cent-auth tags. When those are set, the Akamai server will still forward the request.



In This Chapter

Default Behaviors • 90

Controls for Downstream C

Configuration Options - Sta

Configuration Options - Dyn

Busting Downstream Cache

Overriding Cache-busting B

4
Downstream Caching
acheability • 91

tic Content • 94

amic Content • 96

s • 97

ehaviors • 99

This chapter discusses management of client caching—at downstream proxies or at the end user’s browser.

In general, Akamai uses a default behavior of setting cacheability at the browser to no longer than the remaining lifetime for the content in Akamai server cache. If the cacheability headers sent by the origin server suggest a shorter time, the shorter time is used. There are also some important exceptions to the default behavior.

You can control the downstream cacheability of your content through response headers or through your edge server configuration file.

89

Chapter 4: Downstream Caching

Default Behaviors

When serving content to clients, Akamai servers by default send the lesser of the Cache-Control: max-age (and/or Expires value) received from the origin server and the remaining lifetime of the object in Akamai server cache. This means that the downstream max-age is equal to or less than Akamai max-age.

When no-store or bypass-cache features are used to indicate that the Akamai server should not cache the object, the headers sent to clients will set Cache-Control: no-store, and any max-age received from the origin server is ignored.

The Akamai server only updates the values in the Cache-Control and Expires headers (this includes adding max-age="remaining lifetime" to the Cache-Control header); the server does not add these headers if the origin server did not send them.

There are exceptions to these default behavior:

• When the Honor Cache-Control or Honor Expires features are used, Akamai servers respect those headers from the origin server for purposes of their own cache and pass similar headers to the client (downstream). In this case, the response to the client is directly dependent on the response from the origin and there is no difference in cacheability for Akamai and the end client (except that Akamai will not send an Expires header in the past). The downstream max-age is always the same as the remaining lifetime in Akamai cache. (There is an exception to this exception: cacheability headers from the origin server under Honor Cache-Control and Honor Expires cannot override a setting of no-store in the configuration file, thus, the client will receive cache-busting headers rather than the header values from the origin server.)

• When authorization, such as Centralized Authorization, is used, Akamai servers send cache-busting headers downstream to prevent proxies from caching the responses and serving them to unauthorized clients. While it is not recommended, you may configure the Akamai server not to cache-bust for authorized content.

• When Dynamic Content Assembly is used (Edge Side Includes) the downstream cacheability is calculated to be the lowest value of all the fragments included in the creation of the output page served to the client.

•


Controls for Downstream CacheabilityConfidential & Proprietary

Controls for Downstream Cacheability

Beyond the default behavior and the exceptions listed in the preceding section, you can directly control the downstream cacheability of content with the Downstream Time-To-Live and ESI Downstream Time-To-Live features.

DownstreamTime-To-Live

Downstream Time-To-Live lets you choose among several options for cacheability headers sent to the client.

Origin vs. AkamaiControl

The the most global choice provided by Downstream-TTL is whether to use the headers sent by the origin, or have the headers and their values controlled by the Akamai server.

Use Origin Headers

If you choose to use cacheability headers sent by the origin, they are delivered to the client without any alteration. This setting is most appropriate for responses that are not cacheable. You can apply the setting only to uncacheable content, while allowing the Akamai server to control the headers for cacheable content. When used with uncacheable content, this choice lets the origin server directly control whether a response warrants cache-busting headers or only the “private” directive to prevent private information from being held by a shared cache or browser cache.

You might also use this setting for cacheable content if the origin server sends a Cache-Control headers but no Expires. When this setting is used with cacheable content, it’s possible for the expiration time in the header to move into the past before the object expires in Akamai cache.

Use Akamai Controls

If you choose to control the downstream headers through the Akamai server, the Downstream TTL feature allows you to control:

• Which headers are sent (Cache-Control, Expires, both, or neither).

• How the Cache-Control: max-age value is determined.

• Whether to include the “private” directive.

• Whether or not these settings should override cache-busting behaviors.

These options are discussed in detail in the following sections.

CacheabilityHeaders Sent

When used in the configuration file with Akamai control over the cacheability headers, Downstream Time-to-Live lets you specify which headers are used and how the values in those headers should be calculated. By default, the response to the client contains the same combination of Cache-Control and Expires headers that were received from the origin. You can also choose to send only the Cache-Control header,



only the Expires header, both headers, or neither header.

Usually this setting is left at the default so that the header combination can be controlled at the origin server.

Calculating theDownstream

Max-age

Downstream Time-to-Live lets you choose the method for determining the value of the Cache-Control: max-age setting. When this feature is used, the default is to send a specific value declared in the configuration. For example, you might send all responses with a max-age of five minutes. (You could also set a different value for each type of content. For example, it would be normal to send a very long max-age for images, but a short max-age for HTML.) Alternatively, you can set the value of the Cache-Control header using one of the following methods:

• the value of the Cache-Control header in the origin response

• the Time-to-Live (max-age) that was applied to this object in Akamai cache, without adjustment for time already spent in cache

• the greater of the remaining lifetime in the Akamai server’s cache and what the origin sent

• the lesser of the remaining lifetime in the Akamai server’s cache and what the origin sent. (This is the value sent when the feature is “off ”.)

• the remaining lifetime in the Akamai server’s cache, without regard to what the origin server sent.

Sending“Private”

In any case where you want the served content to be used only by a single user you may wish to add the “private” directive to the Cache-Control header. The HTTP specification provides for using “private” as way to tell shared caches that they should not be caching this response even if it contains a max-age directive.

Overridingcache-busting

As mentioned in the description of default behaviors, the Akamai server will send cache-busting headers with any response that is handled with no-store or bypass-cache settings for the Akamai server. Normally, to ensure that this content is not accidentally cached in a downstream shared cache, the Downstream-TTL features do not override cache-busting. In the event that you want to override the cache-busting behaviors and send a specific set of headers for all uncacheable content, you can choose this option. Obviously great care should be taken when sending user-specific responses with headers that make the response cacheable.

ESIDownstreamTime-To-Live

ESI Downstream Time-To-Live lets you explicitly set the value of the Cache-Control header sent to the clients when an object is processed using Dynamic Content Assembly. Unlike the general feature described above, ESI Downstream Time-to-Live provides only for setting a specific value in the response. There are no controls for selecting the headers to send or the method by which the value of those headers should be calculated.


Controls for Downstream CacheabilityConfidential & Proprietary

InternetExplorer

Behaviors

Controlling downstream cacheability in a consistent manner is complicated by the interactions of browsers. Two specific behaviors of Microsoft Internet Explorer require care in configuring the response:

• Internet Explorer will not respect the settings in Cache-Control and Expires headers if the HTTP version in the response is set to HTTP/1.0. Akamai can work around this by explicitly setting the response to indicate HTTP/1.1 regardless of what is sent by the origin server. Or, alternatively, the Akamai server can be set to pass-through the protocol version sent by the origin.

• If cache-busting headers are used, Internet Explorer may not successfully pass objects to plug-ins for handling. This is because IE strictly interprets the cache-busting headers to mean that it cannot save the files in its temporary cache even to hand them off to the plug-in application. Akamai addresses this with a specific setting that deletes these headers if the client browser is Internet Explorer.



Configuration Options - Static Content

You can control the downstream cacheability of objects through either an Edge-Control response header or through configuration file settings..

By HTTPResponse

Headers

To maintain complete control over downstream cacheability at the origin server, you can specify downstream cacheability using the Edge-Control header downstream-ttl. For example, the header might be:

Edge-Control: downstream-ttl=30

The integer may be followed by a unit specifier: Current unit specifiers are: 's' (seconds), 'm' (minutes), 'h' (hours), 'd' (days). The default is ‘s’. For example:

Edge-Control: downstream-ttl=30m

This response header takes precedence over a Downstream TTL setting in your Akamai edge server configuration file.

The value given to downstream-ttl determines which Cache-Control settings will be passed downstream:

• A positive integer representing a Cache-Control max-age time period.

• A value of zero sets the Cache Control header to “no-cache.”

• A value of -1 sets the Cache Control Header to “no-store”, and causes the Akamai server to send a cache-busting header set downstream.

The cache-busting headers sent are:

Expires: [current time]Cache-Control: max-age=0, no-storePragma: no-cache

Although the Edge-Control header doesn’t give control over which headers are sent to the client (Cache-Control, Expires, both, or neither), since this Edge-Control header is being added at the origin server, it is assumed that you can also set the combination of cacheability headers you desire. The Akamai server will update the headers with the value from the Edge-Control: downstream-ttl header before forwarding the response to the client.

ByConfiguration

File

You can control the downstream cacheability headers through settings in the configuration file. There is also great flexibility to choose the headers sent and for which type of content those headers should apply. As indicated above, there are separate controls when setting the downstream headers for any response or only for

Beginning with server version 5.4, it is possible to directly override the cache-busting behaviors of no-store and bypass-cache content using the Downstream Cacheability feature.


Configuration Options - Static ContentConfidential & Proprietary

responses that have received ESI processing.



Configuration Options - Dynamic Content

You can also control the downstream cacheability of the results of ESI processing through configuration file settings. This configuration option allow for setting a fixed max-age or for busting downstream caches.


Busting Downstream CachesConfidential & Proprietary

Busting Downstream Caches

Often it’s desirable to prevent downstream proxies and browsers from caching a response because the response is of a private nature. Or, this cache-busting behavior may be desirable because the response object is being used to track the number of times a page is accessed without serving the entire page.

Cache-busting headers will be send downstream to clients in any of the following cases (if no attempt is made to override the cache-busting behavior):

• The origin response contains cache-busting headers and no explicit Downstream TTL was configured to override these headers.

• The response is not cacheable by the Akamai server (no-store or bypass-cache was used for the response), and no Downstream TTL was configured to override the cache-busting behavior used by the Akamai server for this content.

• The object is explicitly configured to receive cache busting headers when served to the client

Non-cacheablecontent

cache-busting

If a response is designated as no-store or bypass-cache in the configuration, the downstream headers sent by the Akamai server will be set to bust downstream caches by sending the following header set:

Expires: [current time]Cache-Control: max-age=0Cache-Control: no-storePragma: no-cache

You can override these headers by setting an explicit Downstream TTL and specifying that this setting applies to uncacheable content, or, you can choose to pass the origin’s cacheability headers rather than send the headers applied by the Akamai server.

ExplicitCache-Busting

Aside from the automatic cache-busting behaviors for no-store and bypass-cache content, you can explicitly send cache-busting headers even for content that is cacheable in the Akamai server.

Just as you are able to set an explicit max-age to be served to the client, you can specify that the client should receive cache-busting headers instead of a max-age setting.

You can send either Cache-Control: no-store or Cache-Control: no-cache. In both cases, the Expires header will be set to the current time.



Busting AllCaches UsingHTTP Expires

andCache-Control

The cache-busting for both Akamai and downstream caches described above for no-store or bypass-cache also applies if:

• The Honor Cache Control feature is used, and the Akamai server receives HTTP Cache-Control: no-cache or Cache-Control: no-store headers in a response from the origin server.

• The Honor-Expires feature is used to control cacheability and the Akamai server receives an Expires header in the past but no Cache-Control: max-age header.

Busting OnlyDownstreamCaches Using

Expires andCache-Control

With HTTP Expires and Cache-Control, it is possible to have Akamai cache an object, but bust the caches downstream, and control all cacheability settings from the origin server. To do this, you would use both an Edge-Control: cache-maxage header and Cache-Control: no-store and/or Expires headers. For example:

Edge-Control: cache-maxage=1hCache-Control: no-storeExpires: “now”

This would cause the Akamai server to cache the object for one hour, but pass the Cache-Control: max-age and Expires: “now” headers to the client on every request. You can accomplish similar behavior by using the Set Downstream Cacheability feature, but in that case the downstream cacheability setting is relatively static, as it can only be changed in the configuration file.


Overriding Cache-busting BehaviorsConfidential & Proprietary

Overriding Cache-busting Behaviors

As explained in the previous sections, the Akamai server will actively send cache-busting headers to prevent downstream proxies and browsers from storing the response in two cases:

• if the content used no-store/bypass-cache settings

• if the content used Authorization features.

Authorization indicates that the client’s access to the content must be controlled, and allowing a proxy to cache and server the response may thwart control over user access. Akamai takes the conservative approach of busting the proxy cache rather than trust that the proxy will behave correctly in revalidating the content before serving.

You can override these cache-busting behaviors through specific settings in the configuration file. You can explicitly disable the cache-busting behavior of Authorization, and you can override the cache-busting headers sent with uncacheable content.





In This Chapter

The Default Cache Key • 1

Ignore Query String • 104

Ignore Query Arguments •

Ignore Path Components •

Ignore Path Parameters • 1

Ignore Case in Cache Key •

Flexible Cache ID • 113

5
Cache Key Modification
02

105

108

10

112

By default, the Akamai server caches content based on the entire URI path and query string (if any). You can modify this default behavior by specifying that all or a portion of the query string should not be included in the cache key. Likewise, a portion of the URI path can be excluded from the cache key.

These features are especially useful for requests that include a query string not related to the uniqueness of the content. For example, a unique session ID might be included in the query string to track user interaction with the site, but not be used to differentiate data served to the user. In this case, if the session-ID were not removed from the query string, it would render the content uncacheable. The Ignore Query String Argument feature could make this same content cacheable for all users.

The Flexible Cache-ID feature lets you selectively include information from the request headers (such as the User-Agent header), a cookie, or a query argument in the cache-ID portion of the cache key. You can use this to cache and serve different objects based on User-Agent or any other header, cookie, or query argument value.

Caveat

Of the features described in this chapter, only the Flexible Cache-ID Feature should be used to modify the cache key based on characteristics not contained in the request ARL. For example, only the Flexible Cache-ID feature should be used in such a way as to produce a different cache key based on the presence or absence of a cookie in the request.

101

Chapter 5: Cache Key Modification

The Default Cache Key

By default, the Akamai server forms the cache key (the index entry to the object in cache) from information in the request ARL. Objects that are requested using a CNAMEd URL have their ARL information (typecode, serial number and TTL) determined from configuration files and response headers.

The information used to form the cache key includes:

• Typecode

• Object ID (for non-TTL typecodes)

• Complete forward request path (origin server, pathname, filename and extension)

• Query string in its original order. (If ignore query or prune query is turned on, the query string is removed from the cache key. If the features to selectively include or ignore query arguments are used, the query arguments used in the cache key will also be ordered consistently.)

• SSL vs. non-SSL request

• HTTP Method (GET, HEAD, etc.)

If any of the above information in the ARL changes, the index to the cache changes. The request is then treated as a new request, and the edge server fetches the object from the origin server.

When an object is requested through a CNAMEd URL, it receives a corresponding, but different, Typecode from what would appear in a FreeFlow ARL. Thus it is possible to determine from the Typecode in the cache key whether the object was fetched based on a FreeFlow ARL or a URL. This also means that an object with the same URI may be cached twice if it is requested by a FreeFlow ARL and also by an CNAMEd URL.

Conversely, time-to-live (TTL) is not used as an index into the cache; so changing that field in the ARL or in the configuration file will not result in a new object being fetched. The same is true for the Serial number and CP-Code. These are not part of the cache key. The following two request ARLs return the same object from cache:

/L/1837/7663/4h/origin.example.com/Index/Home

/L/17/63/1h/origin.example.com/Index/Home

Determiningthe Cache Key

You can use the request header Pragma:akamai-x-get-true-cache-key to determine which portions of the URI are part of the cache key and which Typecode is assigned to the request. For example, the response for the ARLs above would be:

X-True-Cache-Key: /L/origin.example.com/Index/Home

This is not the full cache key, as it does not contain the request scheme (HTTP or HTTPS) or the method (GET, POST, HEAD).

An older Pragma request header (Pragma: akamai-x-get-cache-key) indicates


The Default Cache KeyConfidential & Proprietary

the request scheme by prepending a slash and the letter S to the beginning of requests using HTTPS, like this:

X-Cache-Key: /S/L/1837/7663/4h/origin.example.com/Index/Home

However, use of the use the Pragma: akamai-x-get-cache-key request header is deprecated, because it does not accurately reflect whether a query string has been ignored in the cache key, and the response header shows the Serial, CP-Code and TTL, which are not part of the cache key.

The features described in the remainder of this chapter are used to modify the cache key. These modifications are sometimes performed so that several different requests can be served from a single object. Flexible Cache-ID can also be used to add information to the cache key, so that different content can be served based on request headers or cookies in the client request.



Ignore Query String

Web sites sometimes append a question mark (“?”) to a URL followed by some data, such as user inputs, information about the page from which the request was generated, or other tracking or control information.

By default, Akamai servers cache an object with the complete URL, including the query string, as part of the index. If a single object is requested multiple times with different values after the “?” it will be cached as multiple objects. For example, a Web site may be including a session ID as a query string. The session ID will be unique for every end user, but the content may be cacheable if the ID is removed.

Ignore Query String solves this problem by instructing Akamai servers to ignore anything after the “?” when forming the index into cache (the cache key). Thus, the object is retrieved and cached only once.

The information removed from the URL is still recorded in Akamai logs, and, if the Akamai server makes a forward request to the origin server, the requesting URI includes the query string.

Integration Ignore Query String can be set in an ARL or in the configuration file.

By ARL Web sites that use ARLs can invoke this feature using Typecode n. (Typecodes m, k, v, t, and l, also incorporate the ignore query string function along with other typecode features.)

If the ARLs have already been published without the use of a typecode that invokes the “ignore query” option, you can add this feature through metadata in the configuration file.

For a listing of typecodes and their meanings, see the FreeFlow Typecode Summary available on the Akamai customer portal at https://control.akamai.com/


You can directly control the Ignore Query String setting for your content through Configuration Manager, where this feature is part of a set called “Cache Key: Query String Rules.” The Configuration Manager feature also includes some of the options described in the next section of this guide (Ignore Query Arguments).


Ignore Query ArgumentsConfidential & Proprietary

Ignore Query Arguments

The Ignore Query String feature discussed in the preceding section removes the entire query string from the cache key. Similarly, Ignore Query Arguments removes specific query string arguments from the cache key. (When the Akamai server makes a forward request to the origin server, the entire query string is still included in the request.) This is useful if only some arguments in the query string are relevant to the content served.

For example: a Web site might have URL’s that look like the following:

www.example.com/getfile.asp?fileID=1234&randomKey=a1b2&sessionID=32Getfile.asp

This causes the browser to download a file, represented by the "fileID" 1234. Changing the file ID would cause a different file to download. Thus the "fileID" is relevant to the content. Conversely, the "randomKey" and "sessionID" are specific to a particular request and end user. They are used to authenticate the user and to track unique downloads. In this case, randomKey and sessionID must be ignored from cache key, but fileID must be retained. This is exactly the kind of situation that Ignore Query Arguments was designed to handle.

Using this feature, you can indicate which query arguments are part of the cache key by listing either:

• The arguments to ignore, or

• The arguments to include (in which case all others are ignored)

Note that you cannot use the "ignore" and "include" functions together. The "include" setting takes precedence over the "ignore" setting.

You can indicate which arguments to ignore or include by:

• name

• position

When the "by-position" functions are used, you can specify the position by counting either forward or backward through the query string

Ordering ofQuery Arguments

By default, the Akamai server includes the query string in the cache key and makes no modifications to it. So, two otherwise identical URL’s with exactly the same query arguments, but in different order, will result in two copies of the object in cache.

Any time the Ignore Query Arguments feature is used to modify the cache key, the Akamai server will order (alphabetize) the query arguments and their values. The result is a single cache key regardless of the order of the arguments in the original request. For example, if you included the arguments "make", "model" and "year" in the cache key, and the client request was for: /some.cgi?year=2004&make=jones&model=prime, the resulting cache key would be /some.cgi?make=jones&model=prime&year=2004



If your Web site arbitrarily orders the query arguments as a client navigates the site, by ignoring a query argument that will never appear in your URL’s (say, "akamai888’) you can force the remaining query arguments to be reordered for maximum cache efficiency on the Akamai server and maximum traffic off-load for the origin server.

Caveats This feature applies only to URL’s or Akamai ARL’s that do not use a Typecode in their structure.

TechnicalDetails

Ignore Query Arguments lets you remove from the cache key any query arguments that might otherwise have unnecessarily caused the content to be uncacheable. To use this feature, the query string must be well formed. That is, the query string arguments must be separated from each other by an ampersand (&).

For flexibility, you can use removal by position and by name on the same object. In that case the positions refer to the original arguments.

SelectingArguments by

Name

To ignore or include query string arguments by name, the Akamai server performs a prefix (substring) match between the items listed for removal and the different query string arguments. When a match is found, the complete query argument is removed or included. The match is case-sensitive. That is, ‘arg’ would not match “Arg”.

You can match query arguments exactly by ending the matching strings with '&'. (Because '&' is a reserved character in xml you would need to use &amp in the metadata file.)

For example, given the URL:

http://www.example.com/affiliates/[email protected]&pageid=001&date=02242001&affiliateid=2345.

If you want to use only the pageid key=value pair (pageid=001) in the cache key, you can do so by requesting any one of the following settings in the configuration file:

• Ignore query string arguments "email" "date" and "affiliate"

• Ignore query string arguments "email=ah" "date=" and "affi"

• Include only query string argument "pageid"

The substring prefix can be as general or specific as you like, up to an exact match that ends in the ampersand (&).

SelectingArguments by

Position

To ignore or include query string arguments by position, the Akamai server counts forward from the beginning of the query string with the first argument identified by position one (1). Alternately, if you want the count to run backwards from the end of the query string, the positions are declared with negative numbers, such that the last position is specified by negative one (-1).

You can specify the argument positions as a space separated list of numbers and ranges, where the ranges are indicated with a colon. The range -2:-5 indicates


Ignore Query ArgumentsConfidential & Proprietary

positions two through five counted backwards from the end. Open-ended ranges are not allowed.

For example, given the URL:

http://www.example.com/affiliates/[email protected]&pageid=001&date=02242001&affiliateid=2345.

If you want to use only the pageid key=value pair (pageid=001) in the cache key, you can do so by requesting any one of the following settings in the configuration file:

• ignore query string arguments 1 and 3-4 (or 1 and 3-99 to remove everything after the 2nd argument)

• ignore query string arguments –1:-2, and –4 (counting backwards from the end)

• include only query string argument 2

• include only query string argument -3

Integration The Integration Consultant should submit a provisioning request. In addition to the basic required information, the request should explicitly state the following:

• The query string arguments to ignore or include

• A sample URL showing the query string arguments in use

• A sample URL as it would appear if the desired query string arguments were ignored



Ignore Path Components

Ignore Path Components removes specific URL path components from the cache key. This lets the Akamai server retrieve an object defined by different URL's and cache the object as a single cache entry. This is particularly useful if the Web site passes information about the user interaction or session with a site in the URL path rather than the query string. (When the Akamai server makes a request to the origin server, the entire URL path is included in the request.)

You can indicate which path components are part of the cache key by listing either:

• The components to ignore, or

• The components to include (in which case all others are ignored)

Note that you cannot use the "ignore" and "include" functions together. The 'include' setting takes precedence over the 'ignore' setting.

You can indicate which components to ignore or include by:

• Name

• Position

When the "by-position" functions are used, you can specify the position by counting either forward or backward through the URL path. The filename is considered a portion of the URL path and is usually, but not necessarily, the last component. The Akamai server counts backward from the end of the URL path or the beginning of the query string (?).

Caveats This feature applies only to CNAMEd ARL’s; that is, URL's or ARL’s that do not use a Typecode in their structure.

TechnicalDetails

Ignore Path Components lets you remove from the cache key any path components that might otherwise have unnecessarily caused the content to be uncacheable. Components of the path must be separated by a forward slash '/'

For flexibility, you can use removal by position and by name on the same object. In that case the positions refer to the original components (before the Akamai server removed any components).

RemovingComponents by

Name

To ignore or include path components by name, the Akamai server performs a prefix (sub-string) match between the items listed for removal and the different path components. When a match is found, the complete path component is removed or included. The match itself is case-sensitive.

You can match path components exactly by ending the matching strings with '/'.

For example, imagine a Web site uses path components such as:

http://www.example.com/affiliates/[email protected]/pageid=001/


Ignore Path ComponentsConfidential & Proprietary

date=02242001/affiliateid=2345/adenegine.asp

If you want to use only the "affiliates" directory, the pageid key=value pair (pageid=001), and the filename in the cache key, you can do so by requesting any one of the following settings:

ignore path components "email" "date" and "affiliateid"ignore path components "email=ah" "date=" and "affiliatedid"include only path components "affiliates" "pageid" and position –1

Notice that the last request includes components both by "name" and "position" to cover the filename case regardless of the filename or the number of components in the URL path.

The substring prefix can be as general or specific as you like, up to an exact match that ends in the forward slash (/).

RemovingComponents by

Position

To ignore or include path components by position, the Akamai server counts forward from the beginning of the URI path with the first component identified by position one (1). Alternately, if you want the count to run backwards from the end of the URL, the positions are declared with negative numbers, such that the last position is specified by negative one (-1). The last position is the one following the final forward slash (/) to the end of the URL or the beginning of the query string (?).

You can specify the component positions as a space separated list of numbers and ranges, where the ranges are indicated with a semicolon. The range -5:-2 indicates positions two through five counted backwards from the end. Open-ended ranges are not allowed.

For example, imagine a Web site uses path component encoding such as:

http://www.example.com/affiliates/[email protected]/pageid=001/date=02242001/affiliateid=2345/adenegine.asp

If you want to use only the "affiliates" directory, the pageid key=value pair (pageid=001), and the filename in the cache key, you can do so by requesting any one of the following settings in the configuration file:

ignore path components 2 and 4:5ignore path components –3:-2 and -5include only path components 1 3 and 6include only path components –1 –4 and -6


• The path components to ignore or include

• A sample URL showing the path components in use

• A sample URL as it would appear if the desired path components were ignored.



Ignore Path Parameters

Ignore Path Parameters removes specific URL path parameters from the cache key. This lets the Akamai server retrieve an object defined by different URL's and cache the object as a single cache entry. This is particularly useful if the Web site passes information about the user interaction or session with a site in the URL path rather than the query string. (When the Akamai server makes a request to the origin server, the entire URL path is included in the request.)

You can indicate which path parameters are part of the cache key by listing either:

• The parameters to ignore, or

• The parameters to include (in which case all others are ignored)

Note that you cannot use the "ignore" and "include" functions together. The 'include' setting takes precedence over the 'ignore' setting.

You can indicate which path parameters to ignore or include only by name.

Caveats This feature applies only to CNAMEd ARL’s; that is, URL's or ARL’s that do not use a Typecode in their structure.

TechnicalDetails

Ignore Path Parameters lets you remove from the cache key any path parameters that might otherwise have unnecessarily caused the content to be uncacheable. The Parameters must be identified by a prefix (name) on which the Akamai server can match to remove the parameter.

To ignore or include path parameters, the Akamai server performs a prefix (sub-string) match between the items listed for removal and the different path parameters. When a match is found, the complete path parameter is removed or included. The match itself is case-sensitive.

For example, imagine a Web site uses path parameters such as:

http://www.example.com/affiliates;[email protected]; pageid=001;date=02242001;affiliateid=2345/adenegine.asp

If you want to exclude the “email,” “date,” and “affiliateid” parameters from the cache key, you can do so by requesting one of the following settings:

ignore path parameters "email" "date" “affiliateid”include only path parameter "pageid"


• The path parameters to ignore or include

• A sample URL showing the path parameters in use

• A sample URL as it would appear if the desired path parameters were ignored


Ignore Path ParametersConfidential & Proprietary



Ignore Case in Cache Key

You can instruct the Akamai server to create the cache key without regard to case in the URL. Essentially, this means the URL (and query string) is converted to all lower case when the cache key is created. As a result, URLs that fetch the same object using different case will now cache the object only once rather than once for each uniquely-cased URL. For example, when Ignore Case in Cache Key is enabled, these two client request URLs would represent the same object on the Akamai server:

www.example.com/dir1/dir2/myfile.htmlwww.example.com/Dir1/Dir2/MyFile.html

However, the URL used for the forward request (to the origin server or Tiered Distribution parent) is the original ARL with case. The original URL with case is also the one that is logged, unless you specifically request to have your request URLs logged in lower case. (If you need to log the URL in lowercase, you can use the tag reporting:lds.lowercase-url.)

This feature is primarily useful for customers who use the Microsoft IIS server, which ignores case in request URLs and thus can lead to very lax enforcement of naming standards in URLs. It is often easier to simply configure the Akamai server to also ignore case than to carefully edit existing Web sites to enforce proper naming in existing URLs.

Integration You can directly control the Ignore Case setting for your content through Configuration Manager, where the feature is called “Cache Key: Ignore Case.”

Important: To use the Ignore Case in Cache Key feature in combination with NetStorage (or any other Unix-based server) as the origin server, you’ll likely need to configure that server to also ignore the case of the URLs. For NetStorage, this is accomplished with the Force Case option, which can convert the request to either upper or lower case. Note, however, that this requires that you consistently name the files on the NetStorage in either upper or lower case.


Flexible Cache IDConfidential & Proprietary

Flexible Cache ID

Flexible Cache ID makes it possible to add information to the default cache key to potentially include information from cookies and HTTP headers. It also provides a mechanism for including or excluding arguments from the query string.

Caveats Because this feature results in a change in the composition of the cache key, enabling or disabling the feature will result in cache misses until objects are refetched and cached under the new cache key, even if the requests themselves do not change.

TechnicalDetails

As described at the beginning of this chapter, the Akamai server forms its cache key (the index to the object in cache) based almost exclusively on information in the request ARL or URL. The other features described in this chapter can manipulate the information in the request ARL for use in the cache key. For example, they can cause the query string to be ignored for purposes of the cache. But they cannot add information to the cache key from other sources.

Sometimes it is desirable to serve different content to end users based on information other than what is in the ARL. For example, a Web site may serve localized content to users based on the Accept-Language header sent by the browser. There might be optimized pages to be served to different browsers based on the User-Agent header sent by the browser. There may be separate versions of any content based on the value of a cookie present in the client request.

Flexible Cache ID lets you add information from HTTP Headers and Cookies to the cache key in the form of a cache ID. It also lets you select information in the query string for inclusion in the cache ID. You do this by defining a set of rules for what information should be included or excluded from the cache key. These rules are then compared with the request to determine how the object should be cached. If none of the rules match, the object is uncacheable and is discarded after the requesting client is served.

The syntax for defining which parameters of the request are used for the cache ID lets you do the following:

• Identify by name any headers, cookies or query arguments to include in or exclude from the cache ID. (These are exact matches, not prefix matches.)

For example, your rule could say that the requested object should be cached, and the cookie name and value included in the cache ID, if there is a cookie named “PRODUCT” included in the request.

• Identify the values of the headers, cookies, or query arguments that can be included in the cache ID.

For example, your rule could say that the requested object should be cached with the cookie name and value in the cache ID, if there is a cookie named ‘PRODUCT’ included in the request and the value of the cookie is ‘7’, ‘8’, or ‘12’. If the cookie is present, but its value is ‘15’, the rule would not match.



• Identify values of the headers, cookies, or query arguments that must not be included in the cache ID. (If one of these values is present in the request, the rule does not match the request and its not used to form the cache ID.)

This function is useful if it is easier to identify unacceptable values than to list all acceptable values for a cookie, header or query arguments.

• Identify whether parameters to include in the cache ID are optional or required. (If a required parameter is not present, the rule doesn’t match the request and is not used to form the cache ID.)

• Choose to include only the name of the header, cookie or query argument in the cache ID when a rule matches.

• Choose to include all arguments of a query string in the cache ID by default

• Choose to exclude specific query arguments from the cache ID by name.

For example, your rule could say to cache the object with the query string in the cache ID except for the query argument ‘sessionid’.

SpecialUser-Agent

Headers

Because the values of the standard HTTP User-Agent header can vary so much (there are over 3000 possible header values), it isn’t safe to allow for caching based on the value of the standard User-Agent header. Instead there are four “virtual” request headers that can be used in place of the User-Agent header for computation of the cache ID. These headers and their possible values are:

X-Akamai-UA-Type: "NS" or "IE" X-Akamai-UA-Version: "1", "2", "3", "4", "5", "6", "7" X-Akamai-UA-OS: "win95", "win98", "winNT", "unix", or "macos" X-Akamai-UA, (a hyphen separated list of the three virtual types defined

above. For example “IE-6-winNT”.)

There are 70 different possible values for X-Akamai-UA, but only a few will occur in the real world. The use of the X-Akamai-UA header in a cache ID rule should cover 99% of user-agents.

New Cache KeyComposition

Whenever the Cache-ID feature is used, the cache-key is composed of two parts:

• The existing cache-key minus the query string, which is included in the cache ID as appropriate

• The cache-ID computed from the additional information (query arguments, cookie values, HTTP header contents).

Purging Entrieswith Cache ID’s

When you purge an object that uses the Flexible Cache ID feature, a request to purge any object with that URL will cause all objects with the same base URL to be purged.

The Cache-ID feature does not attempt to order elements included in the Cache-ID. So, for example, when query arguments are included in the Cache-ID, they are included in the order they appeared in the original request. If you wish to order the query arguments, this can be accomplished with the Ignore Query Arguments feature.


Flexible Cache IDConfidential & Proprietary

For example, if there are separate cached objects for the following three requests:

http://example.com/query.cgi?page=item1http://example.com/query.cgi?page=item2http://example.com/query.cgi?page=item203

A request to purge any one of these items would purge all three, as they all are based on the same base URL:

http://example.com/query.cgi

Other Cache KeyFeatures

The other features that modify the ARL used to form the cache key continue to function and can be used in combination with the Flexible Cache ID feature. This is because it is the ARL after these features have been applied that is used to compute the cache key + cache ID when the Flexible Cache ID feature is enabled.

Integration To implement the Flexible Cache ID feature you must first carefully identify the cookie, header, and query string names and values that should be included or excluded from the cache ID. If there is a single cookie to consider with only a few possible values, this may be a fairly trivial task. If there are many possible combinations of cookies, headers, or query arguments, this may be fairly complex. Your Integration Consultant will work with you to refine the request matching rules.

Once the rules have been identified, the Integration Consultant should submit a provisioning request with all the basic required information, and the set of request matching rules. This configuration will then be reviewed and carefully tested to ensure that the rules do not generate an excessive number of unique objects in cache for the same request ARL.

See the heading "Important Usage Notes" below in the Akamai Integration section for details regarding proper metadata use to ensure that the purge mechanism works.





In This Chapter

Failover (was Advanced Def

Custom Error Pages • 123

Monitor Origin Server • 12

SureRoute for Failover • 1

Request Queuing • 128

6
Enhanced Availability
ault Content) • 118

5

27

Whenever an Akamai server needs to revalidate the freshness of objects but cannot reach the origin server to do so, the server’s default behavior is to serve these potentially stale objects from cache. This approach helps ensure that the end user receives content rather than an error code, and is particularly helpful in cases where the origin server is unreachable for only a brief period of time.

If content should never be served stale, even in the event that the origin server is unreachable, the Require Revalidation feature should be turned on. In this case, the Akamai server would serve the error code to the client until it could revalidate the content with the origin server.

This chapter discusses features designed to enhance the availability of a Web site to end users. These features provide alternatives to serving an standard error code to the client and ways to tune the Akamai server’s ability to determine that the origin server is not responding.

117

Chapter 6: Enhanced Availability

Failover (was Advanced Default Content)

By default, if the origin server doesn’t respond to an Akamai server’s request to refresh an object in cache, the Akamai server marks the object as fresh and delivers it to the client. This behavior is refered to as "serving stale." Serving stale is the default behavior because it is generally considered better for the user experience than serving an error. If the Akamai server doesn't have the object in cache, or if the Require Revalidation option or Centralized Authorization is used, it serves an error status code (usually 503 or 504) to the client.

The Failover feature lets you specify content to be served in place of the error status code in the event that the origin server cannot be reached and content cannot (or should not) be served stale. This can be used to:

• Maintain a positive user experience. For example, an advertising company might want to display a generic banner ad if the origin server was unable to respond to a request for a new ad. Similarly, any Web site developer might like to customize the error page sent to the user in the event that content is unavailable from the origin.

• Automatically serve a static catalog. An e-commerce Web site may want to serve a static catalog site in the event the origin site is overloaded and cannot perform transactions.

• Automatically divert requests to a backup server. If a Web site has a redundant backup origin server to which Akamai servers can direct traffic if the main origin server goes down, the Akamai edge server can be configured to make that switch automatically when it cannot reach the origin server.

You have two options for serving failover content when the origin server can’t be reached:

Redirect -- serve a redirect (301 or 302) to the user to direct them to different content, or a different server.

Recreated Request -- recreate the request with a new hostname so that the Akamai server can apply new features and potentially fetch content from a different origin server.

Through a related feature—Monitor Origin Server—you can also configure the time it takes for the Akamai server to "time-out" its attempt to connect to the origin server and serve the failover content instead.

Caveats Following is a list of issues to consider when implementing the Failover feature.

• If the failover object is an HTML page, that page should not contain references to embedded objects on the origin server. Obviously if the failover HTML is served, it is likely the origin server is not responding, so inclusion of object references that point to the origin server will likely result in bad links, unless


Failover (was Advanced Default Content)Confidential & Proprietary

those objects also have failover content associated with them.

• When failover content is served to the browser, the response is delivered with the downstream time-to-live that would have applied to the requested object. If the time-to-live for the originally requested content was long, the end user will likely need to force a refresh to retrieve the desired content before the time-to-live expires. This is especially an issue if the failover object was served from the origin with a Last-Modified header. This header should not be included with the failover response or should be set to a time far in the past to avoid having an IMS request from the browser fail to refresh the content.

TechnicalDetails

This feature is an update of the original Default Content feature and provides more flexibility in configuring the failover behavior. In particular, you can:

• Apply failover handling to any response status code (not just 500, 503, and 504).

• Apply failover multiple times. This is useful if there are multiple sources for the content to be served.

• Optionally apply the Failover feature to Range requests.

• Override the status code in a response from the origin to serve a different status code to the client. This is useful in particular where the objective is to serve a custom error page to the client. The forward server will respond to the request for the page with a 200 or 304, and the response to the client needs to be overridden so that the error is delivered with the appropriate error status code (usually 403 or 404).

• Specify that the Akamai server deliver stale content (when possible) as an explicit alternate action. This makes it possible to first attempt other alternate actions (such as serve from an alternate origin), but serve stale content as a last resort.

Response StatusCodes That

Fail-over

Failover is not restricted in any way to the response status code for which it can be applied. However, in the standard configuration, the Akamai server will serve the failover response when status codes 500 Internal Server Error, 503 Service Unavailable, 504 Gateway Timeout, or 000 a special internal status, are returned by the forward process. (Assuming, of course, that the edge server cannot or is not permitted to serve stale content. Remember that serving stale content is the default behavior.)

These status codes are produced by the Akamai server when:

• It is unable to resolve the DNS name (504)

• It doesn't receive an answer from the origin server (503)

• Origin server is unreachable because of a routing problem (504)

• The application server is unable to produce content, or produced improperly formatted content (500)

The origin server may also produce these status codes. Normally, response status codes beginning with the digit "5" indicate cases in which the server is aware that it



has erred or is incapable of satisfying the request. However, the origin server may be configured to produce them in other circumstances.

Failover Actions for Any Response Code

In addition to the standard configuration, you can specify that failover content be served in response to any response code. This is a somewhat more complex configuration and should be used with care. It can be useful for sending customized responses from cache on 403 or 404 errors, for example, without the need to serve a redirect to the error page as is done using the Custom Error Page feature. This can also be used in cases where content is served from Akamai’s NetStorage and a 404 is returned from the storage servers. Rather than serving the 404 to the client, the request can be rewritten to request content from the origin server in the hope that the content will be found there.

Failover Redirect When the Redirect option is used, the Akamai server sends the redirect response to the client in place of the object it could not retrieve. The redirect can be formed from the original URL or can point to a completely different object.

When the redirect is based on the original URL, the configuration file specifies the prefix that should replace the beginning portion of the URL. For example, if example.com wanted to redirect requests

from: www.example.com

to: www.bkp.example.com

the configuration file would have this setting at the global level, and the redirect prefix would be:

http://www.bkp.example.com

A failover redirect can be used as the fallback in the case of ESI processing failures.

RecreatedRequest

In many cases you will want to "recreate" the request with a different Host header so that edge server features can be applied again and the object can be retrieved from a different origin server. This has the advantage of serving content to the end-user client directly, without revealing the alternate origin server name in the a redirect, and without the round-trip required by having the client follow the redirect.

When this option is used, the Akamai server transforms the request internally, as though it came from the client with a different Host header (specified in the configuration file). Then the Akamai server applies the features that were assigned for the new Host header. Since the goal is to retrieve content from a different location, the new Host header is associated with a different origin server. And, since the content may not reside on that origin with exact mapping, or the origin server may have different capabilities than the normal origin server, the ability to apply different features to the request makes it possible to tailor the request for the alternate server. For example, if the alternate origin server doesn't understand how to handle the query strings in a URL, those can be pruned from the request before it is sent to the alternate server.


Failover (was Advanced Default Content)Confidential & Proprietary

For example, imagine that the original request was for

www.example.com/retail/electronics/category.asp?loc=513

The original request arrives with a host header for www.example.com, which the Akamai server might know to be served from origin.example.com. Imagine also that the Failover feature has been enabled to recreate requests for this object with the host header of www.bkp.example.com, which is served from origin.bkp.example.com.

If the Akamai server cannot reach origin.example.com to retrieve content for this request, the request is recreated with the host header www.bkp.example.com and a new configuration is applied. That new configuration might prune the query string from the request. At a minimum, it associates www.bkp.example.com with a new origin server (origin.bkp.example.com) so that the request can be filled by another origin server, presumably in another location.

When this technique is used, the fetched content is stored under a cache key that includes the name of the origin server from which the content was actually retrieved, so that the content of the two origin servers is treated separately. Alternatively, if the content on the alternate server is identical to that of the primary origin server, you can configure the content to be stored under the same cache key while being retrieved using a different DNS lookup.

TieredDistribution

Considerations

In the standard configuration, Failover features are applied only by the Akamai server that responds to the end-client request. When Tiered Distribution or SureRoute are used, the parent servers deliver whatever response code is received from the origin server or generated on the parent. This provides for consistent caching of the response object, regardless of whether it is the same as or different from the originally requested object. The edge server and the parent server will have the same object under the same cache key.

It is also possible to configure Failover to apply at any tier in a Tiered Distribution or SureRoute configuration. For example, if the origin server and the backup server are delivering identical content, and if performance is a critical requirement, then it may be desirable to have Failover apply on the server connecting to the origin, rather than the edge server transacting with the end-user client. When the content is identical, shortening the distance between the origin and the failover decision results in the fastest possible failover. (Note, however, that if the content is not identical on the origin and backup servers, this approach would lead to caching the backup content under the cache key of of the original content.)

POST Requests POST requests are supported by the Failover features. However, this support is not enabled by default so as to avoid inadvertently sending duplicate POST requests to the origin server. When the option is enabled the Akamai server will buffer the POST body so that it can retry the POST if the Failover feature is executed (because the origin server does not respond). Because the POST body is buffered, there is a limit on the size of the POST request that can be retried. The default setting is 16KB.



Integration The Akamai representative should submit a provisioning request. In addition to the basic required information, the request should explicitly state the following:

• The redirect prefix scheme for a relative redirect, or

• The host header and origin server to use to recreate the request

It should also be mentioned that, although the stan


Custom Error PagesConfidential & Proprietary

Custom Error Pages

This feature lets you serve a redirect in place of the requested content based on the response code returned by the origin server or generated by the Akamai server. For example, you can instruct the Akamai server to redirect the client if the request results in a 403 Forbidden response. This is useful when the Akamai server performs the client authorization, because it would otherwise return a standard error page. By redirecting to a different page you can preserve the illusion that the end-user exchange is with the origin server.

Caveats When this feature is used, it should be limited so that it does not apply to requests for image files. As a practical matter, you don’t want to return a redirect to an error page in response to requests for linked images in an HTML page. It would be better to let the error response through. (You could, of course, redirect the requests for the objects to the same objects in another location. This is the approach used by Site Failover.)

TechnicalDetails

When the Akamai server receives a response from the origin server it passes that response to the client unless you instruct it to perform an alternate action. (For example, as explained in the next section, the Akamai server could serve default content in place of the requested content when the origin server cannot be reached. This default action applies only to failure to contact the origin server.)

In cases where the origin server generates an error response, that error message can be tailored to the particular Web site, and the Akamai server simply passes that response to the client. However, when the Akamai server generates the error response, it cannot tailor the response to each Web site. Instead the response is a generic error page served for all Web sites using Akamai edge servers. Errors that the Akamai server might generate include:

• 403 Forbidden in response to a request for content that requires authorization using the Edge Authorization feature.

• 404 Not Found in the case where Redirect Chasing is used and the chase limit is reached before an object is found.

Using this feature, you can serve a 302 redirect to the client so that a response other than the Akamai server’s standard error page is ultimately delivered to the client.

The redirect can be declared as a "relative" redirect, that is, one based on the original URL, or an "absolute" redirect, which can point to a completely different object.

When the redirect is relative, the configuration file specifies the prefix that should replace the beginning portion of the URL. For example, if example.com wanted to redirect requests

from: www.example.com/auth/...to: www.example.com/error/...

when the client was forbidden access to content, the configuration file would have



this setting for the “auth” directory, and the redirect prefix would be:

=http://www.example.com/error


• The HTTP status code for which the redirect should be served

• For an absolute redirect, the URL of the object to serve

• For a relative redirect, the redirect prefix scheme


Monitor Origin ServerConfidential & Proprietary

Monitor Origin Server

This feature configures Akamai servers to detect whether the origin server is responding to new connections on its IP addresses.

In addition to recognizing that an origin server is not accepting connections, the Akamai server will detect when an origin server is responding again. It does this by retrying "bad" IP addresses when going forward for objects on the origin server. You can configure how frequently a "bad" IP is retried, and thus, how quickly the recovered origin server is recognized.

This feature is particularly useful in combination with Fail Action, as it permits the Akamai server to more readily perform the default action and maintain site reliability.

You should keep in mind, however, that the monitoring provided by this feature is local to the particular Akamai server handling requests. This means that each server individually determines whether the origin server is accepting connections, and this information is not propagated to the rest of the network. To monitor the origin server and adjust the behavior of the entire network would be a function of the FirstPoint service.

TechnicalDetails

In the absence of this feature, the Akamai edge server tries the IP’s returned by the DNS lookup in a round-robin fashion. When the Akamai edge server attempts to establish a connection, it selects an IP and attempts to connect for the connect-timeout period (defaults to 5 seconds, but may be different if specifically configured or if the Adaptive Connect Timeout feature is used). If the connection attempt fails, the Akamai server will then attempt to reconnect in the same fashion until the max-reconnects is reached (defaults to 3). Given the default settings, it will take up to 20 seconds for the Akamai server to fail the connection attempt completely and either return the error to the client or take the configured Fail Action. (In some cases the TCP layer detects a failure to connect much sooner than the connect-timeout, and the max-reconnects is reached much sooner than 20 seconds.)

Monitor Origin Server maintains information on the state of origin servers by keeping track of the "health" of the IP addresses the Akamai server uses to go forward. For each IP address the Akamai server maintains:

• status - whether the IP is ‘good’ (accepting connections) or ‘bad’ (not accepting connections)

• retry count - number of consecutive connect failures allowed before marking an IP ‘bad’

• retry interval - the interval before retrying to connect to a ‘bad’ IP

• usage timestamp - when the IP was last used for a connection.

This information makes it possible for the Akamai server to fail the connection attempt more quickly and take the default action for all subsequent requests until the configured “bad-ip-retry-interval” has been reached. The net result is that it generally



will take no more than five seconds times the ‘retry-count’ requests before the client request is served. Subsequent requests will be immediately served the error or default content, which may be a fail-over to a backup server, for whatever period you want to configure. The interval before retrying a ‘bad’ IP can be fairly short, since few requests will experience the delay caused by the connect timeout when a potentially bad IP address is retried.

On DNS refresh, the statistics on the IP addresses are preserved even when the DNS resolution changes.


• The time interval to wait before retrying bad IP’s

• The maximum number of reconnection attempts that the Akamai server should make before sending the error to the client side to take the alternate action


SureRoute for FailoverConfidential & Proprietary

SureRoute for Failover

SureRoute for Failover is appropriate for any content provider interested in improving the reliability of their site. SureRoute configures two additional routes to the origin server, so that, in the event of severe network congestion or complete failure of the direct route, the alternate indirect routes can be used to reach the origin server if at all possible. Each of the indirect routes is tried in turn.

TechnicalDetails

This configuration compliments the other Enhanced Availability features of Akamai edge servers. Those features take effect when the Akamai edge server cannot contact the origin server. Normally the Akamai server will try to reach the origin server a given number of times with a specified timeout for each attempt. This timeout is generally fairly long (several seconds), to ensure that a congested route doesn't cause the timeout to be triggered unnecessarily.

When SureRoute for Failover is enabled, each attempt to reach the origin server for a given request may involve trying the three possible routes in sequence as the connection attempts timeout. Since there are three routes to try, the timeout for each attempt can be relatively short (one second) in the hope that the timeout is a problem with the route, and not with the origin server. Only after all three routes have failed does the Akamai server attempt to reach the origin directly with the normal full-timeout. The logic being that if all routes have timed out, the problem is not likely to be a congested route, and it may be necessary to give the origin server more time to respond to the connection attempt. If that final connection attempt times out, the Akamai server can initiate the fail-action to serve an error, serve default content, or retrieve content from an alternate origin server.

Figure 1. SureRoute for Failover

Integration The Integration Consultant will perform a thorough site review to ensure that SureRoute for Failover is appropriate for the content being served and the Web site’s existing configuration. This review will then be used to prepare the necessary configuration request. In most cases, no changes to the Web site are necessary to enable SureRoute for Failover.



Request Queuing

This feature instructs the Akamai server to queue requests for delivery to the origin server in the order received, and in the event the origin does not respond to a request, to periodically retry sending the request until successful. This is primarily useful for requests that convey information to the origin but do not require a synchronous response to the client. Examples of this include some POST requests and Edge Logging requests. This is particularly useful for avoiding situations where the client may otherwise be held up and time out a connection because the origin server may take a considerable time to respond.

This feature queues requests on each Akamai server individually to ensure sequential delivery of the requests to each server. It is not possible to ensure that requests to separate Akamai servers would be delivered to the origin server in the correct chronological order. Also, since a single end user might be directed to more than one Akamai server, this feature should not be seen as a way to absolutely ensure the sequence of delivery of an end user’s requests.

You can use this feature to queue Edge Logging requests to ensure delivery. However this requires a two-level edge server configuration.

TechnicalDetails

The queuing of client requests occurs before the Akamai server attempts to forward the requests to the origin. (These requests are actually stored to disk so that the queue can be resurrected if the server were to restart for any reason.) Each time the Akamai server forwards a queued request, it checks for a response status other than 503 or 504 from the origin. Any response other than 503 or 504 is considered a successful delivery, and the next queued request is sent forward. (You can configure additional status codes to be considered failures. Note that the Akamai server does not do anything with the response from the origin; it cares only that the status code indicated a successful delivery.)

If a request to the origin fails (returns 503 or 504), the request is retried after a configurable interval, which defaults to 30 seconds. The Akamai server will continue to retry delivery of the first request in the queue until it detects a success (or some other retry limit is reached).

With request queuing, the client is not expected to wait for the ultimate response from the origin server, so you configure a default response object (by providing the ARL for the object) to be sent to the client instead. The Akamai server will retrieve this default response with a GET request and serve it to client requests that are successfully queued. You can configure multiple default response objects to deal with the different client requests that are being queued.

An individual queue will hold up to five hundred (500) requests. This maximum size is not configurable on a per-customer basis, though you can configure multiple queues. When a queue is full, or the Akamai server is unable to queue the request for any reason, client requests that cannot be added are served a 500 Internal Server Error response rather than the configured default success response. You can handle this 500


Request QueuingConfidential & Proprietary

error response with a fail-action (Default Content, Default Redirect, Recreate Request) to send the end client something other than the standard error message or to redirect the client to another site for content.

If the client requests may be delivered in any order, you can optionally configure a set of unordered queues. In this case the requests are assigned to the unordered queues randomly, so all of the queues are used together. This may be desirable if the purpose of the queues is to function as a buffer between the client requests and the origin server at times when the origin server is slow to respond. If a single queue were used in this way, the queue might fill up too quickly and never be able to drain of requests quickly enough even when the origin is available, because the requests in the queue must be delivered and acknowledged in sequence. Though, even in this case it my be possible to empty most of the queue by invoking an option to move failed requests to the end of the queue so that other requests may be tried.

The maximum size of a POST body queued for delivery to the origin is 1MB. A POST body size greater than this maximum will result in a 500 error.

Note: There is an overriding maximum number of queues on a single server of 2000 queues. This limit applies across all customers. There is an overriding maximum number of messages in all queues on a single server of 200,000 requests.

Forward Rate Limiting can be combined with this Request Queuing feature to ensure that, if requests are queued while an origin server is temporarily unavailable, the Akamai server doesn’t overwhelm the origin with requests when it becomes available again.





In This Chapter

General Access Control • 1

Referrer Checking • 133

Block Access by Client IP •

Centralized Authorization

Remote Authorization • 1

Edge Authorization - Cooki

Edge/Central Hybrid Autho

Edge Authorization - URL-B146

Edge Authorization - URL-BTokens • 151

7
Auth - Browser to Edge
32

135

• 136

38

e-Based • 141

rization • 145

ased - Origin Tokens •

ased - Edge Server

Web sites often use cookies or other methods to control access to proprietary content. The Akamai edge server provides several methods to ensure that this access control is preserved when an Akamai server delivers the content.

Many of the features described in this chapter have the term “authorization” in their names. However, most of them also provide for performing “authentication” of the client either by forwarding the request to the origin or authorization server (Centralized and Remote Authorization) or by comparing the client IP with the IP specified in the authorization cookie (Edge Authorization).

Allowing Translate Requests

To ensure that authorization schemes do not interfere with the Content Control Utility (also known as Purge), the metadata should be included within a negative match on the AKAMAI_TRANSLATE method, so that this method is always allowed. CCU uses this request method to determine the cache key of the object to be removed from cache. The appropriate match condition would look like the following:

<match:request.method value="AKAMAI_TRANSLATE" result="false">

...</match:request.method>

131

Chapter 7: Auth - Browser to Edge

General Access Control

You can allow or deny requests for content based on any property of the request that the Akamai edge server can evaluate. For example, the Akamai server supports testing for the presence of an HTTP header and/or header value, so you can allow or deny access to content based on that test. This generalized access control is most frequently employed in the following ways:

• To deny or allow access to content based on the client IP address (as explained later in this chapter).

• To deny access in the absence of a cookie. This is often used during site testing as a simple low-level security mechanism for restricting access to newly published material until it has been reviewed and tested.

• To deny access to specific User Agents (for example, spiders). In this case the restriction may be to deny access to these clients during peak hours.

• To deny access to requests originating from particular geographies. This involves use of EdgeScape to identify the location of the request IP address. (A less drastic version of this approach is to use Content Targeting to redirect the client requests to content appropriate to the geography of the requesting client, or to redirect the client to a customized error page, rather than to serve the standard 403 Forbidden error from the Akamai server.)

When you mark a request for denial, you also indicate the reason for the denial as a simple string. So, for example, if you deny a request based on client IP, you might list “client-ip” as the deny flag. Then, later in the configuration, if there is a reason to remove this denial flag, you would set an “allow” flag of the same name. The server adds denial flags to its deny list, and subtracts “allow” flags from the denial list. At the end of processing the client-request stage metadata, it checks whether any denial flags still exist. If they do, the request is denied. This mechanism allows for implementing complex logic with multiple reasons for denial or access.


Referrer CheckingConfidential & Proprietary

Referrer Checking

Most but not all HTTP requests come with a field that contains the referring URL. For example, if the requested object is an HTML link, the referrer would be the page that contained that link, or if the object was an image, this would be the page that called for that image to be included.

With Referrer Checking enabled, if the domain name in the Referrer field does not match an approved domain or subdomain listed in the configuration file, the Akamai server will deny access.

This feature helps prevent unauthorized syndication of material.

Caveat You must be diligent about updating the list of allowed Referrer fields when you give permission to another site to reference your content.

Referrer checking is intended to handle a list of Referrers on the order of tens to hundreds, not thousands. Performance can be degraded if the list of allowed Referrers is too large.

The ‘strict’ option (explained below) should be used with caution. Some proxy servers strip the Referrer field when forwarding the request. As a result, valid user requests may be denied.

TechnicalDetails

There are actually two degrees of enforcement for Referrer Checking: normal and strict.

Under normal Referrer Checking, if the referrer field is missing or not intelligible for some reason, Akamai will serve the content. This makes sense when you consider that URL's typed into a browser or sent by a bookmark will not have a referrer, and you very likely didn't intend to prevent access through these mechanisms.

Under Strict Referrer Checking, all requests would be required to include an allowed referrer, without exception. This level of enforcement may be appropriate for access to image files that you expect should be requested only as part of an HTML page from an approved domain.

When either level of referrer check fails, the client is denied access to the content and an error page is served instead. The error page states simply that the user does not have permission to access (insert original URL) on this server. You can also choose to serve a custom error page by redirecting the client instead of serving the standard Akamai server error page.

When you list domains to be allowed, it isn't necessary to list all possible sub-domains. For example, you can list simply example.com as an allowed domain and specify that all sub-domains of example.com are allowed.

Referrer Checking is based on the idea of establishing a list of allowed Referrers and blocking all others. It is also possible, through use of the Request Header criteria, to



specify a list of Referrers to deny and allow all others. That solution is more complex to implement, but can be applied if needed. Ask your Integration Consultant for details.

Integration You can directly control Referrer Checking for your content through Configuration Manager, where this feature is called “Control Access by Referrer Domain Rules.”


Block Access by Client IPConfidential & Proprietary

Block Access by Client IP

When you enable this feature, Akamai servers will block particular end-users from accessing specific content. This is useful in two particular instances:

• To halt an attack on a site from a hostile party at a fixed IP address

• To allow access only to the developers when the site is in a staging environment for testing. (This is accomplished in the configuration files by denying all requests, and then turning off the denial feature for only those IP addresses that should have access.)


• A list of client IP addresses to be blocked.

• The list of the IP addresses of the Web site’s origin servers



Centralized Authorization

With Centralized Authorization enabled, the Akamai server forwards every request to the origin server for authorization. This is useful if the you need to maintain tight control over content by authorizing client requests at the origin. Authorization can be performed based on any of a number of factors. Popular implementations include use of Basic Authorization, cookie-based authorizations, and query string authorization.

If the requested object is already in cache, the client request is forwarded to the origin server as an If-Modified-Since request, so that the object does not need to be resent.

Caveats Because Centralized Authorization will cause every request to be forwarded to the origin server, the feature is process intensive. The origin will need to process every request, even though it generally doesn't serve the content. As a result, this feature should be applied only to content that requires authorization.

This feature should not be used simply to require that the origin be contacted on every request if authorization is not required. In the event that the origin server cannot be reached, the content cannot be served, and the client will receive errors instead. The alternative to Centralized Authorization is to use Zero-TTL, which contacts the origin before serving the client, but doesn't "require" authorization from the origin, so a failure to contact the origin will still permit the Akamai server to serve the content (though potentially stale) as a last resort.

Likewise, if the goal is to have the origin server see every request, but you don’t require either authorization or that the origin be contacted before the client is served, Akamai Prefresh can be configured such that the origin is contacted with an If-Modified-Since request after every client request. This provides optimal performance to the end user.

Since Centralized Authorization makes heavy use of If-Modified-Since requests, it’s important you remember that the Akamai server can only make this request if the object is returned from the origin with a Last-Modified header. In the absence of a Last-Modified header, the Akamai server makes its request as a full GET.

TechnicalDetails

Centralized Authorization doesn’t care how the origin server chooses to authenticate the client and authorize the request. The origin server may authorize access based on any data included with the request. For example, authorization could be based on the Authorization header, data in a query string, a cookie, the client IP address, referrer field, etc.

The client request is forwarded to the origin either as an If-Modified-Since request or a full GET depending on whether or not the object is already in cache. (If Large File Optimization is in use, the forward request may be a Range request for the first byte of the file.) The origin server grants access to the object by returning either a 20X or a 304 (Not-Modified) response code (a 304 should be used if possible), and Akamai


Centralized AuthorizationConfidential & Proprietary

serves the content to the client. If the Akamai server receives a 4XX code from the origin server, the client is served the 4XX response. The 4XX response does not replace the object in cache.

Centralized Authorization makes it possible to use HTTP Basic Authorization. If the origin returns a 401 Unauthorized response, the Akamai server sends the 401 to the client. The browser should then prompt the user for identification and password so that the request can be resent with the required Authorization header.


• The list of the IP addresses of the Web site’s origin servers



Remote Authorization

Remote Authorization provides for a separation between the server that authorizes the end user request and the server that provides content to the Akamai edge server. This is particularly useful if you have placed content on Akamai’s NetStorage servers, but wish to authorize the client requests at your own origin server.

Caveats Please carefully review the following caveats with regard to using Remote Authorization:

• By default, Remote Authorization is enabled only for GET and HEAD methods. You can optionally configure it to support POST requests.

• Remote Authorization normally involves a two-level edge server configuration where the requests to the authorization server and to the content server are handled differently. The difference in handling is triggered by use of a different hostname in each request. As a result, removal of content from cache (through the CCU or ECCU mechanisms) must be based on the content server hostname. In practical terms this means you must remember to substitute the client request hostname (for example, www.customer.com) with the content request hostname (for example, content.customer.com) when you use the ECCU, and in some configurations, also for CCU.

• HTTP Headers in the response from the authorization server are not passed forward to the content server. For example, if the authorization server returns a new Set-Cookie header for the client, this Set-Cookie header is not converted to a Cookie: header and forwarded to the content server.

TechnicalDetails

Under Remote Authorization, the Akamai server will first contact an authorization server and then the content server.

The Akamai server obtains authorization by sending the client request (with all its headers, including cookies) to the authorization server. If the Akamai server receives either a 304 Not Modified or 200 OK response, it deems the authorization a success. The Akamai server then processes the original request, either by serving from cache or contacting the content server for the requested object if it is not in cache.

Any response other than 304 Not Modified or 200 OK is considered an authorization failure, and the response (generally 401 Not Authorized, 403 Forbidden, or 302 Moved Temporarily) is returned to the client.

As with Centralized Authorization, every client request is required to be forwarded as a synchronous request to the authorization server and content cannot be served to the client without a valid response. This authorization request is sent forward with cache-busting headers (Cache-Control: no-store etc.) to better ensure that caching proxies will forward the request to the authorization server.

In addition, Set-Cookie headers in the response from the authorization server are passed into the final response delivered to the client. That is, the authorization server


Remote AuthorizationConfidential & Proprietary

can set a new cookie in a 200 OK response and this Set-Cookie header will be added to the headers the origin returns with the content response. This allows the authorization server to control the resetting or expiration of authorization cookies even though it doesn’t deliver the content.

In the event that the directory structure on the authorization server is not the same as on the content server, you can specify how the URL path should be rewritten when the authorization server is contacted. There are some limitations to this rewriting capability. Most often the authorization request is rewritten to a single specific URL on the auth server that invokes the authorization application.

Content RequestCookie

If configured to do so, the Remote Authorization feature will include an identifying cookie in the forward request for content. This cookie indicates to the content server that the request for content originates from an Akamai server, and more importantly, the cookie is included in the forward request only if the Remote Authorization feature was used and the client request was authorized.

TieredDistribution

Cache hierarchy is disabled for requests to the authorization server. As a consequence, it is not possible to apply Tiered Distribution, SureRoute, or SiteShield features to the authorization request.

If cache hierarchy is configured, the request for the content will use it (for example, Tiered Distribution). In the default configuration, the content requests will trigger an authorization request at each hierarchy tier and result in multiple authorization requests for each client request. This is done to ensure that end-users cannot obtain content by mimicing the request from an Akamai edge server to its hierarchy parent. Remote Authorization can be optionally configured to perform authorization only at the edge server (not ICP peers or hierarchy parents) to avoid the multiple authorization requests. When this is done it is imperative that authentication between Akamai servers be properly implemented.

POST Support By default, Remote Authorization does not apply to POST requests, but you can optionally enable support for this request method. As soon as the Akamai server receives the complete request headers, it will forward the request to the authorization server as a GET request without the Content-Length header or the POST body. While waiting for a response from the authorization server, the Akamai server simply doesn’t read data from the client; in other words, it doesn’t buffer the POST body, but makes the client wait instead. The assumption is that the authorization server will respond before the connection with the client times out. If the authorization request succeeds, the forward request to the content server will be the client’s full POST request.

Integration Remote Authorization is an advanced feature that cannot currently be configured through the Akamai Portal. Your Akamai contact should submit a provisioning request for the feature. In addition to the basic required information, the request should explicitly state the following:

• The name of the authorization server



• The IP address(es) of the authorization server

• URL path rewrite required (if any) to forward the request to the authorization server

• The port to use when contacting the authorization server (optional; this will default to port 80)

•


Edge Authorization - Cookie-BasedConfidential & Proprietary

Edge Authorization - Cookie-Based

Edge Authorization allows the Akamai server to authenticate a cookie and authorize the client request without the need to contact the origin server. This is accomplished by including the name of the cookie to be used for authorization in the Akamai server configuration file. The Akamai server looks for this cookie in the client request, and compares the request to the value of the cookie, which contains information about which content the client is authorized to receive.

The cookies used in this case include a message authentication code (MAC) to ensure that end-users cannot modify the cookie values to provide authorizations to which they are not entitled.

As a further security measure, a special Akamai-ID cookie is declared in the configuration file and the Akamai server includes this cookie in requests to the origin server when it has successfully authorized a request but needs to fetch fresh content before serving the client.

Caveats The Edge Authorization feature should be carefully applied only to the content for which it is relevant. There must also be a location on the domain that is accessible without the authorization cookie so that the cookie can be set. Access to this location should be configured with Centralized Authorization or zero-TTL to ensure that the exchange with the origin server is synchronous, and the Set-Cookie header is thus passed to the requesting client.

If you use standard FreeFlow ARL’s on your Web site, you will need to format these ARL’s to not use an Akamai domain so that the authorization cookie can be passed to the client. Your Akamai team is familiar with this requirement and how to satisfy it.

TechnicalDetails

When Edge Authorization is used, Akamai's servers authorize requests by performing the following steps:

1. Check whether the requested content must be authorized or not.

2. For content to be authorized, search for an Edge Authorization cookie with a specified name in the client request headers.

3. Check if the Edge Authorization cookie is genuine by computing the MAC (message authentication code) on the cookie data (plus the salt) and validating the result against the MAC included in the cookie.

4. If an IP address is set in the cookie value, verify that the request came from the specified IP address.

5. If the Expiration Time is set in the cookie value, check that this time has not passed.

6. If the access list is specified in the cookie value, check that the requested content matches one of the entries in the access list.

If all of the above steps are successful, the content is served with a 200, OK. When



one of the steps fails, the Akamai server responds with status code 403, Access Denied.

Using TieredDistribution

By default, when Edge Authorization is used, requests that are forwarded go directly to the origin server, rather than through a cache-hierarchy parent, even when Tiered Distribution is turned on. This is true regardless of whether the request was authorized by the Akamai edge server.

You can enable use of Tiered Distribution for these requests through a separate metadata option. In this case the Edge Authorization requests would always be forwarded through the cache-hierarchy parent.

Setting theCookies

To use cookie-based authorization, the Web site sends end users an Akamai-readable cookie. The end user’s request for content is authorized based on the presence of this cookie.

The cookie can be generated by a function akamai_cookie(), provided by Akamai.

The function takes the following parameters:

End-user IP address – (optional) If provided, Akamai will strictly validate that the cookie came from that IP. This allows an added a layer of protection against an end-user passing around his cookie to other end-users on different machines. If you don’t want to validate the IP, this field should be left out of the cookie.

Expiration time – (optional) If provided, Akamai will validate that the cookie arrived within the expiration time. This expires value is an absolute Unix timestamp (integer value in seconds) that represents the time beyond which this cookie is invalid. Note that this provides some additional level of security over simply using the standard cookie expiration field, since the MAC enforces that this value cannot be altered.

Access List fields – a list of paths against which the path in the incoming request will be matched. For example:

/downloads/*/freeware/poker.exe/airplanes/images/*

The request is authorized as long as the path of the incoming client request (or the path from which the Akamai server obtains the content, if the verify-origin-path metadata is used) matches one of the paths in the access list. This comparison is case-sensitive, so you should be careful in setting up the access list. There is currently no option to make the comparison case- insensitive.Also, the content of the access list should be provided in URL-encoded form so that it will match what comes in the request from the browser. In most cases the link provided to the end-user in an HTML page and the URL that the browser submits will be the same. However, is special characters such as spaces appear in the link, those special characters will be encoded in the URL path. For this encoded form to match the access list, the access list must be encoded also.

Authentication Key (salt) – any string value agreed upon between the content


Edge Authorization - Cookie-BasedConfidential & Proprietary

provider and Akamai. The nature and length of the salt is completely at the discretion of the content provider. However, a longer salt provides more secure encryption. It’s recommended that this salt be a string of at least ten completely random letters (upper and lowercase) and numbers.

The cookie generated will contain all fields, plus a message authentication code (MAC), in the following format:

cookiename=ip=ipvalue~expires=expirestime~access=accesspath1!accesspath2~md5=MACvalue

The MAC is a one-way-function digest (e.g. a hex-to-string encoded MD5 hash) of the values from the name=value pairs in the cookie, plus the secret Salt value. In more mathematical terms, the MAC is calculated like this:

MAC = hex(md5(ipvalue, expirestime, accesspath, salt))

Note that the MAC calculation uses no separators, only the values concatenated, so the actual calculation would be:

MAC = hex(md5(ipvalueexpirestimeaccesspathsalt))

Hence, the MAC ensures that these cookies cannot be forged or altered, as the ’salt’ value (which does not appear elsewhere in the cookie) must be known in order to calculate the MAC. Akamai's servers validate that the MAC matches the data in the cookie before serving any content.

Sample Edge Authorization Cookie:

mycookie=ip=192.22.22.55~expires=971899742~access=/sample.gif!/boo.exe~md5=0f7e53e8cf6a382000dbdb169ae68060;

The MAC for this cookie would be calculated as:

Hex(MD5(192.22.22.55971899742/sample.gif!/boo.exemyseed))

Sample URL using this cookie:

http://www.example.com/sample.gif

Note: The above cookie used “myseed” as a private salt. Two characters are used as delimiters; “~” separates different cookie fields, “!” delimits access control list. These are default values; however, they can be configured on a per-customer basis.

Verifying Accessby Origin Path

In some rare cases it may be difficult to define the access list for the cookie based on the URL path of the client request. This occurs most often if the Akamai server is used to modify the path when requesting content from the origin server. If this is the case, you can choose to have the access list in the cookie compared against the URL path to the origin server when verifying access.

Integration To enable Edge Authorization, the content provider must implement a scheme for passing cookies with appropriate authorization information to the client.

In addition, the feature must be enabled in the edge server configuration file. The Integration Consultant should submit a provisioning request that includes the basic



required information. The request should also explicitly state the following:

• A list of IP addresses and hostname pairs for the origin server from which authorized content is served

• Name of the Edge Authorization cookie set on the browser

• The "salt" used when calculating the MAC for the cookie

• An Akamai-ID cookie for Akamai servers to authenticate themselves to the origin server. This would be a simple name=value combination

• A list of the delimiters used in the cookie, for example:Delimiters: "~" for fields; "!" for the access list of the cookie string


Edge/Central Hybrid AuthorizationConfidential & Proprietary

Edge/Central Hybrid Authorization

Hybrid Authorization is a combination of Edge Authorization and Centralized Authorization. It instructs the Akamai server to forward the request to the origin server using Centralized Authorization whenever Edge Authorization fails to authorize the request.

Caveat Please see the caveats related to Edge Authorization, as all of these also apply to Hybrid Authorization.

TechnicalDetails

Hybrid Authorization involves all of the requirements of both Edge Authorization and Centralized Authorization. If you are not already familiar with them, you should review those sections of this chapter.

When the Akamai server goes forward to the origin server for Centralized Authorization, it will not serve the object without a synchronous response from the origin server. It also checks that configuration settings were applied to the request so that the authorization cannot be subverted by substituting an IP address in place of the origin server name.

The Akamai server does not cache the response from the origin server when it uses Centralized Authorization in this model. This is because the response from the origin server is expected to be something other than the requested content, since the authorization failed, and you don’t want to evict the normal response in favor of an error, a redirect, or an alternate page.

Integration As with Edge Authorization, to enable Hybrid Authorization, the content provider must implement a scheme for passing cookies with appropriate authorization information to the client.

In addition, the feature must be enabled in the edge server configuration file. The Integration Consultant should submit a provisioning request that includes the basic required information. The request should also explicitly state the following:

• A list of IP addresses and hostname pairs for the origin server from which authorized content is served

• Name of the Edge Authorization cookie set on the browser

• The "salt" used to encode the cookie string

• An Akamai-ID cookie for Akamai servers to authenticate themselves to the origin server. This would be a simple name=value combination

• A list of the delimiters used in the cookie, for example:Delimiters: "~" for fields; "!" for the access list of the cookie string



Edge Authorization - URL-Based - Origin Tokens

URL-based Edge Authorization allows the Akamai server to authenticate a URL and authorize the client request without the need to contact the origin server. The most common use case for this feature is to secure digital downloads or video streams such as Akamai HD for Adobe Flash content.

URL-based Edge Authorization is similar to Cookie-Based Edge Authorization described earlier in this chapter, except that:

• the token is contained in the query string of the URL rather than in a cookie.

• each token is unique to the requested URL; you cannot authorize access to multiple URLs with a single token that provides access to a directory of files, and thus there is no "access" parameter to specify. Access is to the single URL. A future version of the Akamai server will make it possible to validate tokens based on a portion of the URL or any other string in the request.

• The tokens can be added to the URLs either by the origin server or the Akamai server.

For example, when Edge Authorization is added to the URL for a file, the HTML link to that file might change from this:

http://download.example.com/somedirectory/somefile.exe

to this:

http://download.example.com/somedirectory/somefile.exe?__gda__=1241790837_6ef643b29daa2c7fbc23c5d89c9ec366&fileExt=.exe

When the Edge Authorization feature is enabled for a request, the Akamai server will validate the token before serving content. If the token is valid, the client is authorized to receive the requested content, and is served from cache if possible. If the token is missing, expired, or invalid, the configuration file specifies whether the request should be denied outright with a 403 Forbidden response, or forwarded to the origin server for authorization.

Whenever a request is forwarded to the origin to refresh the content in cache, the request is sent without the authorization token, so the origin server doesn’t need to be aware of the tokens in any way. This refresh request will contain a cookie specified in the configuration file so that the origin can confirm that this is a request from an Akamai server that has applied the required Edge Authorization logic before requesting the content.

Caveats URL-Based Edge Authorization requests will use Tiered Distribution only when the authorization succeeds. When authorization fails, the request is forwarded directly to the origin server. (This makes URL-Based Edge Authorization incompatible with SiteShield if failed requests are to be forwarded to the origin.)

When validation of a URL fails, it is difficult to determine the cause of the failure


Edge Authorization - URL-Based - Origin TokensConfidential & Proprietary

based on historical information. Effective debugging requires a working failure case that can be observed in real time.

TechnicalDetails

Before going further, let’s take a quick look at the example URL from the discussion above so the elements used in authorization are clear for the rest of this discussion. Here’s that example URL again:


In the example above, the elements relevant to authorization are:

URL path: /somedirectory/somefile.exe&fileExt=.exe

Token name (or parameter): __gda__ (configurable; must be 5 to 12 characters in length)

Token expiration: 1241790837 (expressed as an epoch based on GMT)

Token value: 6ef643b29daa2c7fbc23c5d89c9ec366

Notice that the extra query argument fileExt=.exe is included as part of the URL path for purposes of calculating the token. Any query arguments other than the authorization token are part of the URL path. (Query arguments are separated by the ampersand character.) This particular query argument is added after the token to ensure that Internet Explorer will prompt the user to save the file rather than attempt to open it in the browser. We show it here only because securing digital downloads is a common use for this feature.

Other elements used when generating the authorization token are:

Salt (also know as "key" or "secret"): any typeable string of up to 128 characters. This value is known to the origin server and the Akamai server for purposes of securing the token.

Extracted Value: this element is optional and can be any value present in the client request that is accessible to the Akamai server. In particular, for added security the client’s IP address or the value of a session cookie is sometimes used.

Generating theTokens

Tokens can be added to URL’s either at the origin server, or on the Akamai server. Which approach is most appropriate depends on the specific application. In the case where URL-Based Edge Authorization is used to deliver digital downloads, the common case is that tokens are generated at the origin server.

Origin Generated Tokens

Akamai provides sample code for generating the tokens used in both Cookie-Based and URL-Based Edge Authorization. URL-based token generators are available in ASP, C, C#, Java, Perl, and PHP versions. You’ll find them on the Akamai portal at:

https://control.akamai.com/portal/content/tools/AccessControl.jsp




More details are included in the Content Provider Integration section below.

Akamai Generated Tokens

See the next major section in this chapter: Edge Authorization - URL-Based - Edge Server Tokens

Validating theAuth Tokens

If the edge server configuration file indicates that the request should be validated, the Akamai server will perform the following steps:

1. locate the authorization token in the URL

2. delete the token so that it won't be in the logs, the cache key, or the forward URL

3. authenticate the token by

• confirming that the expiration time is less than the current time.

• checking for existence of the extracted value variable (if one was specified in metadata) for use in computing the authorization token. If the variable is not found in the request, authorization is considered failed.

• recalculating the authorization token using all of the expected values and comparing it with the token in the URL

If authorization fails, the client request is forwarded to the origin server for validation. You can optionally configure the Akamai server to deny the requests outright. (In the case where NetStorage is the origin server, the requests are normally denied, or the 403 response is converted to a redirect to the login page.)

When authorization succeeds, but the content in cache must be refreshed, the request is forwarded without the authorization tokens. The Akamai server can also be configured to send an Akamai-ID cookie along with the request so that the origin server can detect that the request is being forwarded for content, not validation.

Integration To enable URL-base Edge Authorization, the content provider must:

• Configure the origin server to generate the authorization tokens. (See below for more details.)

• Provide the information needed by the Akamai server to validate the authorization tokens. This would include:

• The token query argument name if other than the default value (the default value is __gda__). The string must be 5 to 12 characters in length.

• The salt value

• The location from which to extract a value to use as the extracted-value when generating the token. (Use of an extracted value is optional.)

• The edge-origin authorization cookie to include in requests to the origin server. This is a simple name=value pair.


Edge Authorization - URL-Based - Origin TokensConfidential & Proprietary

• Provide guidance on how authorization failure should be handled. Should the Akamai server:

• deny the request, (403 Forbidden)

• forward the request to the origin server (if not Net Storage)

• serve the client a redirect to a login page

• handle the request in some other manner

Origin-GeneratedTokens

As mentioned in the feature summary above, it is possible to implement this feature such that the origin server generates the authorization token and adds it in the query string.

As always, take care that any requests being validated by the Akamai server contained the required tokens, and that the tokens used the query argument name expected by the Akamai server.

The authorization tokens used by this feature are calculated roughly as follows:

token = hex(md5(key from mdt, md5(expiration from the token, URL without the token, key from mdt, extract-value if specified and present))

Note that the above is only a rough guideline, and you should consult the source code for the token generators for an exact formula for creation of the tokens.

Sample Auth Token Generators

Akamai provides sample code for generating the tokens used in both Cookie-Based and URL-Based Edge Authorization. URL-based token generators are available in ASP, C, C#, Java, Perl, and PHP versions. You’ll find them on the Akamai portal at:


It’s important to note that the various token generators provided at the link above do not contain a uniform set of features. The generator example with the highest version number is likely to contain features not found in the others. At the time of this writing, the Java version of the token generator contains the most features. it provides for specifying the following inputs to the token generator:

inUrlPath - a String containing the path portion of the URL (i.e., "/path/to/file.ext")

param - a string containing the query string parameter containing the authentication information. This must be 5 to 12 characters in length. (This is called the token name or query argument name in the discussion above).

window - a long containing the length of time the authentication will remain valid

salt - a string that will be used as a salt for the authentication hash. This can be up to 128 typeable characters long.

extract - a string containing a specific value that must be present in the client request for authorization to succeed. (This is called the extracted-value in the




discussion above and is optional. It would normally be a value unique to the user request such as the client IP address or session cookie value.)

time - is a long containing the time (in Unix epoch format based on GMT) when the token should become valid. (This provides for generating the tokens in advance of their use. The Akamai server always calculates the expiration time of the token based on the current server clock time plus the window (or expiration time as it is called in this document).

extensionFix - is a boolean indicating whether the standard Internet Explorer extension fix (e.g., "&ext=.exe") should be added to the end of the resulting URL+token

<exclude-query>off</exclude-query>

<grace-period>0s</grace-period><hash>md5</hash>


Edge Authorization - URL-Based - Edge Server TokensConfidential & Proprietary

Edge Authorization - URL-Based - Edge Server Tokens

The feature described in this section is virtually identical to the preceding feature (Edge Authorization - URL-Based - Origin Tokens). As the names imply, a significant difference in the features is where the authorization token is generated (at the origin, or at the edge server). How the feature is being used may influence the choice of where to generate the tokens. When used to secure digital downloads, the tokens are often generated at the origin server. When used to grant access to many objects embedded within an HTML page, and thus prevent deep-linking to content, the tokens are often generated by the Akamai edge server.

URL-based Edge Authorization allows the Akamai server to authenticate a URL and authorize the client request without the need to contact the origin server. Currently, the most common use case for this feature is to secure digital downloads or video streams such as Akamai HD for Adobe Flash content. In these use cases, the token is usually generated by the origin server on each user request.

As originally designed, the URL-based Edge Authorization was intended to substitute for the cookie-based authorization when the client did not support cookies. The intent was to authorize access to all the objects embedded within an HTML page once the origin server had granted access to the page. The logic being that if the client is permitted to receive the base HTML page, then presumably the client is permitted to receive all of the images and other content required to properly display the page in the browser.

To accomplish this, the Akamai server dynamically writes authorization tokens into the query string portion of embedded URLs before the page is served to the client. The parameters for this rewriting are included in the edge server configuration file, along with corresponding parameters for validating the URL’s when the requests for these object are returned by the browser.

URL-based Edge Authorization is similar to Cookie-Based Edge Authorization described earlier in this chapter, except that:

• the token is contained in the query string of the URL rather than in a cookie.

• each token is unique to the requested URL; you cannot authorize access to multiple URLs with a single token that provides access to a directory of files, and thus there is no "access" parameter to specify. Access is to the single URL. A future version of the Akamai server will make it possible to validate tokens based on a portion of the URL.

• The tokens can be added to the URLs either by the origin server or the Akamai server.

For example, when Edge Authorization is added to the URL for a file, the HTML link to that file might change from this:

http://download.example.com/somedirectory/somefile.exe



to this:


When the Edge Authorization feature is enabled for a request, the Akamai server will validate the token before serving content. If the token is valid, the client is authorized to receive the requested content, and is served from cache if possible. If the token is missing, expired, or invalid, the configuration file specifies whether the request should be denied outright with a 403 Forbidden response, or forwarded to the origin server for authorization.

Whenever a request is forwarded to the origin to refresh the content in cache, the request is sent without the authorization token, so the origin server doesn’t need to be aware of the tokens in any way. This refresh request will contain a cookie specified in the configuration file so that the origin can confirm that this is a request from an Akamai server that has applied the required Edge Authorization logic before requesting the content.

Caveats URL-Based Edge Authorization requests will use Tiered Distribution only when the authorization succeeds. When authorization fails, the request is forwarded directly to the origin server. (This makes URL-Based Edge Authorization incompatible with SiteShield if failed requests are to be forwarded to the origin.)

When validation of a URL fails, it is difficult to determine the cause of the failure based on historical information. Effective debugging requires a working failure case that can be observed in real time.

When the Akamai server generates and inserts the tokens, the feature requires use of Dynamic Content Assembly to insert the authorization token.

TechnicalDetails

Before going further, let’s take a quick look at the example URL from the discussion above so the elements used in authorization are clear for the rest of this discussion. Here’s that example URL again:


In the example above, the elements relevant to authorization are:

URL path: /somedirectory/somefile.exe&fileExt=.exe

Token name (or parameter): __gda__ (configurable; must be 5 to 12 characters in length)

Token expiration: 1241790837 (expressed as an epoch based on GMT)

Token value: 6ef643b29daa2c7fbc23c5d89c9ec366



Notice that the extra query argument fileExt=.exe is included as part of the URL path for purposes of calculating the token. Any query arguments other than the authorization token are part of the URL path. (Query arguments are separated by the ampersand character.) This particular query argument is added after the token to ensure that Internet Explorer will prompt the user to save the file rather than attempt to open it in the browser. We show it here only because this is a common use case.

Other elements used when generating the authorization token are:

Salt (also know as "key" or "secret"): any typeable string of up to 128 characters. This value is known to the origin server and the Akamai server for purposes of securing the token.

Extracted Value: this element is optional and can be any value present in the client request that is accessible to the Akamai server. In particular, for added security the client’s IP address or the value of a session cookie is sometimes used.

Generating theTokens on theAkamai Server

Tokens can be added to URL’s either at the origin server, or on the Akamai server. If you are interested in generating tokens at the origin server, you should read the immediately preceding section in this chapter: "Edge Authorization - URL-Based - Origin Tokens". Following is a description of how to generate tokens on the Akamai server.

To generate tokens in the URLs, metadata in the edge server configuration file specifies the following:

• Salt: The salt used to mangle the hash of the authorization token. This can be up to 128 typeable characters long.

• Query argument name: The name to give the query string argument that will contain the authorization token.

• Extracted value name: (Optional) The name of a cookie (or other request variable) whose value should be included in the hash when the authorization token is generated. If it is specified, and the client request lacks the cookie or other request variable, the authorization tokens are not generated.

• Expiration time: the time for which a generated token will be valid. The default is 30 seconds. This time should be short to prevent the sharing of valid URLs among users without authorization.

The information above is used by ESI to calculate the token for each embedded link and insert the token appropriately. How does ESI know which URLs should contain authorization tokens? You can indicate this in one of two ways:

• Add the needed ESI code to the URLs in the document at the origin

• Have the Edge Akamaizer insert the ESI code into the URLs based on a regular expression match.

Each of these options is described in somewhat more detail in the following sections.



Including the ESI code in URLs

Adding the necessary ESI code to URLs is fairly straightforward. You simply add the ESI code:

<esi:vars>$generate_dist_auth(’’’original-URL’’’)</esi:vars>

In the line above, “original-URL” is a relative URL. That is, it should not contain the protocol or origin server name. For example, if the original URL reference looked like this:

<img src="http://www.example.com/example.gif?queryarg1=value1”>

Then the corresponding URL reference with the ESI code would be:

<img src="http://www.example.com/example.gif?queryarg1=value1&<esi:vars>$generate_dist_auth('''/example.gif?queryarg1=value1''')</esi:vars>”>

Adding the ESI code in the original source provides maximum flexibility regarding which URLs receive an authorization token.

Adding the ESI Code Using the Edge Akamaizer

You can have the Edge Akamaizer insert the ESI code for you by specifying:

• which tag types should be rewritten (for example, “a href” or “img src”)

• the regular expression for matching the relevant URLs

This information is included in the edge server configuration file as instructions to the Edge Akamaizer for locating and rewriting the URLs. The metadata tag to specify that all “img src” type URLs with query strings should be rewritten would look like this:

<edgecomputing:akamaizer.tag-filter><rule>#(^\w+://[^/

]+)([^\?]+\?.*)#$1$2&<esi:vars>$generate_dist_auth('''$2''')</esi:vars>#</rule>

<flags></flags> <onmatch>continue</onmatch> <scope>attr</scope> <tags>img/src</tags> <type>include</type></edgecomputing:akamaizer.tag-filter>

You can be as specific as you need to be with the regular expression match and substitution. In practice, the match example above, and a similar match for URLs without query strings, is all that is needed to have all embedded images served using the authorization tokens.

Validating theAuth Tokens

If the edge server configuration file indicates that the request should be validated, the Akamai server will perform the following steps:

1. locate the authorization token in the URL

2. delete the token so that it won't be in the logs, the cache key, or the forward URL

3. authenticate the token by



• confirming that the expiration time is less than the current time.

• checking for existence of the extracted value variable (if one was specified in metadata) for use in computing the authorization token. If the variable is not found in the request, authorization is considered failed.

• recalculating the authorization token using all of the expected values and comparing it with the token in the URL

If authorization fails, the client request may be forwarded to the origin server for validation. You can optionally configure the Akamai server to deny the requests outright. (In the case where NetStorage is the origin server, the requests are normally denied, or the 403 response is converted to a redirect to the login page.)

When authorization succeeds, but the content in cache must be refreshed, the request is forwarded without the authorization tokens. The Akamai server can also be configured to send a cookie along with the request so that the origin server can detect that the request is being forwarded for content, not validation, and that the Edge Authorization feature was applied to the request and succeeded.

Browser CachingIssues to Consider

URL-based Edge Authorization changes the query strings for the embedded images in an page. As a result, any time the browser forces a refresh of the underlying page, all of the images may need to be retrieved again if the URL's of the images retrieved for the prior instance of the page do not match the URL's in the new page.

Similar behavior doesn't occur with cookie-based edge-auth because the cookies aren't part of the URL, so they can vary without requiring the retrieval of new content.

For this reason it is recommended that you limit the rewriting of URL’s for embedded images and links to only those that truly require authorization.

Integration To enable URL-base Edge Authorization, the content provider must:

• Configure the origin server to generate the authorization tokens. (See below for more details.)

• Provide the information needed by the Akamai server to generate and validate the authorization tokens. This would include:

• The tokan query argument name if other than the default value (the default value is __gda__). The string must be 5 to 12 characters in length.

• The salt value

• The expiration time for the tokens. (This i called the "window" in the Java version of the token generator and is expressed as a number in seconds there. It is the "expires" value in configuration file metadata.)

• The location from which to extract a value to use as the extracted-value when generating the token. (Use of an extracted value is optional.)

• The edge-origin authorization cookie to include in requests to the origin server. This is a simple name=value pair.



• Provide guidance on how authorization failure should be handled. Should the Akamai server:

• deny the request, (403 Forbidden)

• forward the request to the origin server (if not Net Storage)

• serve the client a redirect to a login page

• handle the request in some other manner

• insert the necessary ESI code into the embedded object URLs, or

• provide the information needed for the Edge Akamaizer to insert the code. This would include:

• the tag types (for example, ‘img src’) that are to use URL-based Edge Authorization

• the regular expression match/replace strings for inserting the code in appropriate URLs



In This Chapter

Set User Agent • 158

Akamai-ID Cookie • 159

Signature Header Authenti

SSL Client Certificate Authe

8
Auth: Edge to Origin
cation • 160

ntication • 162

This chapter describes methods that can be used by the origin server to identify requests as coming from an Akamai server.

Without any special settings, origin servers can easily identify Akamai servers by their HTTP Via header. The Via header itself is relatively static and looks like the following:

Via: 1.1 akamai.net (ghost) (AkamaiGHost)

With the exception of some internally generated requests, such as requests for the SureRoute test object, this header is included in all requests to the origin server. If you are only mildly concerned about preventing random users from directly accessing content on the origin server, this is generally adequate. The origin server can deny requests that don’t contain the Via header if they are requests for content other than the test object or other well-known requests generated directly by the Akamai server.

Beyond the Via header, there are several methods for authenticating the Akamai server. They are described here in order from simplest (and least secure) to most comprehensive.

157

Chapter 8: Auth: Edge to Origin

Set User Agent

Set User Agent lets you replace the User Agent header in the original request with an identifying string of your choosing when the request is forwarded to the origin server. This can be useful either as a security measure (to serve requests only when they are sent by an Akamai server) or for origin server logging of Akamai traffic.

Caveats When the Set User Agent feature is used, you won’t immediately receive information about the User Agents that originate requests for your content. However, you can capture this information in Akamai logs. See Log Delivery below for information about the Log User Agent option.

A proxy between the Akamai server and the origin server may replace the User-Agent header with its own.

This feature also can be subverted by an attacker who has access to low-level network data and can control HTTP request headers.

Integration You can directly control whether the Akamai server sends the User-Agent header received from the client, or changes the value of the header to “Akamai Edge”. (You cannot specify a custom string for the header value. ) In Configuration Manager this feature is called “Edge Server Identification” and is included in the category “EdgeSevices - General.”


Akamai-ID CookieConfidential & Proprietary

Akamai-ID Cookie

You can specify the name and value of a cookie to be sent with each request an Akamai server makes to the origin. This cookie is called the Akamai-ID Cookie. This can be useful either as a security measure (to serve requests only when they are sent by an Akamai server) or for origin server logging of Akamai traffic.

Caveats This feature can be subverted by an attacker who has access to low-level network data and can control HTTP request headers.

TechnicalDetails

The Akamai-ID cookie format follows the Netscape cookie specification and will be sent with every request from an Akamai server to the origin server.

Cookie: mycookie_name=mycookie_value

By checking for both the Akamai-ID Cookie and the Via header, an origin server can discourage all but the most determined hackers from reaching the site directly. Also, while the Via header is static and thus relatively easy to “spoof,” you can change the name or value of the cookie through the request process if you feel a need to update it.


• The cookie for Akamai servers to authenticate themselves to the origin server. This would be a name=value combination.



Signature Header Authentication

This feature configures Akamai servers to include two special headers in requests to the origin server. One of these headers contains basic information about the specific request. The second header contains similar information encrypted with a shared secret. This allows the origin server to perform several levels of authentication to ensure that the request is coming directly from an Akamai server without tampering.

Caveat This feature involves additional processing overhead both on the Akamai server and the origin server. However, this processing overhead is less significant than that involved in use of SSL client certificate authentication.

TechnicalDetails

When appropriately configured, the Akamai server can authenticate itself to origin servers through signed HTTP headers. When an Akamai server contacts an origin server, it will include the following two headers in the request. The actual names of the headers are configurable; the default values are shown here.

X-Akamai-G2O-Auth-Data: version, Akamai-ip, client-ip, time, unique-id, nonce

X-Akamai-G2O-Auth-Sign: base-64-encoded-signature

The X-Akamai-G2O-Auth-Data header includes the following information:

The base-64 encoded signature for the X-Akamai-G2O-Auth-Sign header is generated based on one of the following algorithms below. You can choose which version is used. In the algorithms, key is the shared secret, data is the contents of the X-Akamai-G2O-Auth-Data header, and sign-string is the string that we want to sign. By default this is the URL from the HTTP request line (the first line of the

Table 1. X-Akamai-G2O-Auth-Data Header Fields

Field Description

version Indicates the encryption format for the authentication

Akamai-ip The Akamai server’s IP address

client-ip The IP address of the client. This value will be the first public IP address in the X-Forwarded-For header. If there is no X-F-F header, or the values in the header are not valid public IP addresses, the connecting client IP addresss is used.

time The current epoch time (for example 1008979391, for Fri Dec 21 16:03:11 2001)

unique-id A unique ID with some randomness that will guarantee uniqueness for header generated at the same time for multiple requests

nonce A simple string or number that tells the origin which key to use to authenticate the request. This makes it possible to transition from one key to another; during the transition the origin server will need to support more than one key.


Signature Header AuthenticationConfidential & Proprietary

HTTP request) without the surrounding method, protocol or space character delimiters.

version 1: MD5(key,data,sign-string)

version 2: MD5(key,MD5(key,data,sign-string))

version 3: MD5-HMAC(key, data, sign-string)

When the origin server receives a request it can use the information in the request to check all of the following:

1. Both of the above specified headers exist.

2. The version given in X-Akamai-G2O-Auth-Data is a supported version.

3. It has the key for the nonce given in X-Akamai-G2O-Auth-Data

4. The time given in X-Akamai-G2O-Auth-Data is + or - 30 seconds within the current time. (It's up to the origin server to relax or make this check more strict by either increasing or decreasing the allowable time difference).

5. The given X-Akamai-G2O-Auth-Data header hasn't been used before. (If the origin server wants to do replay attack prevention, it has to make sure. This means the origin will have to keep track of these headers for a little while.)

6. The signature matches the given data header and the sign-string.

If any of the above steps fail, the origin server should reject the request. Akamai can provide sample code to assist in implementing these authentication steps.


• The encryption algorithm (version) to use

• The key for encryption of the signature header

• The nonce that will identify the key for the origin server

Because this feature involves additional overhead for serving each request to the origin server, you should carefully ensure that it is applied to the appropriate scope of the Web site.



SSL Client Certificate Authentication

This feature enables the Akamai server to submit its SSL certificate to origin servers during the SSL handshake. This is the most secure form of Akamai-to-origin authentication currently available. However, the trade-off for this added authentication security is that it uses the SSL protocol, which has significant overhead associated with it.

Caveat This feature should not be enabled unless the origin server has been configured to request the certificate from the Akamai server. If the feature is enabled and the origin does not request the certificate, the Akamai server will discard the connection rather than reuse it for subsequent SSL requests. Since use of persistent connections between the Akamai server and origin server reduces number of SSL handshakes required to deliver content, loss of the persistent connection feature will negatively impact performance.

TechnicalDetails

By default the Akamai server never submits its SSL certificate to origin servers, even when it is requested during the SSL handshake. When this feature is enabled, Akamai servers will submit their certificate to the origin server upon request during the handshake. If the Akamai server connects to the origin server over the HTTP protocol (rather than HTTPS), it will not submit a certificate to the origin.

The certificate the Akamai server submits has the common name of “a248.e.akamai.net”. This is the same certificate it would serve to a browser for an HTTPS request on the FreeFlow network.

ReusingConnections

When this feature is enabled the Akamai server will only save a connection (as a persistent connection) if the origin server requested a certificate. Otherwise, the connection will be thrown away after the request completes.

Enforcing theCertificateExchange

You can optionally instruct the Akamai server to abort an SSL connection to the origin server if the origin server does not request a certificate. When this option is enabled and the connection is aborted, the requesting client (browser) is served a 403 response.

This feature applies only to authenticating the Akamai server as a client to the origin server. It does not in any way provide for authenticating end users via client certificates.

This feature does not allow for origin request of the SSL certificate during renegotiation of an SSL connection. The origin server must request the Akamai server’s SSL certificate during the initial SSL handshake, not later during a renegotiation.


SSL Client Certificate AuthenticationConfidential & Proprietary

You can also separately enforce that the origin server serves a valid certificate. When this requirement is configured, the Akamai server will abort any forward request and serve an error to the user if the origin server doesn’t serve a valid certificate. The default remote server certificate checking is non-strict, which means that the Akamai server logs an alert for a certificate failure, but it does not deny the request to the client.

Requiring an SSLConnection

You can also configure the Akamai server to request content only over an SSL connection, regardless of whether the end user requested the content with HTTP as the protocol. This will further ensure that the SSL Certificate Authentication is used to transfer sensitive content.

Like most configuration options, you can apply this requirement to only the content that must be transferred securely. For example, you might require that your HTML or other text-based content be requested using HTTPS, but allow your image files to be requested over HTTP. The HTML that is served to the end user could contain all http: references, but the Akamai server would convert these to https: internally and connect to the origin using SSL.

Integration To implement this feature, the origin server must be configured to request and verify the Akamai certificate.

The Integration Consultant should submit a provisioning request that includes all the basic required information and explicitly states:

• Whether the Akamai server should abort an SSL connection if the origin server fails to request the Akamai certificate.

• Whether the Akamai server should abort an SSL connection if the origin server certificate is determined to be invalid.

• Whether any content should be requested from the origin only over an SSL connection.





In This Chapter

Edge Side Includes • 166

EdgeAkamaizer • 167

Process POST Body Through

DCA Output Caching • 170

9
Edge Computing
DCA • 169

This chapter discusses features for processing content on Akamai edge servers so that otherwise dynamic content can be cached at the edge and served to clients without the need to contact the origin. Edge Side Includes can help maximize the cacheability of your content and in the process reduce bandwidth and origin server load. We highly recommend that you examine this option before you assume that content is not cacheable.

165

Chapter 9: Edge Computing

Edge Side Includes

Edge Side Includes (ESI) make it possible for Akamai servers to assemble dynamic content. Because the Akamai server performs the assembly, pages that otherwise would have been entirely uncacheable can now be partially cached at the edge, reducing bandwidth costs and eliminating the "least-common-denominator" cacheability problem.

TechnicalDetails

Without the use of some form of Dynamic Content Assembly on the Akamai server, Akamai servers cannot effectively cache HTML pages that contain dynamic elements. Each dynamic page is potentially unique and cannot be served to multiple clients.

ESI uses an XML-based mark-up language to separate these dynamic documents into their dynamic and cacheable components. This allows the Akamai server to assemble the page from the components, some of which can now be cached on the Akamai server.

For example, if an otherwise static page contains dynamically inserted advertisements, the page would normally not be cacheable because it contained dynamic content. Using ESI, the dynamic advertisement can be separated from the rest of the page so that the majority of the page can be cached on the Akamai server, and the server need only fetch and include the advertisement itself.

For an overview of ESI and the ESI language, see Edge Server ESI Developer's Guide, available on the Akamai customer portal at https://control.akamai.com/

Integration Access to ESI processing is enabled through the configuration files. Once access has been enabled, HTML documents can be nominated for ESI processing either through the configuration file, or through HTTP response headers.

Beyond enabling the feature, and nominating files for ESI processing, the Web site’s content must be marked up using the ESI markup language.


Once the Web site’s edge server configuration file contains the setting to enable ESI through response headers, you can nominate a file for ESI processing in a response header using the Edge-control header dca. The specific header syntax is:

Edge-Control: dca=esi

If files are nominated for ESI processing through configuration files, you can turn off ESI processing for an object by including the following Edge-Control header:

Edge-Control: dca=noop

ConfigurationFile


The request to enable ESI should include a request to enable ESI through response headers to avoid having to file a separate request for this functionality.


EdgeAkamaizerConfidential & Proprietary

EdgeAkamaizer

The EdgeAkamaizer makes it possible to selectively replace strings in HTML or XML files served from Akamai edge servers without the need to write those pages using Edge Side Includes. The replacement is performed based on regular expression matching specified in edge server configuration files.

Key applications for this feature include:

• selective rewriting of URL’s for objects to be served from separate secure and no-secure domains so as to obtain optimal benefits from Akamai for both types of content.

• substitution of session IDs into embedded links. This makes it possible to cache a page containing session IDs for one user, but replace the session IDs in the cached version before serving it to a different user. Because this substitution is specified in the configuration file and performed on the Akamai edge server, it should require no integration on the origin.

TechnicalDetails

The Akamaizer on the Edge uses regular expression matching and replacement specified in the edge server configuration files. In configuration, you first specify which objects you want to act on. Then for each set of objects, you can specify the following:

• The scope of the page to which the changes should be applied. You can specify the type of tags in which to look to replace strings. For example, replace inside tags that contain "a/href," or "img/src."

• The text to be replaced and the replacement text.

• Tags and text that should not be replaced.

• Sections to ignore. For example, you could specify that the Akamaizer ignore everything between <script> and </script> or <style> and </style>

The matched text or replacement text can include HTTP variables.

Multi-byte encoded pages can be successfully filtered because the pages are converted into UTF8 prior to processing. The EdgeAkamaizer is i18n compliant. To use the i18n functionality, you enable a separate option in the configuration file.

The Edge Akamaizer does not replace strings inside of non-HTML blocks of code such as JavaScript. (This will be supported in a future version.)

For more information about regular expression matching, see Perl Compatible Regular Expressions at http://www.pcre.org/pcre.txt

Integration The regular expression matching and replacement filters must be included in the edge server configuration files and include the information listed above. Your Integration Consultant will work with you to properly define the filters.

Once the match/replace filters have been configured, you can nominate content for


http://www.pcre.org/pcre.txt

http://www.pcre.org/pcre.txt


Edge Akamaizer processing either through the configuration file or through HTTP response headers.


Once the Web site’s edge server configuration file contains the setting to enable Edge Akamaization through response headers, you can nominate a file for processing using the Edge-control header dca. The specific header syntax is:

Edge-control: dca=akamaizer

If files are nominated for Edge Akamaization through configuration files, you can turn off processing for an object by including the following Edge-Control header:

Edge-Control: dca=noop


The Integration Consultant should submit a provisioning request that includes the basic required information and very careful definition of the match/replace filters to apply.


Process POST Body Through DCAConfidential & Proprietary

Process POST Body Through DCA

You can nominate your POST requests for Dynamic Content Assembly so that the POST request body can be processed with the POST response object and the assembled response served to the client. This applies to ESI, or JAVAP processing of the POST request body and response.

The maximum allowed size of a POST body that is nominated for Dynamic Content Assembly is 16K bytes. If this limit is exceeded, the client is served a 500 error response.

To make use of this feature, you will likely also want to enable caching of the POST response as described in the chapter Cache - Advanced under the title Cache POST Responses.



DCA Output Caching

By default, the results of Dynamic Content Assembly are served to the requesting client but not cached by the Akamai server. DCA Output Caching allows Akamai edge servers to cache the output separately from the underlying templates used to generate it. This is useful if the output is not customized to an individual user request, but must still be generated dynamically on a frequent interval. Caching the output for a short period of time can dramatically improve performance to end users and reduce load on the origin server.

For example, a Web site that displays a side banner of sports scores might have the content of the banner assembled on the edge server from individual score fragments. The framents themselves may be cacheable for only a very short time, on the order of a few seconds. The template itself may be cacheable for hours. If output caching were not used, the template page would be processed through ESI for every request from an end user. As a result, every end user would experience the slight delay associated with processing.

With output caching, the template would be processed only when the output file expires. The expiration of the output file could be computed by the edge server as the minimum remaining lifetime of the included fragments, or a preset minimum time-to-live. An end user would experience the delay required for processing only if the output file had expired in cache.

TechnicalDetails

When Output Caching is used, only the final result of DCA processing is cached. This detail is important if the solution used involves a daisy chain of processes. For example, handling of session-ID’s through URL’s may involve processing the page with the Edge Akamaizer to insert ESI code into links in the page and then process the page through ESI to insert the client’s individual session ID in place of the ESI code. It is probable that breaking the daisy-chain into two separate processes so that the output of the Edge Akamaizer could be cached would save a good deal of processing effort.

DCA Output Caching is compatible with Tiered Distribution configurations.

When Output Caching is used, the object is served to the client with a Last-Modified header with a date/time value corresponding to when the output was generated. You can optionally send no Last-Modified header to ensure that the client does not refresh the object in browser cache through an IMS request.

Managing theOutput in Cache

The template and output files are differentiated in cache by default, but are both removed when the template page is purged through the Content Control Utility. Any event that forces a refresh of the template page will cause that page to be processed and generate a fresh output object. Thus, setting an invalidation time for the template will also effectively invalidate the output object. When its TTL expires, the DCA output is always deleted. There is no revalidation mechanism (IMS) for the


DCA Output CachingConfidential & Proprietary

cached output, only for the underlying template file.

If the output of DCA processing varies based on a characteristic of the client request (for example, presence of a cookie that specifies the user language), you will want to cache separate output files. You can do this by including the request attribute (the cookie value in this case) in the cache ID of the output file. This is mechanism is virtually identical to the Flexible Cache ID feature. See “Flexible Cache ID” on page 113. Of course, if the number of possible variations is very high, it is likely not worthwhile to cache all possible variations. Depending on the attributes being used, the Flexible Cache ID feature is flexible enough to allow for caching only the most popular variations and leaving the others uncacheable.

Integration Using DCA Output caching requires only that you:

• Identify the desired minimum and maximum TTL for the output file.

• Identify whether the output might vary based on characteristics of the client request, and provide the details needed to add these attributes to the cache-ID so that separate objects can be cached for the variations.





In This Chapter

Add, Pass, or Remove Head

Cloning HTTP Headers • 17

Forward Status Code Overri

Client Status Code Override

Custom Client IP Header •

Constructed Response • 17

Support for 100 Continue R

Support for WebDAV Reque

EdgeScape - Content Target

10
Edge Services - General
ers • 174

5

de • 176

• 177

178

9

esponses • 181

sts / Responses • 182

ing • 185

This chapter describes features of the Akamai server that primarily involve manipulation of HTTP headers (other than cookies)

Akamai servers can add or remove HTTP headers as they process the client request or origin server response. Many of these actions are performed by default, such as removal of Akamai Edge-Control headers before serving the response to the client. You can also instruct the Akamai server to perform some of these actions based on settings in the configuration file.

173

Chapter 10: Edge Services - General

Add, Pass, or Remove Headers

The Akamai server can add HTTP headers (standard or custom) to requests and responses or remove existing headers. The available manipulations are:

• Add, pass unaltered, or remove a header in the request from the client

• Add or remove a header in the request to the origin

• Add, pass unaltered, or remove a header in the response as received from the origin

• Add or remove a header in the response sent to the client

In each of the “add” operations you can specify the header name and value combination.

When the Akamai server processes instructions to add or remove headers, it always performs the removals before the additions so as to avoid removing a header that it just added.


Cloning HTTP HeadersConfidential & Proprietary

Cloning HTTP Headers

This feature allows the Akamai server to clone an HTTP header from the client and to rewrite the name of the header in the forward request. This does not allow for cloning headers in the direction of the client. Only headers known to the Akamai server can be rewritten.

For example, you could rewrite the header “Range” from the client request into “X-Range” in the request to the origin server as information for the origin to log or authorize, but not to use for the basis for the response. (The Akamai server generally requests the entire object, caches the entire object, and serves the client a Range response if a Range was requested.) In this example you would also remove the Range header, so that only one header was sent forward and the original header:

Range: bytes=1024-2047

would become

X-Range: bytes=1024-2047

The origin server would thus know which range the client had requested, but would respond to the Akamai server with the full object.



Forward Status Code Override

This feature overrides the status code from the origin server. This is used primarily for testing other features, but can be used for transforming responses in a production environment.

TechnicalDetails

This feature only overrides the value from the origin server and not the value loaded from cache. That is, the Akamai server must go forward for this feature to apply to the response. The Akamai server will cache the status code set by this feature rather than the one that came back from the origin server. As a practical matter this means that, to reliably change the status code served with an object that is already in cache, after this metadata has been enabled the object must be purged or invalidated (without the IMS option) to force a forward GET request for the object.

The status code from the origin server is overridden after forward-response stage metadata is applied. At client-response stage, the Akamai server can match on the value set with this tag.


Client Status Code OverrideConfidential & Proprietary

Client Status Code Override

This feature overrides the status code as the response to the client is constructed. The status code will be overridden regardless of whether the response was served from cache or from the origin server.

By default the status code override feature does not apply to a 206 response. You can cause it to apply to a 206 response with the additional metadata tag:

With this additional tag, you can override a 206 response with a 200 status code. The content served will be the requested range, with a content length matching the requested range length.

Overriding a 206 with a non-2xx status is generally a bad idea, because the client will always get some portion of the request content in the body.



Custom Client IP Header

This feature is used to declare the name of a custom header the Akamai server will use to pass the client IP address to the origin server.

This is done to better ensure that the information arrives at the origin server intact. Normally the client IP is passed in the X-Forwarded-For header. However, since this header is routinely modified by proxies, it is difficult to guarantee that what arrives at the origin server represents the correct value for the client IP.

Integration You can directly control whether the Akamai server includes the IP of the connecting client in a custom header when it forwards requests to the origin server. In Configuration Manager this feature is called “True Client IP Header” and is included among the “EdgeServices - General” features.


Constructed ResponseConfidential & Proprietary

Constructed Response

The Constructed Response feature lets you serve a short response to client requests from information in the configuration file. The primary advantage of this feature is that it allows for responding to the client without ever contacting the origin server where skipping that step is appropriate. This is very similar to serving a redirect response to the client (described in the next chapter), except that the response code, response headers, and message body are completely flexible. For example, you can use this feature to serve an HTTP Basic Auth challenge (401 Unauthorized) to any request that doesn’t include the Authorization header. This strategy could both reduce load on the origin server and improve performance for the end user.

In some cases you may wish to serve a Constructed Response conditional on the response from the origin server. This could be used as another mechanism for serving a custom error page or a redirect in the event the origin server cannot be reached. The primary advantage to this mechanism is that it provides for including a body with the redirect, which can be especially useful if the client doesn’t automatically follow redirects.

TechnicalDetails

To define a Constructed Response, you supply the status code and the message body in the configuration file where it would be used. For example, in the case of the Basic Auth challenge you would use a match condition to test for absence of the Authorization header in the client’s request. Within that condition, you would supply the status code and message body for the Constructed Response, and, as needed, you would add headers to the response.

The body of the constructed response is limited to 2K bytes of data. You can use extracted or built-in variables within the body definition in order to include elements of the client request (such as the request URL) or the origin response in the response body.

The constructed response is handled by the edge server as though the response had been received from the origin server. Thus, in the default case, the Akamai server will evict any underlying object in the cache when the feature is used. This is done because logically the object will never be served. There is a setting to control for allowing the underlying object to remain in cache if the generated response is conditional on some attribute of the request (such as lack of authorization headers).

An exception to treating the constructed response as though it came from the origin is the application of fail-action. A constructed response will take precedence over a fail-action setting when both apply to the same request/response. The assumption is that, if you defined a constructed response, that is the response you want to send. If you want to send a fail-action response for some HTTP status codes, you can restrict the constructed response so that it does not also apply to those status codes.

In the case where the Constructed Response feature is used conditional on origin response code and the response in cache is stale, the Akamai server will have to refresh the object before it can evaluate the response code condition and apply the feature.



This applies for negatively cached objects (errors) as well as normal responses. Depending on the error code being handled, you may want to increase the TTL for the negative response so that the Constructed Response can be served for a longer period before checking again with the origin server.

The feature currently applies only to GET requests due to the complexities of how to handle the POST body from the client and intermediate responses (100 Continue) from the origin server.

In addition to the metadata for defining the constructed response, there is a match condition to determine whether the response was constructed and thus apply metadata to the response based on that attribute.


Support for 100 Continue ResponsesConfidential & Proprietary

Support for 100 Continue Responses

When sending POST or PUT requests, some clients use the Expected: 100-continue request header, to which the origin response should be 100 Continue or a rejection of the request. The 100 Continue response is the signal to the client to continue sending the request.

Caveats For the 100 Continue behavior to work correctly, persistent connections must be supported in the configuration. This support must be between both client and Akamai and Akamai and origin. Otherwise, when the 100 Continue response is processed, the connection will close and the client will not be able to deliver the POST body to the Akamai server, or the Akamai server will not be able to deliver it to the origin.

TechnicalDetails

While most client browsers (IE, Mozilla) do not use the Expect: 100-continue request header when making a POST request. The Microsoft .NET framwork includes use of the Expect: 100-continue header by default.

In addition to the standard behavior of returning the origin’s 100 Continue response to the client, the Akamai server monitors a separate timeout for the receipt of this response. By default, if the origin does not respond with 100 Continue within five seconds, the Akamai server will send forward any POST body it has received from the client, as suggested by section 8.2.3 of the RFC. The length of this timeout is configurable.

As mentioned above, for the 100 Continue behavior to function correctly, the request headers and request body must be forwarded to the origin server across the same connection. Where the Akamai network is not present in the transaction, this is a trivial detail. However, the Akamai server maintains many connections with the origin server, and will normally reuse these connections as they become available. To ensure that the request headers and and body are sent on the same connection with the origin with no other transactions in between, the Akamai server reserves the connection as a "sticky" pconn to be reused only by the client that sent the Expect: 100-continue header. Until the request body has been sent to the origin, and the origin response has been delivered to the client, this forward connection is held in reserve. All of this is handled automatically without the need for any configuration other than to ensure that persistent connections are supported in both directions. The obvious side effect, however, is that the Akamai server may need to maintain additional connections to origin servers that handle many such POST or PUT transactions.

As of this writing, support for use of 100 Continue is currently "on" across the Akamai network. There is no need to enable the feature in individual customer configuration files. Discussion of tshe feature is included here for informational purposes only.



Support for WebDAV Requests / Responses

WebDAV stands for "Web-based Distributed Authoring and Versioning.” It is a set of extensions to the HTTP protocol that allows users to collaboratively edit and manage files on remote web servers. – (source: http://www.webdav.org)

By default the Akamai server will reject requests that use the methods defined by WebDAV. You can optionally configure the server to allow WebDAV requests and responses to be tunnelled between the client and the origin. Also, in the special case of PROPFIND requests, the response may be cached.

Caveats You cannot implement Remote Authorization in combination with WebDAV methods. Remote Authorization can be used only with GET and POST methods.

When support for WebDAV is enabled, it allows for use of a limited set of additional request methods, as described below. is critical that the client application not attempt to use any method that is not supported by the Akamai server, as those requests will be rejected.

TechnicalDescription

WedDAV defines the following seven methods as an extention to the HTTP specification:

PROPFIND - Used to retrieve properties, persisted as XML, from a resource. In some implementations, this mehod can also allow one to retrieve the collection structure (a.k.a. directory hierarchy) of a remote system.

PROPPATCH - Used to change and delete multiple properties on a resource in a single atomic act.

MKCOL - Used to create collections (a.k.a. directory)

COPY - Used to copy a resource from one URI to another

MOVE - Used to move a resource from one URI to another

LOCK - Used to put a lock on a resource; WebDAV supports both shared and exclusive locks

UNLOCK - To remove a lock from a resource

It further defines the following six status codes and response strings:

102 Processing - an interim response used to inform the client that the server has accepted the complete request, but has not yet completed it.

Akamai support: Proxied to the client; cache by-passed.

207 Multi-Status - The default 207 (Multi-Status) response body is a text/xml or application/xml HTTP entity that contains a single XML element called multistatus, which contains a set of XML elements called response which contain 200, 300, 400, and 500 series status codes generated during the method invocation.


Support for WebDAV Requests / ResponsesConfidential & Proprietary

422 Unprocessable Entity - the server understands the content type of the request entity (hence a 415 Unsupported Media Type status code is inappropriate), and the syntax of the request entity is correct (thus a 400 Bad Request status code is inappropriate) but was unable to process the contained instructions.

423 Locked - the source or destination resource of a method is locked.

424 Failed Dependency - the method could not be performed on the resource because the requested action depended on another action and that action failed.

507 Insufficient Storage - the method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request. This condition is considered to be temporary.

When you enable support for WebDAV methods and responses, the Akamai server allows these methods and tunnels them to the origin server using the same mechanisms it uses for a POST request (that is, not being cached or processed through ESI).

Other SupportedMethods

In addition to the defined WebDAV methods, PUT, DELETE, and OPTIONS methods are also automatically allowed (and tunneled to the origin server) when WebDAV support is enabled

If a customer intends to use the OPTIONS method, it is important that they understand the limited nature of this support. The OPTIONS method was added as part of Akamai’s WebDAV support in order to allow for use of frameworks that make the OPTIONS call but essentially throw away the result or invoke the special origin capabilities only with request methods that are automatically tunneled through to the origin server..

CachingPROPFINDResponses

You can optionally enable the caching of responses to PROPFIND requests. The cached responses are 207 (positive response) and 507 (negative response). The controls for caching allow for:

• Enabling caching in general, which will cache the positive response (207)

• Optionally caching negative responses (507) under the negative-ttl

CAUTION: Use of the OPTIONS method through a proxy or a surrogate server such as the Akamai edge server is not recommended. In using the OPTIONS method, the client is seeking to learn the capabilities of the server. When this exchange is through a proxy or surrogate, it is not clear which server should be responding to the client’s request. Akamai’s support eliminates this ambiguity by always passing the OPTIONS request to the origin and the origin’s response back to the client with no caching of the response. The origin server may well be capable of application level behaviors that the Akamai server cannot support. If the client issues a request to the Akamai server expecting behaviors that only the origin can provide, the requests will likely fail. The Akamai server must be configured to forward any such requests and responses without caching, just as the OPTIONS request itself was handled.



• Optionally including the Authorization header value in the cache-key for the response. This is useful for associating the response with a particular user.

PROPFINDResponse Cache

Key

When the Akamai server forms the cache key for a PROPFIND response, it adds a few elements the cache key. The cache key is a hash of the usual components plus:

• The Content-Length header value

• The Depth header value

• The entire entity body of the request (if any)

• The Authorization header value (if the header exists and metadata is configured to include this value)

Caution: Before enabling WebDav support, the Integration Consultant must ensure that the customer uses ONLY the supported methods listed in the Technical Details section of this document.


EdgeScape - Content TargetingConfidential & Proprietary

EdgeScape - Content Targeting

When EdgeScape is enabled, the Akamai server sends a special header to the origin server containing geographic and other information related to the requesting end-user client. The header will look something like the following, :

X-Akamai-Edgescape: georegion=1,country_code=reserved,region_code=reserved,city=reserved,dma=reserved,pmsa=reserved,msa=reserved,areacode=reserved,county=reserved,fips=reserved,lat=reserved,long=reserved,timezone=reserved,zip=reserved,continent=reserved,throughput=reserved,network=reserved,asnum=,network_type=reserved

In the example above most of the values have been obscured. The specification of the possible values for each field in the header can be found in the EdgeScape Users Guide.

ConditionalRequest Handling

In addition to forwarding the raw EdgeScape information to the origin server, the Akamai server can conditionally handle a request based on the EdgeScape data for the client IP. This is accomplished through use of the EdgeScape match condition. For example, you could configure the Akamai server to deny requests that originate from a particular geographic region.

<match:client.edgescape field="city" value="Pittsburgh"> <auth:acl.deny>edgescape</auth:acl.deny></match:client.edgescape>

Or, you could redirect requests based on the client IP country of origin to serve localized content to the user.

The client.edgescape condition also contains an attribute (use-headers) to control whether the edgescape data will consider an X-Forwarded-For header received from the client, or will ignore that header and rely solely on the IP address of the connecting client to determine locale.

EdgeScape withESI

For customers using Edge Side Includes, the EdgeScape information is passed to the ESI processor so that the decision of what information to include in the response can be made by ESI as it performs the assembly. For example, as ESI assembles the page, you could have it include the weather forecast or local sports scores based on the zip code of the client IP.

Integration Through Configuration Manager, you can directly control whether EdgeScape information is forwarded in requests from the Akamai server. In Configuration Manager the feature is called “Content Targeting” and included in the category “EdgeServices - General.”

The company, domain, and device_type fields are not available to the Akamai edge server, and thus are not included in the header sent forward to the origin server.





In This Chapter

Cookies Set by the Origin •

Generate Unique Cookies •

Set Explicit Cookie Via Conf

Expire Browser Cookies (Be

11
EdgeServices - Cookie Handling
189

191

iguration File • 193

ta) • 194

This chapter describes the mechanisms for cookies to be set by the Akamai server. It is possible to set three kinds of cookies:

Origin Cookies -- a cookie set by the origin server and passed through to the client by the Akamai server

Unique Cookie -- a cookie with a unique value assigned by the Akamai server as the request is handled

Explicit Cookie -- a cookie with a static value defined in the configuration files

The Unique Cookie and Explicit Cookie features are designed so that the Akamai server can set the cookie without the need to contact the origin server. Also, the configuration files can be written to first test for the presence or absence of a cookie, and only set a new one if it is necessary. These cookies can be set on any request (provided the Web site is not using an Akamai domain), regardless of whether the Akamai server contacted the origin before serving. This is significantly different from the default behavior when handling cookies set by the origin server.

Caveat

The Akamai server supports the Netscape cookie specification, which can be found at the following link:

http://home.netscape.com/newsref/std/cookie_spec.html

This specification is supported by virtually all browsers and web servers. There is also an RFC for cookies (RFC2109), but this RFC is not generally

187

Chapter 11: EdgeServices - Cookie Handling

supported by browsers and is not supported in the Akamai server.

Matching onCookies

Presence or absence of a cookie in the client request is one of the many conditions you can test for before applying features. (See “Client Cookies” in the chapter Conditions: Defining the Scope of Features.) This condition is often used in combination with setting Unique or Explicit cookies. It also provides a simple mechanism for controlling access to a test environment.


Cookies Set by the OriginConfidential & Proprietary

Cookies Set by the Origin

By default Akamai servers will set cookies sent by the origin server only if the response from the origin is synchronous with the request and the domain for the cookie has been CNAME’d or delegated to Akamai. That is, when the Akamai server receives the client request, it must go forward to the origin server (usually with an If-Modified-Since request) to have the cookie set in the response and the response is then served to the client, complete with the cookie. If an object is served to Akamai with a Set-Cookie header, and that object is then stored on disk, the header is stripped from the origin response before it is stored, so that no clients are inadvertently served the wrong Set-Cookie header.

If the objective is to have cookies set by the origin server, the usual approach is to enable the Zero-TTL feature to cause the Akamai server to go forward on each request. By combining this setting with Require Revalidation and a Set-Cookie policy of "connection", you can ensure that content is never served without a 200 OK or 304 Not Modified response from the origin server.

Passing OriginServer Cookies

to Browser

By default the Akamai server will pass Set-Cookie headers if either of the following conditions are true:

• the request domain is not an Akamai domain and the caching policy of the object is no-store, bypass-cache. (Thus, the content is synchronously transferred from the origin and never stored in cache.)

• it's an ESI include request.

The Akamai server will never pass Set-Cookie headers if the request domain is an Akamai domain. Provided the Set-Cookie is not for an Akamai domain, you can have Set-Cookie headers passed:

• whenever the Akamai server contacts the origin server for a request. (Set-Cookie policy of "connection."

• always, even if the headers are being served from cache. (Set-Cookie policy of "always.")

• never (Set-Cookie policy of "never.")

DomainRestrictions

An additional restriction on the setting of cookies by the origin is that the edge server will not set cookies for an Akamai domain. The reason is that the browser would submit these cookies to any content provider using Akamai’s service, and thus the cookies set by one content provider could be sent to another. This would compromise the security of the cookies.

RewritingSet-Cookie

Headers

You can instruct the Akamai server to rewrite the path or the domain of a Set-Cookie header so that a Set-Cookie sent from an Akamai domain in response to a request sent to a CNAME’d hostname can be returned as a Set-Cookie from the same CNAME’d hostname. Thus, the client will return the cookie only to the correct



domain and the security of the cookie is not compromised.

For example, a client request to www.example.com that is served by example.edgekey.net could have Set-Cookie headers sent from the example.edgekey.net origin and, rather than stripping the Set-Cookie headers, the Akamai server could be instructed to rewrite the domain in the headers to be .example.com. This is accomplished using the metadata tag:

Set-CookieHeaders in

POSTResponses

For POST requests, the Akamai server passes Set-Cookie response headers back to the client regardless of the max-age or no-store settings. You can disable this behavior in metadata so that Set-Cookie headers are not implicitly passed in a POST response.


Generate Unique CookiesConfidential & Proprietary

Generate Unique Cookies

Akamai servers can generate a unique cookie to send to the client based on settings in the configuration file.

The feature is generally configured such that the unique cookie is set only if it is not already present in the client request and client cookies are logged for each request. You may find this useful as a way to identify the number of unique users or analyze client sessions within a Web site.

Caveats Akamai can only set cookies for domains that have been CNAME'd or are a domain delegation.

If the request is nominated for ESI processing and both the template page and fragments set a cookie, the first response to the client will include multiple Set-Cookie headers with unique cookies. In most cases, the browser will retain only a single cookie to return on subsequent requests, so everything works as expected for subsequent requests, as those will contain a single unique cookie that is logged. However, the first hit will have skewed the number of unique users reflected in the logs by the number of extra cookies set. The work-around to this problem is to generate unique cookies in response to requests for only a single object and include that object as a fragment in all responses. This should cause the first hit to receive a single unique cookie, and subsequent hits would not set a new cookie if the unique cookie were set only when absent in requests.

TechnicalDetails

This feature makes it possible to set unique cookies based on settings in the configuration files. You can specify:

• Name of the cookie (defaults to "unique_id" if not specified)

• Path property of the cookie (optional; defaults to current path)

• Domain property of the cookie (optional; defaults to current domain)

• Secure connection requirement (optional; defaults to off )

• Expiration date/time of the cookie (optional; if not set, the cookie expires when the user closes the browser)

• Format of the cookie to be either Akamai or Apache (optional; if not set, the format is Akamai). The Akamai format is based on the Netscape cookie specification, which both Netscape and Microsoft Internet Explorer accept. You’ll find the cookie specification at:

http://wp.netscape.com/newsref/std/cookie_spec.html

Note: the Akamai server sends the Set-Cookie header to the client in the response to the first request, so the browser can only start sending it in the second request.

This feature is usually configured so that the cookie is only set if it is not already present.


http://wp.netscape.com/newsref/std/cookie_spec.html


The UniqueCookie Value

The value of the unique cookie will depend of the “format” specified for the cookie. The Akamai format (the default) generates the unique value using the Akamai method. The Apache format generates the unique value using the Apache method.

Akamai Format Value

The cookie's "value" is a unique identifier constructed by the Akamai server from the following fields:

• The Akamai server's IP address

• The current process ID

• The current time as seconds

• The decimal part of the current time

• A counter

The cookie's value will be based on the hex value of the binary representation of the above fields. The combination of these fields ensures that the cookies are always different.

Apache Format Value

The Apache format creates a cookie with the unique value computed using the Apache method. The value is computed from:

• The server’s IP address

• The current process ID

• Cookie generation time (in seconds since Unix epoch time - 10 digits)

• Cookie generation time milliseconds (the milliseconds part of the epoch time - 3 digits)

Example: Apache=63.116.109.10.114111027639937737


• Name of the cookie to be generated, if the format of the cookie is Akamai (defaults to "unique_id" if not specified for Akamai format; and always defaults to “Apache” for Apache format cookies.)

• The following parameters, or explicitly state that they are not to be defined





• Format of the cookie (optional; if not set, the default is Akamai)


Set Explicit Cookie Via Configuration FileConfidential & Proprietary

Set Explicit Cookie Via Configuration File

This feature instructs Akamai servers to set cookies on the client browser using static values set in the configuration file. Thus you can set a specific cookie value on the client browser without the need to contact the origin server.

Using this feature, you might set a pre-specified cookies to maintain the state of an end user, for example, to track if a user has already visited an article and then conduct a poll regarding that article later in the user’s session. The state could be maintained by setting a cookie: article1_viewed=yes, for every user who visits www.newssite.com/article1.html.

Caveats Akamai can only set cookies for domains that have been CNAME'd to Akamai or are a domain delegation.

TechnicalDetails

This feature instructs Akamai servers to set cookies on the client browser using static values set in the configuration file. You can use all of the usual mechanisms described in the beginning of this document to define when a cookie should be set. For example, you could set a cookie:

• If the cookie doesn't already exist

• If a particular file is requested

• If the request came with a particular Host header

The name, value and other parameters for the cookie are specified in the edge server configuration file. (See Integration below for a list of parameters.)

Note: the Akamai server sends the Set-Cookie header to the client in the response to the first request, so the browser can only start sending it back in the second request.


• Name of the cookie to be generated

• Value of the cookie to be generated

• The following parameters, or explicitly state that are not to be defined.







Expire Browser Cookies (Beta)

Normally any browser cookies that need to be expired would be expired by the origin server. In the rare case where the requests are not being forwarded to the origin server, and it is necessary to expire the browser cookies, you can do this through the edge server configuration file.

This involves listing the names of the cookies to be expired. The names can include the wildcard character (*) to match zero or more occurrences of any character in a non-greedy (minimal) way until the next character in the given cookie name is encountered. You can expire all submitted browser cookies by specifying simply “*” as the cookie name.

When a request includes cookies to be expired, the Akamai server sends a Set-Cookie header to set the cookie with the same name and value, but an expiration date of 1980. This will cause the cookies not to be submitted by the browser in future requests. Note that this does not remove the cookies from the cookie cache maintained by the browser; it simply prevents the cookies from being submitted.



In This Chapter

Redirect Chasing • 196

Generate Redirects Based o

Generate Redirects Based O

12
EdgeServices - Redirect Handling
n URL Marker • 198

n Configuration • 200

This chapter discusses features of the Akamai edge server related to handling redirects from the origin server and for generating redirects at the edge server.

You should also be aware of a somewhat related feature, Default Content. This feature can be used to serve a redirect to the client in the event the origin server cannot be reached. For a description of this, see the chapter Enhanced Availability.

Cacheability of Redirects

By default, Akamai edge servers will cache a 301 Moved Permanently response from the origin server using the same time-to-live that a 200 OK response would have received.

A 302 Moved Temporarily is cached depending on whether or not it contains a Cache-Control or Expires header. If neither of these headers is present in the response, the 302 is treated as uncacheable. If either of these headers is present, then the response is considered cacheable. Cacheable 302s receive the same time-to-live that a 200 OK response receives.

If the origin server does not send Cache-Control or Expires with a 302 response, you can make these responses cacheable through a setting in the edge server configuration file.

195

Chapter 12: EdgeServices - Redirect Handling

Redirect Chasing

By default, when the response from the origin server is an HTTP redirect to obtain a requested object, the Akamai server serves the redirect to the client and may cache it for response to future requests for the same object.

With Redirect Chasing enabled, the Akamai server can follow the redirect to obtain the object and serve it to the client. The object will then be stored in cache and served to future requests. This reduces the number of requests the client browser must make to obtain the object and thus improves performance for the end user.

Turning on Redirect Chasing is also useful for pages that receive ESI processing, since ESI cannot currently serve a redirect to the client. See the Technical Details section below for a brief explanation.

Caveats There are a few important caveats with respect to chasing redirects. Please read these carefully to ensure that this feature is appropriate or the content your Web site is serving.

• Akamai servers will only chase redirects that contain an absolute URL in the Location header (http://www.example.com/images/spiffy.gif ). They will not chase redirects where the Location is relative (/images/spiffy.gif ).

• The current implementation of Redirect Chasing does not work with directory names that don't include the trailing slash. If Redirect chasing is to be used across the entire site, you must be careful to include the trailing slash in references to directory names. When servers receive a request for /some/path they generally return a 302 redirect to /some/path/. This behavior is difficult to modify or prevent.

For example, if the reference is to /some/path and that reference is to a directory, the HTML should be /some/path/ (including the trailing slash). In this example, if the trailing slash is not included, Akamai servers may cache index.html from the /some/path/ directory as /some/path, and relative links in the page will not work correctly.

HTML documents should include a BASE HREF tag so that references from the document will not be broken.

If neither the trailing slash nor BASE HREF solution can be reliably implemented, Redirect Chasing should be limited by file extension. For example, you could still enable redirect chasing for all .zip, .gif, .jpg, .png, .exe files across the entire domain.

TechnicalDetails

Some further information regarding Akamai servers' default behavior with redirects:

When the Akamai server chases a redirect from the origin, it copies the headers from the original client request into the new request (based on the redirect) so that all appropriate authorization headers, cookies, and user agent information are available


Redirect ChasingConfidential & Proprietary

in the request.

Akamai servers will not chase a redirect if the protocol for the redirect does not match that of the client request. For example, if the client request was for https://www.example.com/ a redirect to http://www.example.com/index.html will be served to the client rather than chased. The same applies if the client request was HTTP and the redirect response was HTTPS. Any change in protocol is considered a potential security downgrade if the redirect is not served through to the client.

When a redirect is chased, the decision about how to cache the resulting object is deferred until the chase is complete. That is, cacheability is determined by the final response, not the intermediate responses. So, if the configuration file indicates that the object will be cacheable, and the final response after chasing redirects from the origin is a 200 OK, then the response is cached.

The maximum redirects the Akamai server will follow is currently seven (7). You can configure the Akamai server to serve a 404 response to the client if this limit is exceeded and the response from the origin is still a redirect. Otherwise the browser is served the final redirect to chase itself. Serving a 404 instead is useful in situations where this high number of redirects likely indicates an endless loop of redirects.

For ESI users, enabling Redirect Chasing for content nominated for ESI processing is recommended. Currently, ESI does not support generating an HTTP redirect (301 or 302) response to the client. It also does not support serving a redirect returned by a esi:include src or alt URL. If an esi:include src or alt URL returns an HTTP redirect, and Redirect Chasing is not enabled in your edge server configuration file, ESI will generate an error. With Redirect Chasing enabled, ESI will chase the redirect to obtain the object.

Redirected POSTRequests

The Akamai server does not chase redirects a redirect in response to a POST request by default. Instead, the default behavior, even with the basic Redirect Chasing feature enabled, is to serve the redirect to the client.

With the addition of POST Caching features, the Akamai server will chase a redirect with a new POST request to the Location: in the redirect response. This redirect POST will also contain the body of the original POST request.

Integration The Integration Consultant should submit a provisioning request that includes the basic required information. No additional information is required.



Generate Redirects Based on URL Marker

Akamai servers are able to generate redirects based on information in the URL. This is achieved by configuring a string to serve as the “redirect marker”. When the Akamai server encounters the tag in a URL, it serves the client a 302 redirect, and uses the portion of the URL that follows the redirect marker as the value of the Location header.

For example, an Internet search might generate a list of URL where the path portion is a link to the search site and the query string is the destination site for the search. Something like this:

http://www.searchsite.com/drst/5503/?http://www.library.yxwv.ca/utel/rp/authors/byron.html

In the absence of Akamai, an end user would click on the link and the search site would serve a redirect based on the query string portion of the URL.

With Akamai, you can have the edge server log the user request and serve the redirect, rather than forwarding it to the origin server. You do this by inserting a unique string in front of the redirect and configuring the edge server to look for that string in client requests. For example, if the Akamai server has been configured to generate redirects based on ARL's that contain the tag "url=", clicking on the following link

http://www.searchsite.com/drst/5503/?url=http://www.library.yxwv.ca/utel/rp/authors/byron.html

would cause the Akamai server to serve a 302 Redirect where the location header was the string that followed “url=”:

Location: http://www.library.yxwv.ca/utel/rp/authors/byron.html

If the URL doesn’t contain the redirect marker, it is served like a normal request. That is, the Akamai server will look for the object in cache, and if it is not found, it will forward the request to the origin server.

In the event that a request URL is configured to generate a redirect to the client both from a redirect marker in the URL and from an edge server configuration file setting, the configuration file setting takes precedence. See “Generate Redirects Based On Configuration” on page 200.

Integration The Integration Consultant should submit a provisioning request. In addition to the

In the example above, “url=” is defined as the tag to appear in an ARL or URL to indicate that the Akamai server should redirect to the URL that follows. You can define this redirect marker as anything you want, but it must be formed from legal HTTP characters and you should carefully consider the tag string to ensure that redirects are not inadvertently generated. Although the Generate Redirects feature can be easily applied to the entire origin server, you are encouraged to limit the scope of the request to the minimum necessary portion of the site.


Generate Redirects Based on URL MarkerConfidential & Proprietary

basic required information, the request should explicitly state the following:

• The tag that specifies the redirection URI

• A sample ARL including the tag in use



Generate Redirects Based On Configuration

Akamai servers can redirect requests based on information in the Web site’s edge server configuration file. Requests that contain a particular path are redirected to a different destination.

Caveat The matching system for comparing the prefix listed in the configuration files with the URL in the request is not case-sensitive.

TechnicalDetails

In some cases, Akamai servers need to support the redirection system of a Web site. For example, a company that changed its home page structure several times in the past may be redirecting many legacy links to other locations. This feature allows us to provide similar functionality without caching a potentially huge number of redirect objects. This is accomplished by specifying in the configuration file that URI's with a particular path component should be redirected to a different destination. For example:

www.example.com/electronics/

can now be redirected (through configuration files) to

www.us.example.com/retail/Electronics

By default Generate Redirects will cause the eviction of an object already in cache. So, for example, if http://www.example.com/goodies/precious.jpg is in cache and a redirect is defined in the configuration file to redirect this request to http://www.example.com/login.html, the precious.jpg file will be evicted from cache on the next request that is redirected. This may not be the desired effect if the redirect feature is being applied selectively. For example, if you are generating the redirect only when the client does not have the necessary cookie, you probably don’t want the underlying file evicted. In this case, the feature can be configured to not evict the originally requested file.

Redirects can be served with response status codes 301, 302, 303, or 307. The response message is not configurable; it will be the standard response message for the respective code. For example, a 301 status code serves a Moved Permanently message.


• The URL path to be redirected

• The URL path prefix to be applied

• A before and after URL example that demonstrates the desired result, to serve as a check that the described redirection will achieve the desired result


Generate Redirects Based On ConfigurationConfidential & Proprietary





In This Chapter

Support Compressed Conte

Last Mile Accelerator • 205

Chunked Encoding • 208

Prefetching • 210

13
Performance
nt • 204

The features in this chapter are primarily geared toward improving performance. That is, they reduce bandwidth usage, improve response times to end users, or reduce load on the origin server as their primary purpose.

203

Chapter 13: Performance

Support Compressed Content

Enabling this feature instructs Akamai servers to advertise support for compressed (gzipped) content. The Akamai server will accept gzipped content from the origin server and serve it to clients that accept gzipped content. If the client does not accept gzipped content, the Akamai server un-zips the content before serving.

TechnicalDetails

With this feature enabled, Akamai servers include the following header in requests to the origin to advertise support for gzipped content:

Accept-Encoding: gzip

If the origin server is configured to send content gzipped, it returns the content with the headers:

Vary: Accept-Encoding

Content-Encoding: gzip

Note: all of these headers are standard HTTP/1.1. Also note that this is the only case in which an Akamai server will cache content that includes a Vary header.

If the origin server sends content gzipped, Akamai servers cache it in gzipped form. Requests from clients that accept gzipped content are then served gzipped content. Netscape and IE both accept gzipped content and include the necessary headers in requests by default. If a client does not support gzipped content, the Akamai server unzips the content before serving it to that client.

If the origin server sends unzipped content, the Akamai server always stores and serves the content unzipped.

If the content is nominated for ESI processing and is also compressed, the Akamai server unzips it for ESI and then automatically re-gzips the result returned by ESI before serving the client. If the content should not be re-gzipped before serving, you can configure the server to store and serve ESI results unzipped.

Integration To take advantage of this feature, the origin servers must be configured to deliver gzipped content with Vary: Accept-Encoding and Content-Encoding: gzip headers in response to the Accept-Encoding: gzip header from Akamai.

In addition, the Integration Consultant should submit a provisioning request that includes the basic required information. No additional information is required.


Last Mile AcceleratorConfidential & Proprietary

Last Mile Accelerator

Last Mile Accelerator selectively compresses content before delivery to the end user. Compression of HTML in particular can provide for significant improvement in transfer times to clients on slow (modem) connections. Implementation of Last Mile Accelerator doesn’t require additional hardware or software at the origin. This solution is intended to assist in cases where the origin server cannot compress the content before serving, for whatever reason.

This feature can be enabled in combination with Support Compressed Content.

Caveats • This feature should be applied only to content that is known to compress well. In general, this means text-based files.

You should not use this feature to compress image files even if you expect that they will compress. There is also a known issue whereby Netscape 4.7 corrupts image files that have been compressed regardless of whether Akamai or the origin server applied the compression.

• When Last Mile Accelerator is first enabled, there may be a noticeable increase in traffic to the origin until edge server caches have been refreshed with compressed content. This is because client requests for content that is uncompressed in cache will cause the Akamai server to refresh that content with the origin. When this refresh occurs, the client request is first served from the uncompressed content in cache, and then the Akamai server sends a request to the origin for fresh content. The new content is then compressed and stored in cache.

• The Akamai server cannot serve an uncompressed Range response from a compressed object in cache. If the client does not support compression and requests a Range of bytes from an object that is compressed in cache, the Akamai server will respond with a 200 OK and the full uncompressed object. If serving the full object uncompressed is not an acceptable behavior, the content should be stored in cache uncompressed, so that it can be served in ranges. Note that this is never an issue for objects that use Partial Object Caching, because those objects are always stored uncompressed.

TechnicalDetails

Last Mile Accelerator causes the Akamai server to apply gzip compression to content received from the origin server either before it is cached, or before it is served to the client. In both cases, the goal is to serve the content to the browser in compressed form to speed the transfer time. The choice of where the compression should be applied is generally related to whether the content is cacheable or not.

The majority of browsers in use today support receiving compressed content and decompressing the content for display. This support is part of the HTTP/1.1 standard. Clients (browsers) usually advertise their support for compression in their requests for content by means of the HTTP header Accept-Encoding: gzip. This header is not necessary, and support for gzip compression is assumed, if the client sends the request advertizing HTTP/1.1 as the protocol. In the case of the few clients



that do not support compressed content, Akamai servers uncompress the content on the fly for delivery to the client in uncompressed form.

CompressingStatic (Cacheable)

Content

When Last Mile Accelerator is configured for static, cacheable content, the Akamai server compresses the objects as it receives them from the origin server, adds the appropriate Vary:Accept-Encoding and Content-Encoding:gzip headers, and stores the object compressed. This is done only to content that is not already compressed and is cacheable. Any content that is designated as no-store or bypass-cache is not compressed.

As with Support Compressed Content (described above), Akamai servers deliver the objects to the client in compressed form only if the client advertises Accept-Encoding:gzip in the request headers. Otherwise, the Akamai server unzips the content before serving.

CompressingDynamic

(Uncacheable)Content

When Last Mile Accelerator is configured for dynamic or otherwise uncacheable content, the Akamai server compresses the content just before it is served to the client and adds the appropriate Vary: Accept-Encoding and Content-Encoding: gzip headers. It compresses the content only if the client request included the Accept-Encoding: gzip header.

An obvious application of this feature is for content that is nominated for Edge Side Includes (ESI) processing. This content is text-based, so it compresses well, but the final, processed response generally cannot be cached, so compressing just before serving the client is appropriate.

ForcingUncompressed

Delivery

If you encounter browsers or specialized client software that advertizes support for compressed content, but fails to properly uncompress and display the content, you can instruct the Akamai server to serve these clients uncompressed content regardless of their advertized support for compression. The only requirement to do this is the ability to identify the client by its User-Agent header or some other identifying header in the client request.

As a best practice, Integration Consultents will include the necessary configuration to uncompress content for browsers that have already been identified as buggy with respect to compression.

Integration Before Last Mile Accelerator is enabled, it is important to address the following issues:

• The exact scope of the site to which the feature should apply. The content may be identified by directory, file extension, or some other method, but should be known to compress well.

• Whether the content is cacheable (static) or uncacheable (dynamic). This may not be obvious from the configuration file if the origin site is controlling cacheablility with Edge-Control or Cache-Control headers (if Honor Cache Control Headers is enabled).


Last Mile AcceleratorConfidential & Proprietary

• Whether there should be any exceptions made for particular clients. That is, whether any content should be forced to be served unzipped to particular browsers and how those should be identified.

You can directly control the Last Mile Accelerator settings for your content through Configuration Manager, where the feature is called "Last Mile Accelerator." Configuration Manager lets you apply the feature based on the content type of the response object. For example, you can apply the feature:

• only to HTML responses,

• to any responses with a character set declaration,

• to Javascript,

• to stylesheets,

• and to any custom configured content-type you input.

Last Mile Accelerator is automatically turned off for browsers that do not advertise support for compression, and for older browsers that advertise support, but fail to properly decompress.



Chunked Encoding

By default, an Akamai server advertises itself to the origin server as an HTTP/1.0 compliant server. However, it can advertise support for the chunked Transfer Encoding feature of HTTP/1.1.

This feature makes it possible to maintain a persistent connection for content that lacks a Content-Length header, as is sometimes the case with dynamically generated content.

TechnicalDetails

With this feature enabled, Akamai servers include the following header in requests to the origin server. (In addition, they advertise HTTP/1.1 as the HTTP version.)

TE: chunked;q=1.0

If the origin wants to send content using chunked encoding, it returns the content with the header:

Transfer-Encoding: chunked.

(Note: these headers are standard HTTP/1.1. Also, the Akamai server does not support, or advertise support for, trailers in chunked encoding.)

Serving content with transfer encoding is most commonly done when the server does not know the length of the content in advance (as is the case with dynamic content) and wishes to maintain the connection with the client. When an origin server delivers dynamic content to the Akamai server the content may be passed in one of two ways:

• If the client supports chunking, the Akamai server passes the response to the client. The client knows when the transfer is complete, because, as defined in the specification, the last chunk will have a size of zero. The connection is left open so that the client can submit a new request.

• If the client does not support chunking, the Akamai server buffers the response (up to 32K) before serving and does not use chunking for the response.

• If the full object is received within the 32K buffer, the Akamai server adds a Content-Length header and a Connection: Keep-Alive header to the response and serves the client. This allows the client to reuse the connection for the next request.

• If the full object is not received within the 32K buffer, the Akamai server begins serving the response without Content-Length or Connection: Keep-Alive. When the transfer is complete, it closes the connection. The

This feature is generally enabled by default in the direction of the client and in the direction of the origin server. That is, the Akamai server will by default use Chunked Encoding if the client supports it and it is appropriate, and it will advertise support for Chunked Encoding to the origin server unless this feature is explicitely disabled.


Chunked EncodingConfidential & Proprietary

client must establish a new connection for the next request.

In any case, if the content is cacheable, the Akamai server adds a Content-Length header when it stores the response. When served from cache to future requests, the response will contain a Content-Length header and Connection: Keep-Alive.

The Akamai server might also serve content from cache to the client using transfer encoding if the response was processed using Dynamic Content Assembly (for example, Edge Side Includes) or it was dynamically compressed from an uncompressed object in cache. In these cases, the Akamai server may not know the content length of the final response before it reaches the buffer limit and begins serving the client. If the client accepts chunking, the Akamai server will use chunking for the response. Otherwise, it will close the connection once the complete object is served.

Integration As mentioned above, this feature is enabled by default. There is currently no control in the Akamai EdgeControl Portal to disable the feature. If you believe that this feature should be disabled for some reason, please contact your Akamai team.

To control chunking with the origin server:



Prefetching

At the time of this writing, Prefetching is a feature of the Dynamic Site Accelerator and Web Application Accelerator solutions.

When Prefetching is enabled, the Akamai server retrieves images and scripts embedded in HTML content at the same time it serves the HTML to the browser rather than waiting for the browser request for these objects. This can significantly decrease the overall rendering time of the HTML page and improve the user experience of a Web site.

Prefetching can be applied to either cacheable or un-cacheable content. When Prefetching is used for cacheable content, and the object to be prefetched is already in cache, the object is moved from disk into memory so that it is ready to be served.

When used for uncacheable content, Prefetching causes the retrieved objects to be uniquely associated with the client browser request that triggered the prefetch so that these objects cannot be served to a different end user.

Prefetching can be combined with Tiered Distribution to further improve the speed of object delivery and to protect the origin server from bursts of prefetching requests. When Prefetching is used for cacheable content, you are strongly encouraged to configure Tiered Distribution for the content as well.

Request FlowWithout

Prefetching

Without Prefetching, the Akamai server requests content from the origin server (or a parent Akamai server) only when it receives a request for the content from an end client (browser). This means that images referenced by an HTML page are not retrieved until the end user’s browser has received and read the HTML and requested those images. The normal request flow looks like this:

1. Browser requests an HTML page from the Akamai server.

2. The Akamai server retrieves the HTML page from cache (or from the origin server if the page is not already in cache).

3. The Akamai server returns the HTML page to the browser.

4. The browser scans the HTML and requests the objects referenced by the HTML.

5. The Akamai server retrieves the images and other content from cache (or from the origin server if the objects are not already in cache).

6. The Akamai server returns the requested objects to the browser.

Request FlowWith Prefetching

When prefetching is enabled, the Akamai server actively scans the HTML page for embedded images and scripts and retrieves these objects before they are requested by the end-user’s browser. So the new request flow looks like this:

1. End-user client requests an HTML page from the Akamai server.

2. The Akamai server retrieves the HTML page from cache (or from the origin


PrefetchingConfidential & Proprietary

server if the page is not already in cache).

3. The Akamai server scans the HTML for referenced images and scripts at the same time it serves the page to the browser.

4. Overlapping in time, the following two things occur

• The Akamai server retrieves the referenced images and scripts from cache (or from the origin server if the objects are not already in cache).

• The client browser scans the HTML and requests the objects referenced by the HTML.

5. The Akamai server returns the requested objects to the client browser.

Caveats The following restrictions apply when determining whether to scan a response for prefetchable content or to prefetch a referenced object:

• By default, the Akamai server will apply Prefetching only to responses with a Content-Type header that begins with text/html. (This option is configurable in the event that you need to parse responses that are served with a different content type.)

• By default, the response is scanned for prefetchable objects only if the status code sent to the client will be 200 or 404. You can extend this to include 304 responses to clients; in which case the underlying response object is scanned. You can also optionally prefetch the URL in the Location: header of a redirect (301, 302, 307) response.

• URL’s inside JavaScript are not prefetched. If the JavaScript section contains a properly formatted HTML tag that references a URL, the URL will be prefetched.

• Objects to be prefetched must be referenced using the same protocol (HTTP or HTTPS) as the HTML page. If the protocol in the reference does not match, the object is not prefetched.

• Embedded object references must use the same hostname as the original request or they are not prefetched. It is possible to loosen this restriction to require only that the two requests use the same map of Akamai servers (for example, if both request hostnames were CNAMEd to a27.g.akamai.net, the objects could be prefetched). [Ask about whether base HREF resets the hostname for this purpose.]

ContentProvider

Integration

Akamai integration consultants will work with customer provisioning to identify the appropriate context for prefetching. Before concluding a prefetching configuration, steps should be taken to ensure that:



• The Content-Type header is properly set to contain "text/html" for all content that should be scanned for prefetching, or the Akamai configuration has been modified to allow for the needed content types.

• Cookies needed for successful prefetch requests are not set through JavaScript.



In This Chapter

General Forward Connectio

Host Header Modification

Origin Server Assignment •

Tiered Distribution • 219

SureRoute for Performance

Site Shield • 222

14
Forward Server
n Settings • 214

• 217

218

• 220

Whenever an Akamai server needs to revalidate the freshness of objects but cannot reach the origin server to do so, the Akamai server’s default behavior is to serve these potentially stale objects from cache. This approach helps ensure that the end user receives content rather than an error code, and is particularly helpful in cases where the origin server is unreachable for only a brief period of time.

If content should never be served stale, even in the event that the origin server is unreachable, the Require Revalidation feature should be turned on. In this case, the Akamai server would serve the error code to the client until it could revalidate the content with the origin server.

This chapter discusses features designed to enhance the availability of a Web site to end users. These features provide alternatives to serving a standard error code to the client and ways to tune the Akamai server’s ability to determine that the origin server is not responding.

213

Chapter 14: Forward Server

General Forward Connection Settings

There are several metadata tags for controlling the connection to the forward server. This section provids a quick overview of how the forward connection is established, and then lists the most relevant of the controls for configuring individual customer accounts.

Establishing aConnection

When the Akamai edge server needs to retrieve or refresh content, it will take the following steps:

1. Determine the origin hostname for the forward request.

2. Create the Forward Server List

This is a listing of which servers should be contacted in the process of retrieving the content. The servers included in the list will vary depending on whether the content is cacheable or uncacheable (ICP is not used for uncacheable content) and whether any form of cache hierarchy (Tiered Distribution or SureRoute) is enabled for this content. In the simplest case of cacheable content and no cache hierarchy, the Akamai server will first send an ICP query request to determine whether it can retrieve content from a peer. If it cannot obtain the content from a peer, it will contact the origin server directly.

3. Contact the servers in the list in turn until a connection is established and a positive response received, or until the maximum allowed reconnects or retries is reached.

Establishing a connection to the origin server is a multi-step process that looks something like this:

a. Check for an idle persistent connection to the origin hostname and use it if one exists. (The assumption is that this connection will be good and the request will succeed, though in some cases it will not, because the origin or some other device has timed out the connection without informing the edge server.) Skip down to step 4.

b. If there is no idle persistent connection, obtain an IP address from the ipcache. (The ipcache will round-robin IPs as it hands them out, so, if the origin hostname resolution returned multiple addresses, it is possible for each connection attempt to use a different IP address.)

c. Attempt to connect on the given IP. If the connection is not established within the connect-timeout (defaults to 5s), terminate the connection attempt and continue to step d). If the connection succeeds continue to step 4).

d. Check whether max-reconnects has been reached. (Default setting is 3.) If max-reconnects has not been reached, increment it and return to step a). If max-reconnects has been reached, continue to step e).

e. Generate a connect-timeout error for the end-client. Continue to step 5.


General Forward Connection SettingsConfidential & Proprietary

4. If the connection was established, and a positive response received, the cache is refreshed and the response is served to the client. Go to step 6.

5. If the connection attempt failed, but the content is stale in cache and the Akamai server is permitted to serve stale, it will mark the object fresh and serve the client. If the server is not permitted to serve stale, it will check to see if a fail-action is configured for this error and take the configured fail-action. If neither serving stale nor fail-action is possible, it will serve the error to the client.

6. The connection to the forward server is returned to the connection pool for reuse.

Reconnects When the Akamai edge server fails to connect to the origin server, it will generally retry the connection some configured number of times. The default configuration is for three (3) reconnects. This means that the Akamai server will attempt the connection a total of four times. You can change the number of connection attempts to suit the needs of the Web site. Most commonly this number is reduced to provide the fastest possible response to the client where response time is considered the most important factor in the end-user experience.

There is also a separate metadata tag to control the number of reconnects to a cache hierarchy parent. The default behavior is to attempt the connection to the parent only once. However, under some circumstances, such as a SiteShield configuration, you may want to try the connection a few times.

Retry on Error By default, when an Akamai edge server receives an error status response (403 Fobidden or 504 Gateway Timeout) from a peer, it can identify whether the response originated at the origin or at the peer and take the appropriate action. If the error was generated by the origin, the edge server will not reforward the request directly to the origin, but instead it accepts the response as authoritative.

You can alter this behavior to have the edge server forward the request directly to the origin server, though there generally is no benefit to doing so.

Pass RequestID

You can instruct the Akamai server to send its request ID (a unique number assigned to a client request) to the origin server in the X-Akamai-Request-ID header. This is sometimes useful when debugging behaviors that require tracing a request through from client to origin. By default, this flag is off.



Host Header Modification

The Host header is not directly related to the decision of where to send the forward request. However, modification of the host header may be important to how the origin server handles the request.

By default, Akamai edge servers send the origin server a Host header with the hostname of the origin server. For example, if the edge server configuration file defines the origin server as origin.example.com, the Host header will read “Host: origin.example.com” though the client request may have been to www.example.com.

You can specify a particular host header to use when going forward to the origin server, or you can instruct the edge server to use the Host header from the client request when going forward to the origin server.

Host in OriginRedirects

One reason to use the client’s Host header is that some servers use this header to form the redirect when they redirect a request that was for a directory and did not include the final shash (/). If the Akamai server goes forward with origin.example.com in the Host header, the redirect returned by the origin may be to origin.example.com. For example, if the end client sent a request for:

www.example.com/pages

and “pages” is a directory, the origin server may use the Host header to send a redirect to

Location: origin.example.com/pages/

This would both expose the true origin server to the client and cause the next client request to go straight to the origin rather than to an Akamai server.


Origin Server AssignmentConfidential & Proprietary

Origin Server Assignment

The tags described in this section control the decision of which server and port the Akamai edge server should address when forwarding a request.

Origin Server The origin-server metadata is used to specify the origin server to which the request is sent.

When the configuration file for a site is established, the normal structure calls for the hostname or ARL Token in the client request to be mapped to a specific origin server. However, you can make this assignment based on characteristics other than Host header or ARL Token.

When you change the origin server used in the forward request, this change applies both to the DNS lookup and to the cache key used to cache the response.

Forward DNSName

As an alternative to changing the origin server used in the forward request, you can change the domain used in the DNS resolution without changing the origin server used in the cache key. This makes it possible to request the same objects from multiple servers, and cache the responses under a single cache key. The common use for this is to maintain stickiness between a client and a particular origin server in a server farm that does not share the session object among the servers. The forward DNS name option is also able to use the variable from an Extract Value function. By combining the two features, it’s possible to base the DNS lookup on a client cookie so that every request is consistently sent to the same origin server, and the origin server controls this setting in real time.



Tiered Distribution

Tiered Distribution instructs Akamai servers at the edge of the Internet to fetch content from a parent Akamai server within a core region. Then only the parent servers fetch content from the origin server.

The core region servers leverage Akamai's existing mapping technology to map regions of Akamai servers near the edge of the network to clusters of Akamai servers co-located in large hosting data centers in the well-connected "core" of the Internet Web hosting infrastructure. By funneling edge requests through this smaller subset of regions, Akamai can significantly reduce the amount of traffic on origin servers, and exploit server-to-server optimizations, such as persistent connections.

In short, the direct benefits of Tiered Distribution include:

• Additional flash crowd protection

• Reduced load on the customer's infrastructure due to ability to efficiently offload file download requests to Akamai network

• Reduced bandwidth provisioning at the origin server due to fewer requests back to origin.

• Effective use of persistent connections to the origin server (due to fewer number of servers to which the origin site must connect -> 20 tiered distribution regions versus hundreds of edge regions).

• Improved performance, reliability, and scalability of a customer’s Web site.

Caveats Tiered Distribution is intended to reduce traffic to origin servers for very popular content and large, potentially flash-popular objects. It is not intended for use on all content in general.



SureRoute for PerformanceConfidential & Proprietary

SureRoute for Performance

SureRoute for Performance identifies alternate paths from the Akamai edge server to the origin server and uses the route that provides the optimal performance under current conditions to improve the performance of content delivery.

TechnicalDetails

When an Akamai edge server contacts the origin server, the "direct" route is the route obtained through BGP (Border Gateway Protocol). When SureRoute is used, alternate routes to the origin server are accessed by sending the request from the Akamai edge server to another Akamai server before going to the origin. While one might assume that adding the intermediate step would reduce performance, it frequently improves performance, because Akamai servers are well connected, and the indirect route can bypass network congestion.

Figure 2. SureRoute for Performance

Each Akamai edge server is configured with at least two alternate routes to use in addition to the direct route to the origin. These intermediate servers are specific to each Akamai edge server and origin server to be contacted. Also, the intermediate servers listed in the configuration are updated frequently based on the current performance of connections between Akamai servers.

The Akamai edge servers use occasional "races" among identical requests to determine which of the three possible routes is performing the best and then choose the route to use when going forward for the current and future requests. The parameters for these races are highly configurable to optimize the performance for the type of content being served and the intended result.

Who Should UseSureRoute?

SureRoute is appropriate for any customer seeking to optimize performance in content delivery and for many customers interested in improved reliability.

The performance benefit is greatest when the connection from Akamai edge server to origin is frequent, since this is the transfer that SureRoute optimizes. This applies regardless of whether the connection is used to transfer an entire file or an If-Modified-Since request to revalidate content or authorize a request before serving the client. Specifically, any content that uses one of the following features or settings



is a good candidate for SureRoute for Performance:

• Centralized Authorization

• No-store or bypass-cache

• Zero-TTL or low TTL settings

Customer Impact It isn't necessary to modify a Web site to take advantage of SureRoute, though, as a practical matter some changes may be required to address the following circumstances:

• We recommend the use of test objects for SureRoute races. This may require placement of a specific test object on the origin servers.

• If request object races are used, it might be necessary to configure the origin site to recognize the Akamai Race Identifier header and thereby ignore the duplicated requests for purposes of back-end processing (shopping carts, etc.).

• If the site does not permit pinging the origin, SureRoute will not be able to update the map with current performance data, and overall performance would likely improve with this data. If pinging can be allowed, it should be.

SureRoute will increase bandwidth usage by a small percent. This is a natural result of testing the current performance of the alternate routes. However, these increases in bandwidth use are very small and generally well worth the improvement in performance.

Integration The Integration Consultant will perform a thorough site review to ensure that SureRoute for Performance is appropriate for the content being served and the Web site’s existing configuration. This review will then be used to prepare the necessary configuration request. In most cases, no changes to the Web site are necessary to enable SureRoute for Performance.


Site ShieldConfidential & Proprietary

Site Shield

Akamai Site Shield is the industry’s first and only solution for “cloaking” a Web site from the public Internet while still ensuring that content is delivered quickly and without fail, regardless of user location.

A Site Shield is a collection of Akamai server regions designed to complement the existing infrastructure protecting the origin site. The Site Shield resides near the origin data center, whether that data center is a company’s premises, a dedicated facility, or a co-location facility. These servers operate the same proprietary software that is the foundation of the globally distributed Akamai platform. Site Shield benefits from the same local and global load balancing, performance monitoring and traffic optimization. Coupled to the global Akamai platform, Site Shield creates a layer of protection that works with existing origin site infrastructure to absorb external traffic surges and block attacks.

The features of Site Shield include, among others:

Origin Masking: Through use of customer specific metadata, an origin site can be setup with an unknown name to protect against attacks. This reduces the chance of attackers reaching origin infrastructure.

Port Masking: The Akamai network can be configured to communicate with the origin server on ports other than standard HTTP or HTTPS ports in a manner invisible to end-users. This provides additional protection from standard “scan” based attacks.

Minimum Access: All non-essential IP services are disabled on Site Shield servers (including FTP, telnet and rlogin.) The only remote access permitted is via encrypted and authenticated connections using RSA public key. No physical connections (keyboard, port monitors, etc) are allowed with Akamai servers.

Watch Dog: Each server continuously monitors its performance and feeds reports of anomalies to the Akamai NOCC. If necessary, a region can be suspended,



reconfigured and brought back on line.

Managed Service: The Akamai Information Security department actively monitors CERT, Bugtraq, Security Focus and other industry and federal groups to stay ahead of threats.

For a somewhat more detailed description of the Site Shield offering, see the document Site Shield Service Description, which is available on the Akamai customer portal at https://control.akamai.com/.

Caveats There are some known issues with the implementation of Site Shield using the current version of the Akamai server.

Client-OriginStickiness

Stickiness between a client IP and a physical origin server may present a problem when any limited cache hierarchy configuration (like Site Shield) is used.

If the Web site has more than one origin server behind a load balancer, and the load balancer is configured to use "stickiness" (consistently map a client IP to the same physical server), a single region hierarchy may cause all requests to map to one physical origin server, because all the requests will be coming from a limited set of request IP's -- the IP’s of the Site Shield regions.

Integration Site Shield involves defining a hierarchy map of Akamai server regions near the origin servers through which all requests are routed, so that the origin can be protected from contact with Internet traffic coming from any sources other than the Akamai servers.

Your Integration Consultant will work closely with you during the multi-step process of configuring Site Shield. This process includes the following:

1. Complete discovery of the customers network architecture. The "Akamai Site Shield Discovery Document" is available on the Akamai customer portal at https://control.akamai.com/

2. Complete Akamai edge server integration for the Web site. (The Akamai edge server integration is always fully implemented first to ensure that Site Shield integration issues do not overlap with standard edge server issues.)

3. Assignment of a SiteShield map to handle the customer traffic.

4. Configuration of Site Shield metadata within the content provider’s edge server configuration file.

5. Configuration of the IP ACLs at the origin site to block all non-Akamai Site Shield traffic from reaching the origin.

See the cache.log file for debugging output.


Site ShieldConfidential & Proprietary





In This Chapter

Prune or Modify Query Strin

Path Modification By Rule

Path Modification by Regul

15
Forward Path
g • 226

• 227

ar Expression • 228

By default the Akamai server will retrieve objects from the origin server using the same URL and query string that was included in the client request. There are some cases where it is helpful or necessary to alter the path before forwarding the request. Usually this is because the request is being forwarded to a server other than the origin server. For example, if objects are being served from Network Storage, the path is modified to include the content provider code under which the content is stored.

This chapter describes the mechanisms available for modifying the URL before fowarding the request.

Note that these modifications are applied only when the request is forwarded to the origin server. Or, more correctly, they are not applied when the request is forwarded to another Akamai edge server.

225

Chapter 15: Forward Path

Prune or Modify Query String

The Akamai edge server can remove or modify the query string from the request before forwarding it. Normally the origin server wants to see the query string because it contains some useful information. However, there are at least two cases where the query string may contain information the forward server can’t process or should not see:

• If the origin server doesn’t respond to the forward request, and alternate data is being fetched from a backup location, such as NetStorage, it might be necessary to remove the query string from the request URL, since the backup site may not know how to deal with the query string.

• If the client request will be handled by multiple forward servers (for example, by an authorization server and then a content server), it may be that the query string contains information relevant only to the authorization server. In this case it might be necessary to remove the client-specific authorization information from the query string before forwarding the request to the content server.

In the first case, the client request URL might look like the following:

/tables/dining/productsearch.asp?product=abc&color=blue

If the origin server doesn’t respond to this request, the alternative may be to serve a generic version of the search results for dining tables by sending a request to an alternate location for only:

/tables/dining/pruductsearch.asp.

In the second case, the client request might contain a client-specific string for authorization purposes

/tables/dining/productsearch.asp?product=abc&color=blue&user=a1b2c3d4e5

Once the authorization server (or other request processing server) has inspected the "user" query argument, you may wish to remove this argument from the request that is forwarded to the content server, so that the content request is only:

/tables/dining/productsearch.asp?product=abc&color=blue


Path Modification By RuleConfidential & Proprietary

Path Modification By Rule

You can instruct the edge server to rewrite the forward path when it makes a request to the origin server. You can use this to insert or remove path components from the forward request. For example, you could have the edge server rewrite all requests to insert an additional path component in the forward request:

/dir1/dir2/file.htm

might become

/newdir/dir1/dir2/file.htm

If necessary, you can also have the rewrite of the forward path include a rewrite of the filename so that the rewrite is to an absolute path. For example:

/dir1/dir2/file.htm

might become

/newdir/dir1/dir2/login.htm

You can turn off the rewrite in a subdirectory by specifying that the path should be rewritten to the same string as the original URL for that subdirectory.

Note that this feature cannot be applied to standard FreeFlow ARL’s, that is, ARL’s that include a typecode. Also, the cache key for the request is based on the rewritten URL.


Chapter 15: Forward Path

Path Modification by Regular Expression

You can use simplified regular expression matching and substitution to modify the URL path in the client request before the request is forwarded to the origin server. And, you can chain multiple substitutions to perform a complex rewrite of the original URL. Note, however, that the feature does not allow for back-referencing.

When Tiered Distribution is used, the modification is performed only by the server that connects to the origin server.



In This Chapter

DNS • 230

HTTP • 231

ICP • 232

Persistent Connections (pco

TCP Optimizations • 235

Timeouts • 237

Adaptive Connect Timeout

Client-Side Traffic Shaping (

16
Network
nns) • 233

(Beta) • 238

Beta) • 240

This section lists metadata for controlling the establishment and maintenance of a connection between the Akamai edge server and another server or client. It also contains some controls related to the protocols used to deliver content.

229

Chapter 16: Network

DNS

The Akamai server provides several options for controling the freshness of DNS entries and whether thos entries are refreshed synchonously (before serving the client) or asynchronously (independent of serving the client).

DynamicallyPre-freshing

DNS

When this feature is "on", the Akamai server will proactively refresh a DNS name even if it didn't receive a client request for the hostname.

The prefresh occurs after a configured period of time beyond the DNS expiration. This period defaults to five minutes.

A second configurable period marks the point at which the Akamai server will cease prefreshing the DNS entries if there have been no requests to that domain name. This period defaults to two hours.

AsynchronousDNS Refresh

This feature causes the Akamai server to refresh an expired DNS name after serving a client request. You can also set the point after which the Akamai server will perform a synchronous refresh to prevent the server from using a DNS resolution that is unacceptably past the required refresh time.

Minimum DNSTime-to-Live

This setting controls the minimum time for which the Akamai edge server will cache a DNS resolution.

DNS ErrorTime-to-Live

This setting controls the time for which DNS errors are cached.

Configuration Manager Support: If it is included in your contracted solution and features, you can directly control this feature through Configuration Manager where the feature is called "DNS - Prefresh."

Configuration Manager Support: You can directly control this feature through Configuration Manager on the Akamai Portal. In the Configuration Manager the feature is called "DNS - Refresh."


HTTPConfidential & Proprietary

HTTP

This section describes features for controlling aspects of the HTTP protocol, such as which version of the protocol the Akamai server advertises to the client.

HTTP Version By default the Akamai server advertises itself as an HTTP/1.0 server in its response to the client. You can instruct the server to advertise HTTP/1.1 as appropriate for the client request, or to pass through the protocol advertised by the origin server.

UnbufferingResponses

If there is no Content-Length header in the origin response, the Akamai server will buffer the response until it receive the end of the response or 32K of the response body (if the object is larger than 32K). This is done to avoid having to serve content to the client without the Content-Length header. (If the client does not support transfer encoding (chunking), and the Content-Length is not known, the Akamai server would need to close the connection with the client to signal the end of the transfer, and the performance benefit of persistent connections would be lost.) You can change this behavior so that the server more readily serves without buffering.


Chapter 16: Network

ICP

This section describes controls for managing ICP (Inter-cache Protocol) communication between Akamai servers.

no-sibling-icp This tag is for Akamai internal use only.


Persistent Connections (pconns)Confidential & Proprietary

Persistent Connections (pconns)

This section describes controls for managing use of persistent connections by the Akamai server.

PconnTimeouts

In general, the Akamai server will maintain and reuse a persistent connection for as long as the origin server will allow it. And, when a new request arrives, the Akamai server will look first to see if it has an available persistent connection to reuse before it establishes a new connection with the origin server. However, it will not wait for a persistent connection to become free; it will immediately establish as many new connections to the origin server as are necessary to serve the request load.

Idle persistent connections are reused on a last-in-first-out basis, so the most recently idle connection is used first. This allows unneeded pconns to timeout through lack of use, and thus ensures that we don't waste connections, because the Akamai server is trying to maintain connections to many different origin servers and needs to have connections available.

An idle connection will timeout once the controlling timeout setting has been reached. In addition to the global default setting of 300 seconds, the timeout setting for origin and client connections can be configured separately for each customer.

It is important that the Akamai server’s timeout setting for connections with the origin server is shorter than the time allowed by the origin. If the origin server times out the connection before the Akamai server does so, the Akamai server may attempt to forward a request to the origin on the connection only to discover that the it is no longer live. In the case of a GET request, this failed request will likely go unnoticed, because it will be retried on a new connection. However, the performance penalty is unnecessary with proper configuration. Other request types (such as POST) may result in errors to the end user, because these requests are not retried by default.

In addition to the timeout for an idle connection, it is possible to set a maximum lifetime for the origin connections even when they are active. Two cases for which this feature was desired were:

• the origin needed the ability to gradually adjust load among many servers behind a load balancer. Setting a maximum connection lifetime allowed for taking an origin server out of rotation without the need to abruptly terminate existing, active connections from Akamai servers. (Without the maximum lifetime setting, the active Akamai server connections would never close on their own.)

• the origin server wanted to enforce that SSL connections had a limited lifetime so that it could ensure continuing security of the connections.

Configuration Manager Support: You can directly control the timeout setting for idle persistent connections between the Akamai server and the origin server through Configuration Manager on the Akamai Portal. In the Configuration Manager the feature is called "Edge to Origin PCONN Timeout."


Chapter 16: Network

PreventingClient Pconns

In some rare circumstances, you may need to disable persistent connections with the client entirely. This can be accomplished through a simple configuration setting.

Note that to use this setting correctly, it should be applied based on the client/connection properties (User-Agent, for example) and not on properties of the request (like filename or extension). This setting can prevent a persistent connection from being established only if it is applied consistently to all communication with the client. If it is applied only to selected request types (like .pdf files) it is likely that a different request (for example, for .html) will establish a pconn and the client will reuse that pconn for a request that you wanted to prevent from using pconns.

PreventingForward Pconn

As with client connections, there are some rare instances where it may be necessary to prevent reuse of connections with the origin server. This can be accomplished through a simple configuration setting. However, persistent connections should be prevented only as a last resort, as the performance penalty of establishing a connection for each request is significant. This is especially true of SSL connections.


TCP OptimizationsConfidential & Proprietary

TCP Optimizations

The Akamai server provides controls that can be used to optimize TCP connections. These controls are used as part of the Dynamic Site Accelerator and Web Application Accelerator solutions to improve overall performance. They can be used to:

• adjust send or receive buffer sizes

• optimize the connection between the Akamai server and its peers, end-user client, or the origin server.

• disable the no-delay behavior when sending POST data forward

TCP BufferSizes

There are separate metadata tags for configuring the send buffer or receive buffer sizes when communicating with another Akamai server or an origin server. Each tag has a corresponding default setting in the server configuration files. These settings are available for use in edge server configuration files primarily in the event it becomes necessary to limit the size of the TCP buffer when talking to a particular origin server.

TransportOptimization

In addition to adjusting the raw send and receive buffer sizes as described above, it is possible to adjust the TCP parameters to optimize the connection between the Akamai server and its client or any forward server. There are controls to all of the following TCP settings:

• Retransmission Timeout

• initial

• maximum

• minimum

• Congestion Window Size

• initial window

• slow start increase

• congestion avoidance rate

• congestion reduction rate

• congestion window after loss

• application minimum congestion window

• minimum idle congestion window

• maximum burst

• congestion window validation factor

• slow start threshold congestion window validation factor

• slow start threshold decay factor

• Packet Loss Detection

• Reordering initial value


Chapter 16: Network

• Reordering max value

For a discussion of how these settings are used in the world and background regarding TCP in general, see the following RFC’s:

http://www.faqs.org/rfcs/rfc2001.html



forward-no-delay

This tag can be used to disable the Akamai server behavior of sending the body packets of a POST request immediately after the headers without an intervening delay. This lack of delay in has been known to cause problems for a very few load balancers, because the Akamai server is so much faster than most clients.

When you set this tag to “off,” there will be a longer delay between the sending of header packets for the request and body packets.

<network:tcp.forward-no-delay>off</network:tcp.forward-no-delay>


TimeoutsConfidential & Proprietary

Timeouts

Client Timeout

This sets a timeout for aborting the forward request and serving the client an error (or Default Content). This timeout applies to the period between the Akamai server receiving the client request (and applying metadata) and returning the first byte of the response to the client.

This timeout was added to allow for more direct control of the length of delay the client experiences before the Akamai server takes a default action. Notice that the Akamai server does not normally serve stale content based on this timeout, it can serve an error or take a default action. As of server version 5.0.2, you can configure a default action to serve stale content. To facilitate this, version 5.0.2 also provided a match condition to test whether the Client Timeout had been triggered, so that stale content can be served only under this condition.

When the client-timeout is triggered, the fail-action is taken and the forward connection is terminated without waiting for the response from the origin. If the object was stale in cache, the original entry is not modified in any way. Specifically, the object's time-stamp is not updated based on this request, since we terminated the forward request.


Chapter 16: Network

Adaptive Connect Timeout (Beta)

When the Adaptive Connect Timeout feature is used, each individual Akamai server dynamically recalculates the appropriate connect timeout to an origin server IP:port based on previous successful and failed connection attempts.

In the absense of this feature, the standard connect timeout is a fixed number of seconds. The setting can be different for each origin server, but it does not adjust to current origin server conditions, so it is generally relatively long (defaults to five seconds), and the setting is the same for all Akamai servers, regardless of their success in connecting to the origin.

This feature is independent of Monitor Origin Server (origin-health-detect) and the two can work separately or together.

TechnicalDetails

When an Akamai edge server connects to an origin server:port combination for the first time it uses the value of the standard connect timeout metadata. After a specified number of consecutive connection successes, the edge server will decrease the connect timeout by a set amount. It will continue to decrease the connect timeout for each series of successful connections until it reaches the minimum allowed connect timeout for this origin server. You use metadata to specify the following values for the edge server to use:

• the number of successful connections before decreasing the connect timeout

• amount of decrease

• the minimum connect timeout.

Similarly, each time an Akamai edge server experiences a series of consecutive connection timeouts, it will increase the connect-timeout by a set amount. It will continue to increase the connect timeout for each series of consecutive timeouts until it reaches the maximum allowed connect timeout for this origin server. Also, once the connect timeout has been increased, it won’t be decreased for a specified number of seconds without any connection timeouts. This helps prevent ocillation in the settings. You use metadata to specify the following values for the edge server to use:

• the number of connection timeouts before increasing the connect timeout setting

• the amount of increase

• the number of seconds during which the connect timeout cannot be decrease after an increase

• the maximum connect timeout

Note that these dynamic connect-timeout calculations are performed on each edge server individually and none of the servers will know what another server’s setting is. When an edge server is shut down or it crashes, it will lose the dynamic connect timeout value and will start at the default connect timeout again on start-up.

The edge server keeps track of connection failures to each IP address and port


Adaptive Connect Timeout (Beta)Confidential & Proprietary

separately and hence calculates the connect timeout for each IP and port separately regardless of which IP belongs to which hostname.

Before the edge server performs a DNS lookup, it will set the connect timeout based on the static connect-timeout value in metadata. After the DNS lookup completes and the edge server knows which IP address it will go to, it will cancel the previous timer and set a new one based on the dynamically calculated connection timeout (if there is one). When resetting the timer, the edge server will decrease the dynamic timeout value by the amount of time it spent doing the DNS lookup. The dynamic connection timeout is always set based on milliseconds.


Chapter 16: Network

Client-Side Traffic Shaping (Beta)

This feature provides a mechanism for controlling the rate at which content is served to end users. The feature can be applied within a match on various properties of the client request.

Example uses include:

• Limiting the rate of a progressive media download (a video file) to that of the bit rate of the media encoding. This would be advantageous as it could avoid serving the user more data than they actually view.

• Limiting the rate of large file downloads to keep the overall traffic rate reasonable.

• Differentiating end-user experience into "premium" and "free."

The bit rate used to serve the client can also be varied based on time or bit thresholds. For example, you could choose to serve the first megabyte of data without any limit to the bit rate, so that playback can begin immediately, and then begin limiting the download rate to that of the media media encoding.

TechnicalDetails

When this feature is enabled, the Akamai server will restrict the flow of data to the client to the specified "bitrate" once the specified "threshold" has been reached. The bit rate is expressed in bits per second (or kilobits, megabits, gigabits). The threshold can be expressed either as a number of bytes (kilobytes, megabytes, etc.) or as a number of seconds relative to the real-time viewing spead of the content. You an specify multiple thresholds and bit rates, but the expected usage is for a single bit rate setting to apply once a given amount of data was delivered without restriction.

This feature allows for obtaining the desired "bitrate" and "threshold" settings from an encrypted query argument or cookie in the client request or from a header in the origin response so that it is possible for the origin server to specify these values dynamically rather than have static values in the configuration file.

InformationHeader

When this feature is enabled, sending the header Pragma: x-rate-limiting-data in a request will return the response header X-Akamai-Rate-Limit: rate:threshold, where "rate" and "threshold" contain the values of the bit rate and threshold applied to the request. This is done to assist in debugging the rate-limiting behaviors.



In This Chapter

Log Delivery • 242

Edge Logging (Download R

17
Reporting
eceipts) • 245

This chapter describes the logging capabilities of Akamai. Log Delivery Service (LDS) is the mechanism by which Akamai transfers information regarding the content served through its network. In addition to the standard fields in the logs, you can choose to have edge servers log any of several optional fields. These are described in the Log Delivery Service section.

You can also configure Akamai edge servers to transfer information regarding the content served as it serves the content. This is called Edge Logging or “download receipts" since it is commonly used to track the success of client downloads of specific files.

241

Chapter 17: Reporting

Log Delivery

Through Log Delivery Service (LDS), you can gather valuable information about the traffic on a Web site. Customer logs are delivered through e-mail (or via FTP) in various formats and can be configured to contain the fields you are interested in tracking.

The edge server log formats are described briefly below. For a more detailed description of LDS and the format of delivered logs, see Akamai Log Delivery Service: Service Description & Customer Integration Guide. This document is available on the Akamai customer portal, https://control.akamai.com

Caveats You should be careful not to request more log fields than actually used.

TechnicalDetails

Akamai customers can choose between two log formats: Combined Log Format and Custom Log Format. The two formats are described briefly here.

Combined LogFormat

The Combined Log file format provides the following fields for each entry in the log:

• Client IP address (c-ip)

• The remote logname of the user (ident)

• The username under which the user was authenticated (authuser)

• Date and time of the request (datetime)

• The request line exactly as it came from the client ("request")

• The HTTP status code returned to the client (status)

• The content-length of the object transferred (bytes)

Combined Log format can also optionally include two additional fields:

• The referring URL (Referer header contents)

• The client software name and version (User-Agent header contents)

Custom LogFormat

The W3C Extended Log Format lets you to specify the fields you’re interested in logging. This is useful for reducing the size of logs by eliminating fields contained in the Common and Combined log formats.

The custom log format also lets you specify three additional fields not supported by the Combined Log format:

• All Cookies contained in the request (or selected cookies you have specified).

• The contents of the Host header

• The contents of the Accept-Language header

Integration You can self-configure Log Delivery Service on the Akamai customer portal. To begin


Log DeliveryConfidential & Proprietary

receiving your logs, log onto the customer portal and submit the information on how you want your logs configured and delivered. If you have any questions regarding this process, you should contact your Account Specialist.

Combined LogFormat

You can instruct the Akamai server to log the Referer field or User Agent in a request through settings in either HTTP response headers or your edge server configuration file.

Integration by HTTP Response Headers

For these response header settings to be of any value, the content provider must first sign up for Log Delivery Service with combined format.

Log Referer: You can instruct Akamai servers to log the referer field for a request by using the Edge-control header log-referer. For example:

Edge-control: log-referer

Log User Agent: You can instruct Akamai servers to log the user agent field for a request by using the Edge-control header log-user-agent. For example:

Edge-control: log-user-agent

Integration by Configuration Files

You can directly control the logging of Referrer and User-Agent headers for your content through Configuration Manager where the feature is called "HTTP Headers to Include in Logs" and is grouped under the category "Reporting Options." This feature also provides control over whether the client request Host header is logged.

Custom LogFormat

You can instruct Akamai servers to log the Referer field, User Agent, Host header, cookies, and Accept Language header in the request for an object can be accomplished through settings in either HTTP response headers or the configuration file.

Integration by HTTP Response Headers

Note that for these response header settings to be of any value, the content provider must first sign up for Log Delivery Service with custom format.

Log-Referer: You can instruct Akamai servers to log the referer field for a request by using the Edge-control header log-referer. For example:

Edge-control: log-referer

Log User-Agent: You can instruct Akamai servers to log the user agent field for a request by using the Edge-control header log-user-agent. For example:

Edge-control: log-user-agent

Log Host Header: You can instruct Akamai servers to log the host header field for a request by using the Edge-control header log-hosthdr. For example:

Edge-control: log-hosthdr



Log Cookies: You can instruct Akamai servers to log all cookies that accompany a request by using the Edge-control header log-cookie. Although the metadata component is singular, it will log all cookies with the request. For example:

Edge-control: log-cookie

Log Accept-Language Header: You can instruct Akamai servers to log the Accept-Language header field for a request by using the Edge-control header log-accept-lang. For example:

Edge-control: log-accept-lang

Integration by Configuration Files

You can directly control the logging of Referer, User-Agent, Host header, and cookies through Configuration Manager where the features are called "HTTP Headers to Include in Logs" and "Cookie Values to Include in Logs." These features are grouped under the category "Reporting Options."


Edge Logging (Download Receipts)Confidential & Proprietary

Edge Logging (Download Receipts)

In addition to the historical logs provided through the Log Delivery Service, the Akamai edge server can report to the origin server on the success of client downloads in real time as the downloads complete.

Alternatively, these ‘download receipts’ can be aggregated and delivered periodically to reduce the receipt traffic to the origin server. For example, you might configure the feature such that each Akamai server delivers one aggregated list of receipts every few minutes.

Caveats Edge Logging should not be viewed as a substitute for historical logs. The Akamai server sends receipt requests to the origin and does not wait for any confirmation of receipt to ensure that the request was actually received.Aggregation of receipts occurs in non-persistent server memory. In the event the Akamai server restarts for any reason, unsent receipts in the aggregation buffer would be irretrievably lost.

TechnicalDetails

The Akamai server reports on the status of client downloads in real time by sending a special request to the origin server after each client download completes. Edge Logging receipt requests are sent using HTTP as the scheme unless specifically configured otherwise. The request can be configured as either a GET or a POST request. If receipts are aggregated, the request is a POST with the aggregated receipts in the POST body.

This special request can be configured to communicate the information of interest to the content provider. The request can contain any of the following information about the client request and how it was served:

• IP address of the HTTP client -

• EdgeScape info about the client. For example, country code, region code, or city. You can include any EdgeScape information available to the request based on the version of EdgeScape (Regular or Pro) in use.

• Time of the beginning of the request, in UTC time zone or epoch format.

• Origin server name

• Complete Request URL (path + query), request URL path, or request URL query string.

• The value of a cookie of a specific name, or the value of a string within a cookie of a specific name. We log an empty string if the cookie does not exist or the desired string is not found.

• Request header of a specific name

• All request headers

• HTTP status code

• Response content type

• Client abort status; in the event the client aborts the download before receiving



the last byte on an HTTP 200 response code from the Akamai server.

• Download time in milliseconds or DDHHMMSS format

• Content bytes served

• Object content-length in bytes

• Flag that indicates if the last byte of the object was downloaded

• Customer cpcode

• Customer Serial number

• ESI debug information

ReceiptAggregation

Receipt Aggregation allows for collecting the Edge Logging receipt requests into a single request to be delivered later. When aggregation is used, the receipts are forwarded to the origin server in the body of a POST request in which

• the receipts are in the order the requests completed and the receipts were generated.

• each individual receipt is separated by a new line character (‘\n’).

• the lines are URL encoded as specified in RFC1738 before they are added to the entity.

• the content type is application/x-www-form-urlencoded. (Unfortunately, the edge server currently does not set the Content-Type header in the forward request.)

Delivery of the aggregated receipts is triggered based on one of three thresholds being reached:

• a number of bytes

• a number of receipts

• a time interval

Each of these thresholds is configurable and establishes a default maximum if aggregation is enabled but a particular threshold is not specified.

Receipts of different names are aggregated in separate buffers. That is, if the configuration file calls for generating receipts with names SERVED200 and RANGEREQ, each of these would be aggregated into separate buffers and sent to the origin as separate POST requests. Likewise each buffer would have its own thresholds for triggering delivery.

Integration The Professional Services consultant should submit a provisioning request that includes the basic required information. The configuration request should also explicitly list:

• The information to be conveyed in the receipt request

• The exact scope of the site for which download receipts should be sent.


Edge Logging (Download Receipts)Confidential & Proprietary

• Whether the receipts should be aggregated and, if aggregated, which thresholds should be used to determine when the receipt is forwarded.





In This Chapter

Support POST Requests • 2

Support for PUT and DELET

Munged URL • 252

Object ID Checking • 253

Authenticate Object ID's •

Use SSL Going Forward • 2

18
Security Related Features
50

E Methods • 251

255

56

If your Web site serves sensitive content, you might want to ensure that Akamai's servers are the only clients permitted to download material from your origin servers. Or, you may be concerned that the objects Akamai serves are not corrupted in any intentional or unintentional way. This chapter describes features related to security or data integrity.

249

Chapter 18: Security Related Features

Support POST Requests

For security reasons, Akamai's servers do not, by default, support HTTP POST requests (commonly used for processing forms, for example). To allow posting, this feature must be explicitly enabled.

Please note that responses to POST requests are not cached in Akamai's servers by default, but you can configure this behavior using the Cache POST Responses feature.

POST Caching atthe Client

By default, POST responses to the client contain cache-busting headers to prevent proxy caches from storing the file and serving it to multiple clients. This has the unfortunate side effect of also rendering the response uncacheable for the client. The result is that the client cannot use the “Back" button to return to the page once they have moved to another.

If POST responses from the origin are cacheable for the end-client, you may want to preserve this by passing the origin headers to the client, rather than sending the default cache-busting headers. You can accomplish this with a combination of the header manipulation features described in the chapter Edge Services - General.

Integration You can directly control POST support for your content through Configuration Manager, where this feature is called "HTTP POST." In the Configuration Manager interface, the option to support POST is turned on by default, and you are given the opportunity to turn it off.

Note: As a best practice, Integration Consultants will recommend turning this feature on by default, unless the content provider knows that support for POST requests is not needed and would prefer to have the feature left off.


Support for PUT and DELETE MethodsConfidential & Proprietary

Support for PUT and DELETE Methods

For security reasons, Akamai's servers do not, by default, support HTTP PUT and DELETE requests from clients. To allow these methods, the feature must be explicitly enabled.

Please note that responses to PUT and DELETE requests are not cached in Akamai's servers by default and you cannot configure them to be cached.

Response Cachingat the Client

By default, the response to a PUT or DELETE request contains cache-busting headers to prevent proxy caches from storing the file and serving it to multiple clients. This has the unfortunate side effect of also rendering the response uncacheable for the browser. The result is that the user cannot use the “Back" button to return to the page once they have moved to another.

If responses to PUT and DELETE requests from the origin are cacheable for the end-client, you may want to preserve this behavior by passing the origin headers to the client, rather than sending the default cache-busting headers. You can accomplish this with a combination of the header manipulation features described in the chapter Edge Services - General.


Allowing DELETEwith a Body

In the current implementation, allowing the DELETE method with the tag security:allow-delete tag enables use of the DELETE method, but does not support passing a body as part of the request. If you want to support passing a body with the DELETE method, you need to enable support for WebDAV. You can limit this support to the DELETE method by enclosing it inside a match on the DELETE method, like this:



Munged URL

For security reasons, some Akamai customers prefer to hide the name and directory structure of the origin server from the casual observer. Akamaizer tools will optionally "munge" the URI portion of the ARL (except the portion after the last slash) in a manner that Akamai servers can later decode. For example:

http://a9.g.akamai.net/5/9/1440/000/www.foo.com/images/logo.gif

becomes

http://a9.g.akamai.net/5/9/1440/000/1a1a1a940735ae1784eb197/logo.gif

The portion of the URL after the last slash is not munged because browsers typically use this as a suggested name when presenting dialog boxes to save files, etc.

Caveats There is a minor calculation overhead in having the Akamai server unmunge the URL's each time they fetch an object.

Only customers using an Akamaizer can use this feature.

Integration Munged URL's can be implemented only in an ARL using typecodes 5, 4, d, k, l, and t). No request should be submitted.

For a listing of typecodes and their meanings, see FreeFlow Typecode Summary


Object ID CheckingConfidential & Proprietary

Object ID Checking

Akamai's edge servers do substantial double and triple checking to ensure that they never serve the wrong object or a corrupted object from cache. Still, there are some risks that are out of our control. Akamai receives data from the origin server across the public Internet. One unfortunate side effect of this is that a transparent proxy server between the Akamai server and origin server could (intentionally or unintentionally) corrupt the data Akamai's servers receive. While we have not seen any evidence of this happening in the field, Akamai does support Object ID checking for ARL's that contain an Object ID.

With Object ID checking enabled, Akamai will compare a secure hash of the object as specified in the ARL with the computed secure hash of the object it is serving. If the Object ID's do not match, Akamai servers behave in one of two ways depending on the typecode used for Object ID checking:

• Under Typecode 2, the Akamai server serves client requests with the object retrieved, but retries the download after a specified time-to-live for objects with a bad Object ID’s. It continues to retry for each expired time-to-live until it receives an object with a matching Object ID.

• Under Typecode 3, the Akamai server cancels the client request, serves an error in place of the object, and the object with the bad ID is deleted from cache.

Caveats It is important that the site is properly Akamaized.

If the Web site serves an incorrect Object ID, and Typecode 3 is enabled, Akamai's servers will be unable to serve these objects to end-users. Every client request would require the Akamai server to request the entire object from the origin server and then discard it due to a failure in the Object ID check. If clients continue to request the object, the Akamai server must repeatedly download and discard. This can generate excessive load on origin servers

Note: Typecode 3 does not work correctly with files greater than 16 megabytes.

TechnicalDetails

As mentioned above, there are two versions of Object ID checking. They are enabled through Typecode 2 (and its derivatives) and Typecode 3 (and its derivatives).

Typecode 2 Typecode 2 causes the Akamai server to check the Object ID of the object retrieved from the origin server against the Object ID in the object data field in the ARL. When these identifiers do not match, the Akamai server caches and serves the object anyway, and retrieves a new object from the origin server after a specified time-to-live. (The default TTL is 30 minutes, but this TTL can be set in the customer configuration file.) Once an instance of the object with the correct identifier is retrieved, the TTL is extended to infinity.

Also, under Typecode 2, the Akamai server will begin serving the object to the client as it receives it from the origin, rather than waiting until the entire object has been



retrieved and checked for a valid Object ID before serving the client.

Typecode 3 Under Typecode 3, the Akamai server compares the Object ID of the object retrieved from the origin server against the Object ID in the object data field in the ARL. The action taken depends on the results of the comparison:

• If the identifiers match, the Akamai server serves the object to the client and caches it with an infinite time-to-live.

• If these identifiers do not match, the object is discarded; it is not stored in cache or served to the client. Instead the client is served a status code 502 HTTP BAD GATEWAY error.

If the you want to use Typecode 3 behavior, it must be enabled for you through the configuration files.

Integration Object ID Checking can be enabled only in an ARL through typecodes 2, 0 (zero), g, i or typecodes 3, 1, h and j. However, there are configuration options associated with each of these typecodes, as described below.

Typecode 2 (andderivatives)

If the you want to configure the time-to-live for objects with bad Object ID's as something other than 30 minutes, the Integration Consultant should submit a provisioning request. In addition to the basic required information, the request should explicitly state:

• The time-to-live for objects with bad Object ID's(As with standard time-to-live, this setting can be varied based on directory path, file extension, or any other characteristic by which application of features can be limited.)

Typecode 3 (andderivatives)

Typecode 3 behaves exactly as Typecode 2 unless you specifically requests the “strict" Typecode 3 behavior of discarding objects with bad Object ID's and serving clients only after an Object ID check succeeds. Only Web sites using an Akamaizer should use this typecode. The Integration Consultant should submit a provisioning request with all the basic required information.


Authenticate Object ID'sConfidential & Proprietary

Authenticate Object ID's

Akamai servers normally consider any Object ID valid when the Object ID arrives in the request. As a result, an end user could potentially flood an Akamai server with requests for a single object, each with a different Object ID, and thus cause the origin server to be overwhelmed with requests.

This authentication feature allows the Akamai server to determine whether an Object ID was generated by a CP rather than made up by a user or a hacker.

This feature applies only to standard FreeFlow ARL's, since that is the only mechanism Akamai currently supports that includes an Object ID with the request.

Caveats As with any Object ID checking scheme, it is critical that the Web site properly generate the encrypted Object ID and the results be tested before the solution is deployed. Any errors in the encryption or decryption steps will cause Akamai to deny service to the requests.

TechnicalDetails

This solution involves adding an encrypted and hex-encoded authentication code to the Object ID. When this feature is enabled, the Akamai server will attempt to validate the Object ID by extracting and decrypting the authentication code using a key value stored in the configuration file. If the decryption step fails, the request is rejected.


• The value of the Object ID authentication key

• The value of the alternate Object ID authentication key (if any), used for transition from one key to another

• A sample ARL with a properly encoded authentication code in place. (Your Integration Consultant can provide the list of steps to follow in generating a properly encoded Object ID.)



Use SSL Going Forward

By default, the Akamai server goes forward to the origin server using HTTP or HTTPS depending on the format of the original client request. That is, an HTTP request goes forward using HTTP, and an HTTPS request goes forward using HTTPS. This feature makes it possible to force an HTTP client request to go forward using HTTPS.

TechnicalDetails

The cache key is always based on the protocol used to forward the request toward the origin. If the Akamai server receives a non-SSL request but goes forward using SSL, the cache key will be SSL based. As a result, if a Web site using this feature has both an HTTP and an HTTPS version of the same page, the objects for both the HTTP and HTTPS pages will be cached under the same entry.

The forward protocol setting, when used, also applies to communication between Akamai servers. When the forward protocol is set to HTTPS, Akamai servers will connect to port 443.



In This Chapter

Variables Syntax • 258

Extracting Values Into Varia

Assigning and Transforming

Comparing Variables • 265

19
Using Variables
bles • 260

Variables • 262

This chapter discusses some of the features and individual metadata tags available for manipulating variables. The most common use for variables is to extract a value from some portion of a client request (for example, a cookie), and then use that variable to declare the value in other metadata. Specifically, this technique is often used to set the Host header in the request forwarded to the origin server based on a client session cookie value.

257

Chapter 19: Using Variables

Variables Syntax

In general, you can use a variable in an edge server configuration file where the metadata tag normally takes an unrestricted string as its content. Most other tags will fail schema validation if you try to put the variable name inside them.

The variables syntax is:

%(VARIABLE-NAME)

This is similar to ESI’s $(VARIABLE-NAME) syntax.

Whenever a built-in variable is used, the variable name begins with AK_ to distinguish this variable from any potentially similar user-defined variables. The following are two examples of common variable usage:

<forward:modify-host-header.value>%(AK_HOSTHEADER)</forward:modify-host-header.value>

<forward:origin-server.host>%(EXTRACTED-VALUE)<forward:origin-server.host>

Available Built-inVariables

The following is a list of built-in variables available for use in metadata without the need to first perform an extraction.

AK_HOSTHEADER: the client request hostname

AK_DOMAIN : the hostname minus the first subdomain and dot. That is "example.com" if the request hostname was www.example.com

AK_ARLTOKEN : the client request ARL Token (for v1 ARL's only)

AK_CPCODE : the request cpcode

AK_SCHEME: Scheme of the incoming request ("http" or "https")

AK_METHOD: Method if the incoming request

AK_HOST: Host of the incoming request. Synonym for AK_HOSTHEADER

AK_URL: URL of the incoming request. This includes the query

AK_PATH: URL path of the incoming request. Use extract-value to get separate path components.

AK_QUERY: Query of the incoming request. Use extract-value to get query components.

AK_FILENAME: Filename of the incoming request

AK_EXTENSION: Filename extension of the incoming request.

AK_TYPECODE: Typecode in the ARL

AK_CLIENT_IP: Client IP address seen by the Akamai server. Can be overriden by the X-Forwarded-For and Akamai-Client-IP request headers.

AK_CLIENT_REAL_IP: Client IP address seen by the Akamai server. Request headers are ignored.


Variables SyntaxConfidential & Proprietary

AK_CURRENT_TIME: The current epoch time as of application of metadata to the request.

AK_SR2_RACE_KEY: The stat-key for the Sureroute v2 race.



Extracting Values Into Variables

Akamai servers can extract a value from the client request and match on that value to apply features or make the value available to ESI.

This ability is particularly useful when handling session ID’s. It is the method by which the Akamai server can insert the client’s session ID into links for pages that are cacheable on the Akamai server.

This can also be used to maintain stickiness with a particular origin server in the case where a server farm does not share the session object among the servers and the client is therefore expected to return to the same server for each subsequent request in a session. The Akamai server extracts a value and uses that value to determine the origin server to which it should forward the client request.

TechnicalDetails

You can extract the value from:

• HTTP headers

• Cookies

• Path components (by name or offset)

• Path parameters by name

• Query string arguments by name

• Response headers sent to the client or received from the origin

• Set-Cookie headers sent to the client or received from the origin

• Host domain components

• EdgeScape data fields

You assign a variable name to the extracted value, and you can extract more than one value for a variable, in which case, the last extracted value is the one that takes precedence. Alternately, you can assign a different variable name to each extracted value to differentiate them if you have a need for more than one. For example, to support use of session ID’s there may be one variable into which the client’s session ID is stored and another variable into which a value is stored to determine which origin server should be used when going forward.

You can also delete the value from a variable, to unset the variable based on some condition.

Finally, the origin server can override the variable value through use of a special response header. Again, this is used to implement support for session ID’s, and is the mechanism by which the origin server overrides an expired or invalid session ID in the client request.


Extracting Values Into VariablesConfidential & Proprietary

Note: You cannot assign one variable to another variable. Variable values must be constants.



Assigning and Transforming Variables

In addition to extracting a value from a request or response and assigning it to a variable, you can directly assign a value to a variable. In the process of assigning a value to a variable, you can also transform that value. For example, you could URL-encode a value before assigning it to a variable to be used in forming a Location: header for a redirect response.

Following is a list of possible transformations with a brief definition of the transformation.

Transformation Description

md5 Get the MD5 as a hexadecimal string of size 32 in uppercase.

hmac This node produces a base64 encoded digest value from the variable value and key. Algorithms to use include: SHA1, SHA256, MD5

sha1 Calculates a SHA1 hash from the input. Note that the computed hash is in a raw binary form and may need to be further encoded to be usable.

upper Convert the string to upper case.

lower Convert the string to lower case.

trim Remove leading and trailing white spaces from input

url-encode URL encoding (RFC 1738, more details below)

url-decode URL decoding (RFC 1738, more details below)

urlDecodeUni Same as url-decode, but also decode unicode encoding.

xml-encode XML encoding (more details below)

xml-decode XML decoding (more details below)

cssDecode Decode CSS escaping in the input

htmlEntityDecode Decode HTML entities present in input.

jsDecode Decode javascript escape sequences.

normalisePath Remove multiple slashes, self-references and directory back-references.

normalisePathWin Same as normalisePath, but first convert backslash characters to forward slashes.

base64encode Apply base64 encoding to a variable.

base65decode Decode a base64-encoded string

hexEncode Encode input as hex-encoded string.

hexDecode Decode a hex-encoded string.

decimal-to-hex Convert a decimal integer to a hexadecimal string.

hex-to-decimal Convert a hexadecimal string to a decimal integer.

escapeSeqDecode Decode ANSI C escape sequences. Invalid encodings are left in the output.

string-length Get the string length of the input.


Assigning and Transforming VariablesConfidential & Proprietary

string-index Get the position of the first occurrence of a substring inside the input string, or -1 if it is not found. This is case sensitive.

add input = input + value

subtract input = input – value

multiply input = input * value

divide input = input / value

modulo input = input % value

bitwise-and input = input & value

bitwise-or input = input | value

bitwise-xor input = input ^ value

bitwise-not input = ~input [One's complement]

minus input = -input [Two's complement]

substring Extract a substring.

parityEven7Bit Calculates even parity of 7-bit data replacing the 8th bit of each target byte with the calculated parity bit.

ParityOdd7Bit Calculates odd parity of 7-bit data replacing the 8th bit of each target byte with the calculated parity bit.

ParityZero7Bit Calculates zero parity of 7-bit data replacing the 8th bit of each target byte with a zero parity bit which allows inspection of even/odd parity 7bit data as ASCII7 data.

hash Hash the string into an integer. This returns the string representation of (HASH(input) % (max-min+1)) + min, where HASH is an arbitrary function that hashes a string into an unsigned 32-bit integer.

rand Generate a 32-bit unsigned random number between min and max.

hexrand The hexrand transformation generates a configurable number of bytes of random data. Maximum, and default, setting is 16 bytes.

encrypt Encrypt the string. The output is the nonce followed by the base-64 encoded encrypted input. In order to make the encryption non-deterministic, a 8-byte random string is prepended to the input before encryption.

decrypt Decrypt an encrypted string. The first 8 bytes of the decrypted value are automatically deleted.

substitute Do a regular expression-based substitution (similar to Perl's =~ s/regex/replacement/flags)

The regular expression can use grouping.

extract-param Extract a value from a list of parameters. This is useful to extract query parameters without having to write a regular expression.

* If several occurrences of the parameter exist, only the first one is returned.

* If the parameter is not found, the transformation fails.

* The separator between the name and the value of a parameter is always '='.




The maximum length for the value of any variable is 4K. You can increase this maximum size in the unlikely event you need to form a very long variable value. However, there is an overriding maximum length of 16K that cannot be exceeded.

replaceComments Replace C-style comments with a single space.

replaceNulls Replace NULL bytes with spaces.

removeNulls Remove NULL bytes from input.

removeWhitespace Remove all whitespace characters.

compressWhitespace Convert whitespace characters to spaces, then compress multiple space characters into only one.



Comparing VariablesConfidential & Proprietary

Comparing Variables

You can compare the value of two variables (or a variable and a fixed value) and apply features if the comparison yields the desired result. Possible comparisons include:

• equal

• not equal

• less than

• greater than

• less than or equal to

• greater than or equal to

If the value of the two arguments are both valid 64-bit signed integers, the operation is performed on the integer values. Otherwise, it is performed on the string values (basic lexical comparisons in ASCII). To perform case-insensitive comparisons, you must first convert the arguments to the same case, using either the “upper” or “lower” transformations.

You can also compare the value of a variable against a regular expression, and apply features if the comparison is true (or false).





In This Chapter

Session ID Support • 268

Download Manager • 271

Progressive Download Seek

20
Other Capabilities
ing • 272

This chapter lists some additional capabilities of Akamai servers. Currently, material is included here for one of two reasons:

1. It does not easily fit within another category

2. It does not constitute what we would characterize as a “feature”, but is nonetheless an important capability.

267

Chapter 20: Other Capabilities

Session ID Support

Akamai can support Web sites that use session ID’s to maintain information about user activity. For a complete description of how session ID’s are supported, see the separate document: Edge Server Session ID Support.

The three session ID implementations Akamai can support are:

• Cookie-based session ID's only. The session ID is passed to the client in a Set-Cookie header and the client returns the session ID cookie with each request.

• URL-based session ID's only. The origin server (usually an application server in this case) rewrites the URL’s in pages to include the session ID as part of the URL. The session ID is often part of the query string in this case. Each client request returns the session ID as part of the URL for the request.

• Cookie/URL hybrid session ID's. If the client request doesn’t include a session ID cookie, the origin server rewrites the URL’s to include a session ID and sends a Set-Cookie header. Any client that accepts the cookie will return the session ID cookie in future requests, in which case the URL’s are no longer rewritten.

Caveat The Akamai Prefresh feature is not compatible with use of session ID's. Akamai Prefresh causes the edge server to validate an object's freshness with the origin server after the client has been served. Akamai Prefresh should be explicitly turned off in the configuration file for Web sites that use session ID's, unless it is possible to identify content that will neither change the session state nor initiate a new session when one doesn't already exist.

TechnicalDetails

Some Web sites use a session ID to track the movement of a user through the site or associate a server object with the user. For example, the session ID might identify the end user's shopping cart while browsing an e-commerce site. On the browser side the shopping cart is merely a session ID, but on the server it is a collection of items (the contents of the cart) associated with the ID.

The Session ID may be passed between the origin server and the browser as either a cookie or a portion of the URL. In many cases, notably J2EE application servers, the primary mechanism is a cookie, but if the browser doesn't support or accept cookies, the URL's are rewritten as a backup solution.

Session IDSupport

Requirements

The requirements for supporting use of session ID’s varies depending on the mechanism for passing the session ID’s. These requirements are discussed in detail in Edge Server Session ID Support. Following is a brief summary.

Session ID’s Only in Cookies

For Akamai to support session ID's in Cookies, the content provider must be able to:

• Identify which requests potentially change the session state.


Session ID SupportConfidential & Proprietary

• Send a Set-Cookie header in a 304 Not-Modified response to an If-Modified-Since request from Akamai.

Session ID’s Only in URL’s

For Akamai to support session ID's in the URL's, the content provider must be able to:


• Use session ID's that contain a prefix by which the session ID portion of the URL can be identified and removed for caching.

• Identify which content contains links that are specific to a user session. (This may be all HTML.)

In the simple case, this content is treated as uncacheable. If the Web site uses ESI to abstract out the session ID from the HTML, this content can be rendered cacheable. To accomplish this, there are two additional requirements.

• Insert ESI statements in place of the session ID’s in the links (or use a servlet to do this).

• Send a custom HTTP header that contains the session ID parameters. The origin server must be able to send this header in response to an If-Modified-Since request from Akamai (preferably in a 304 Not-Modified response).

Session ID’s in Both Cookies and URL’s

For Akamai to support session ID's in both cookies and URL’s, the content provider must be able to:


• Use session ID's that contain a prefix by which the session ID portion of the URL can be identified and removed for caching.

• Send a Set-Cookie header in response to an If-Modified-Since request from Akamai.

• Identify which content will contain links that are specific to the user session and send an Edge-Control: bypass-cache header in the response.

Use of the Edge-Control: bypass-cache header instructs the Akamai server not to cache the response, and not to evict an existing entry (one returned in response to a request with a Cookie header). This model treats the responses to requests that contain the session ID cookie as cacheable and responses to requests that use session ID’s in the URL’s as uncacheable.

If the Web site uses ESI to abstract out the session ID from the HTML, this content can be rendered cacheable. To accomplish this, there are two additional requirements.

• Insert ESI code in place of the session ID’s in the links (or use



Akamai-provided code or tools to do this).

• Send a custom HTTP header that contains the session ID parameters. The origin server must be able to send this header in response to an If-Modified-Since request from Akamai (preferably in a 304 Not-Modified response).


Download ManagerConfidential & Proprietary

Download Manager

Akamai’s Download Manager is available as an add-on feature for Akamai customers who use their Web sites to deliver digitized files, such as software, movies, or other large objects. Download Manager uses InstallShield® DigitalWizard™ to provide a standard for distributing, downloading, and installing digitized assets via the Internet. In particular, the Download Manager makes it possible for the end user to interrupted and resume downloads seamlessly.

For more details regarding the Download Manager, see the feature description on the Akamai customer portal at: https://control.akamai.com.

Caveat Download Manager is available only for the Microsoft® Windows® operating system. However, it is relatively simple to configure the edge server to invoke the Download Manager for user requests from browsers running on Microsoft® Windows® while delivering the content without Download Manager for other operating systems.



Progressive Download Seeking

The Akamai server can support delivering content requested for a specific seek location within an MP3 or FLV progressive download.

TechnicalDetails

To support this feature, the Player request for the progressive download must include a time offest parameter in the request. For example, the request would have a format similar to:

/urlpath/xyz.flv?aksessionid=mscscscs&aktimeoffset=0

The Akamai server will use the value of the aktimeoffset parameter to identify the appropriate frames. To do this it inspects the file metadata and buffers the response until it has the appropriate point in the data. The Akamai server then assembles the appropriate FLV header and FLV metadata to send to the player before beginning the transfer.

The query string parameters (aksessionid and aktimeoffset) are not used as part of the cache key for the file. They are unconditionally filtered out of the URI when computing the cache key.

Caveats There are several caveats to use of progressive download seeking.

• Progressive media processing will not work with Range requests; the player must request the full file with the time offset specified in the

• Progressive media processing will not work with gzip compressioni (Last Mile Accelerator).

• The Akamai server will not chunk the progressive media files when sending to client.

• Progressive media processing will be done only to the end user. Internal Akamai server requests (ICP/cacheh) will not be processed; the entire file will be transfered between servers.

https://docs.akamai.com/esp/user/edgesuite/guides/

metadata.htm#edgeservices+progressive-download

Note: Use of this feature is officially deprecated. New customers should use the AkamaiHD Network to deliver their progressive media files.


https://docs.akamai.com/esp/user/edgesuite/guides/metadata.htm#edgeservices+progressive-download


In This Chapter

NetStorage • 274

21
Related Services
This chapter briefly describes additional services that involve some form of integration for use with Akamai edge servers.

273

Chapter 21: Related Services

NetStorage

NetStorage is a managed service that provides persistent, replicated storage of Web site content — images, streaming media files, software, documents, and other digital objects. By mirroring content to a small number of core network locations and thus making it highly-available and easily-accessible to Akamai edge servers, NetStorage complements Akamai’s content delivery services.

NetStorage content can be served through an edge server domain. That is, a content provider can create their content as they normally would, with URL's that point to their own domain, and Akamai edge servers can request the content from NetStorage transparent to the end user.

Some possible applications of NetStorage include:

• Serving any web object (particularly large or flash-popular files) from NetStorage

• Serving an entire site (minus data-base transactions) from NetStorage

• Using NetStorage as the source of default content for partial backup of the origin server

• Using NetStorage as a mirror site in the event the content provider's origin server becomes inaccessible

For a complete description of the NetStorage service and how to use it, see the documents available on the Akamai customer portal at: https://control.akamai.com/


Glossary

AAkamai server Also called “edge servers.” Akamai servers form a global network that provides

faster download times by allowing end users to retrieve content that’s closer to the “edge of the Internet.”

Akamai ResourceLocator (ARL)

The ARL, or Akamai Resource Locator, is similar to a URL but allows content to be served from the Akamai platform.

Akamaize To Akamaize a site is to prepare it for serving content through the Akamai platform. This can involve replacing URL references with ARL references.

asynchronousrequest

This type of request includes an “asynchronous refresh” (also called a “prefresh”). An asynchronous refresh is performed after serving the client (asynchronously) rather than before (synchronously).

auth In Akamai metadata, the abbreviation auth is used as a metadata tag to specify settings for authentication or authorization.

authentication Authentication refers to the process of validating the identity of a user/client. This is sometimes done based on username and password. Authentication and authorization are the two steps needed to provide access for a client to an Edge server or origin server. A client must first be authenticated before a request can be authorized.

authorization This is the process of granting or denying access to a network resource. Most computer security systems are based on a two-step process. The first step is authentication, which validates the identity of a user/client. The second step is authorization, which allows the user/client access to resources based on the user’s/client’s access privileges.

Ccache busting Cache busting refers to mechanisms that prevent an HTTP response from being

stored in cache. This is usually accomplished by sending HTTP headers that direct the client not to cache the response. Cache-Control: no-store , Cache-Control: no-cache, Pragma: no-store, and Expires with a value equal to "now" are examples of cache-busting headers. Akamai servers generally send these headers to clients when authentication or authorization of the client is being used or the content is not cacheable by the Akamai server.


Glossary

cache hierarchy Cache hierarchy uses parent-child relationships between Akamai servers to distribute content from the origin server through hierarchy parents to edge servers (hierarchy children) to distribute cache server load. An Akamai server is the "parent" server when it responds to a request from another Akamai server in the hierarchy. This system helps reduce network bandwidth usage and load on origin servers. In Akamai metadata, this is abbreviated as cacheh.

The Akamai edge server feature called Tiered Distribution uses cache hierarchy to significantly reduce the amount of traffic on origin servers and exploit server-to-server optimizations, such as persistent connections.

cacheh Short for cache hierarchy. This abbreviation is used in Akamai metadata tags where the settings apply between Akamai servers that are cache-hierarchy peers.

cache hit This occurs when a request is made for an object and that object is in cache.

CP code Short for content provider code. Used primarily for billing and reporting purposes, this code is a unique identifier of a customer’s account.

DDCA Short for Dynamic Content Assembly. DCA allows content to be customized on the

Akamai edge server and to be delivered quickly and reliably to each user, without interaction with a centralized application server.

downstream This refers to data being sent from a server to a client. When discussing content service with Akamai, this most often refers to serving from an edge server to a client (A transmission from a client to a server is referred to as upstream.)

EEdge, edge This refers to the "edge" of the Internet, close to the end users requesting content.

Akamai servers are often referred to as edge servers.

Edge Akamaizer The Edge Akamaizer provides the ability to replace regex-matched strings in HTML or XML files. One key application is the ability to selectively replace ARLs into separate secure and non-secure domains so as to obtain optimal benefits from the Akamai platform for both types of content.

The Edge Akamaizer functions through the use of regex matching and replacement specified in the customer configuration file. Objects to be Akamaized in this way are handled as an ESI object – that is, they are DCA parsed and processed.

Edge-control header An Akamai-developed header used for setting HTTP response header metadata. For example, including the header Edge-Control: max-age=30m instructs the Akamai edge server that the response can be cached for 30 minutes.

epoch time Unix “epoch time” format is used to specify start and end time in some edge server configuration file syntax. Epoch time is the number of seconds that have passed since 1 January 1970 00:00 UTC. You can find the current epoch time with the following Unix command:

$ date +%s1010705782

276 EdgeSuite Configuration Guide. Confidential and Proprietary

Glossary

escape, escaped,escaping, unescape

Escaping is used to replace special characters that would otherwise be interpreted as code in a particular context such as HTML or XML. For example, if a character used in the syntax of a tag (a comma or bracket, for example) is also used in the string of a parameter being added to the cache-id, you must “escape the character,” that is, list the escaped form of the character. See RFC 2396 (“URI Syntax”) for more information about escaping.

ESI Edge Side Includes (ESI) provides for dynamically generating HTML pages at the edge of the Internet, near the end user. The ESI language is an XML-based markup language that provides the tools to assemble the content dynamically.

Using ESIs improves the performance of Web-based applications by defining a simple markup language to describe cacheable and non-cacheable Web-page components.

evicting, evicted,eviction

Refers to the process of removing or deleting the requested object from cache on Akamai edge servers.

Fforward, forward

requestA request is "forward" if it is in the direction of the origin server.

FreeFlow typecode See typecode.

GAcronym for Global Host. Is commonly written in all lower-case as "". Refers to an Akamai Edge or to the specific server process (as distinct from the ESI process, for example).

Hhierarchy See cache hierarchy.

EdgeSuite Configuration Guide. Confidential and Proprietary 277

Glossary

HOIT Acronym for Hostname Or In-ARL Token. If your file contains metadata that is used to serve several hostnames, but you want to apply special metadata to some of those hostnames, you do this with a HOIT match. An In-ARL Token refers to the first version of ARLs, which contained metadata such as TTL embedded in a “token” inside the ARL.

IIMS request, If-Mod-

ified-Since requestUse of this term is consistent with the standard definition presented at w3.org or in other texts and glossaries. An IMS request is a request that includes an If-Modified-Since header, which specifies that the requested content is to be sent only if it has been modified since the date given as the value of this header. Akamai servers generally use an IMS request to refresh content that is already in cache.

Mmetadata Metadata, as used in reference to Akamai, is information about the content provider’s

content served by Akamai. More specifically, metadata is the set of control options and parameters that determine how an Akamai server handles a request for an object. Examples of metadata include the time-to-live settings that specify how long an object may be served from cache before it is revalidated with the origin server, and the log-cookies setting that instructs Akamai servers to log the cookies sent along with an object.

MUI Short for Metadata Update Interface (sometimes called the Metadata User Interface), MUI is the workflow management tool responsible for securely deploying customer metadata changes to the Akamai network. The tool has an optional front end that allows internal users to modify metadata files and a workflow management system that checks the validity of submitted metadata using internal rules and tests Akamai servers to make sure changes are safe.

Nno-store This is short for the cache:no-store metadata tag. Similar to cache:bypass, this tag

must be used with care, as it prevents Akamai servers from storing the content in cache – and it takes precedence over other cache coherence settings (such as cache:max-age).

Ppersonalized con-

tentSome content is highly personalized (is different for each end user) and can be assembled at the origin server only. Generally, this content is not cached, because it cannot be properly served to more than one client. Often, a page is comprised of both personalized and more static content. With DCA services such as ESI, you can cache the more static content, fetch the personalized content from the orgin, and compile the page at the edge, saving time and boosting performance.

prefix match A prefix match is one that attempts to match a given string to the beginning portion of a potentially longer string. For example, if the match string is "sessionid" and a prefix match is used, the found string "sessionid987654" would be a positive match because it begins with the match string.


Glossary

prefresh A prefresh request refreshes an object in cache before its Time-to-Live has completely expired. This is also called an "asynchronous refresh," because the object is refreshed after serving the client (asynchronously) rather than before (synchronously).

Qquery argument Use of this term is consistent with the standard definition presented at w3.org or in

other texts and glossaries. Also called a query string argument, a query argument is a value or parameter included within a query string. For example, a Web site might have URLs that look like the following: www.example.com/getfile.asp?fileID=1234&randomKey=a1b2&sessionID=32Getfile.asp

The portion of the URL in bold is the query string. The query argument is the value 1234. (See also query string.)

query string Use of this term is consistent with the standard definition presented at w3.org or in other texts and glossaries. A query string is the portion of a dynamic URL that contains the search parameters when a dynamic Web site is searched. Query strings do not exist until a user plugs the variables into a database search, at which point the search engine will create the dynamic URL with the query string based on the results. Query strings typically contain ? and % characters. (See also query argument.)

Rredirect chasing By default, when the response from the origin server is an HTTP redirect to obtain a

requested object, the Akamai server serves the redirect to the client and may cache it for response to future requests for the same object. With the Redirect Chasing feature enabled, the Akamai server can follow the redirect to obtain the object and serve it to the client. The object will then be stored in cache on the Akamai server and served to future requests. This reduces the number of requests the client browser must make to obtain the object and thus improves performance for the end user.

reforward An Akamai server can reforward a request to the origin server after receiving an error status response (for example, 403 Forbidden or 504 Gateway Timeout).

By default, an edge server also can identify whether an error response originated at the origin or at its hierarchy parent and take the appropriate action. If the error was generated by the origin, the edge server will not reforward the request directly to the origin, but instead it accepts the response as authoritative.

You can alter this behavior to have the edge server forward the request directly to the origin server, although there is generally no benefit to doing so.

refresh When the Akamai server receives a request for an object that is stale in cache, it will contact the origin server to refresh the object — that is, fetch a new version of the object from the origin, if a new version is available, and replace the stale cached version with the new one. This refresh is generally performed with an If-Modified-Since request.


Glossary

region A region is a collection of Akamai servers installed together at a data center and able to communicate directly with each other.

request ID A unique number assigned to a client request that is useful for problem solving and tracking.

request URL The URL of the content that the client originally requested.

revalidate, revalida-tion

Revalidation is a “refresh request.” An object that is stale in cache must be revalidated before it can be refreshed. (see also refresh). – check with the origin with an IMS to make sure the currently cached version isn’t stale.

Ssession A period that a user (client) or session ID is connected to a Web site. The site

administrator determines the length of time that defines a session – for example, 30 minutes. If a visitor leaves and returns to a site within that time span, it may still be considered just one session. The number of user sessions on a site is one way to measure the amount of traffic to it.

stages Internally the Akamai server applies metadata at several different stages of request and response processing. Knowing the point at which a metadata tag is used is primarily important when using the response.header condition.

stale Generally used in reference to a “stale object,” this describes an object whose Time-to-Live has expired.

static content For purposes of Akamai, dynamic content is any content that may vary based on some attribute of the request other than those normally used as part of the cache-key — for example, news headlines that change every hour. Static content does not vary this way — for example, the headline logo of a Web site. A page served is often composed of both static and dynamic content and might also contain personalized content.

stickiness The tendency for a client to maintain its connection with a particular origin server (usually enforced for a "session" but could be longer).

synchronous request This type of request includes a synchronous refresh, which means the refresh is done before serving the client (synchronously).

Ttiered distribution Tiered Distribution is a feature that instructs Akamai servers at the edge of the

Internet to fetch content from a parent Akamai server within a core region. The parent servers then fetch content from the origin server. By funneling edge requests through this smaller subset of server regions, Akamai can significantly reduce the amount of traffic on origin servers.


Glossary

timestamp The epoch time at which an object is placed in cache or made fresh in cache.

TTL TTL (time-to-live) is the time period for which an Akamai server may serve an object from cache without revalidating its freshness with the origin server.

typecode Typecodes are a mechanism for identifying features to be applied to a request made using a FreeFlow ARL (also called a v1 ARL). For example, the typecode can indicate that the ARL has been munged, that the ARL contains a TTL setting, or that the query string portion of the request should be ignored.

Vvalidation The process of confirming with the origin server that the object in cache may be

served as a valid response.

WWfetch A Microsoft program (wfetch.exe) for issuing HTTP requests and viewing the raw

response, including the status code and response headers.


Glossary


ESConfigGuide Customer

Documents

endorsement of akamai

names of akamai services

use of akamai services

akamai wave logo

client ip

client cookies

client ssl

client timeout